функция обратного вызова PCREATE_COMMON_BUFFER_FROM_MDL (wdm.h)

Статья
08/08/2023

Подпрограмма CreateCommonBufferFromMdl попытается создать общий буфер из MDL, проверив совместимость доступа к устройствам и потенциально сопоставив память с непрерывным логическим диапазоном в зависимости от типа преобразования. Как и все другие распространенные функции выделения буферов, эта функция не обеспечивает гарантию хода выполнения.

Синтаксис

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Параметры

[in] DmaAdapter

Предоставляет указатель на адаптер DMA, выполняющий операцию.

[in] Mdl

Предоставляет MDL, который будет сопоставлен с общим буфером.

Чтобы MDL мог поддерживать общий буфер, должны быть выполнены следующие условия:

MDL должен содержать страницы, которые всегда находятся в течение всего времени существования общего буфера и сопоставлены с адресным пространством системы. Это можно сделать с помощью следующих подходов:
MDL создается из буфера в нестраничном пуле через MmBuildMdlForNonPagedPool.
MDL был заблокирован через MmProbeAndLockPages и сопоставлен с системным пространством с помощью MmGetSystemAddressForMdlSafe.
Физические страницы для MDL были выделены через MmAllocatePagesForMdlEx и сопоставлены с системным пространством с помощью MmGetSystemAddressForMdlSafe.
MDL должен представлять область, выравниваемую по страницам, и быть кратным PAGE_SIZE.
- Если используется расширенная конфигурация SubSection, то используемая часть MDL должна быть выровнена по страницам и кратна PAGE_SIZE.
MDL не должен быть цепной MDL.
- Если используется расширенная конфигурация SubSection, можно предоставить цепной MDL, но часть используемого MDL должна содержаться в одном MDL в цепочке.
Если переназначение DMA не используется, MDL должен представлять физически непрерывную память и быть доступным для устройства.

[in] ExtendedConfigs

Предоставляет необязательный массив структур DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION для дальнейшей настройки создания общего буфера на базе MDL.

Если в массиве указано несколько конфигураций одного и того же DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE , создание завершится ошибкой.

[in] ExtendedConfigsCount

Предоставляет количество расширенных конфигураций в массиве ExtendedConfigs .

[out] LogicalAddress

При успешном выполнении предоставляет логический адрес результирующего общего буфера.

Возвращаемое значение

CreateCommonBufferFromMdl возвращает STATUS_SUCCESS , если вызов выполнен успешно. Возможные возвращаемые значения ошибок включают следующие коды состояния.

Код возврата	Описание
STATUS_INVALID_PARAMETER	Вызывающий объект предоставил несовместимую MDL или расширенную конфигурацию.
STATUS_NOT_SUPPORTED	Вызывающий объект предоставил расширенную конфигурацию, которая не поддерживается в текущей системе.
STATUS_INSUFFICIENT_RESOURCES	В системе недостаточно памяти для создания метаданных логического учета и сопоставления.

CreateCommonBufferFromMdl не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в DMA_OPERATIONS структуре. Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter с элементом Version параметра DeviceDescription , равным DEVICE_DESCRIPTION_VERSION3. Если IoGetDmaAdapter возвращает значение NULL, подпрограмма недоступна на вашей платформе.

Общий буфер, созданный командой CreateCommonBufferFromMdl , будет удален с помощью FreeCommonBuffer. Вызывающий объект должен указать системный виртуальный адрес в качестве виртуального адреса, чтобы обеспечить правильное удаление общего буфера из структур учета общих буферов адаптера. Драйвер по-прежнему отвечает за разблокировку и освобождение MDL и его резервных страниц.

Чтобы создать общий буфер, в котором HAL отвечает за обслуживание резервной памяти, используйте AllocateCommonBufferWithBounds.

Требования

Требование	Значение
Минимальная версия сервера	Windows Server 2022
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h
IRQL	PASSIVE_LEVEL