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

Подпрограмма 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, если вызов выполнен успешно. Возможные значения возвращаемых ошибок включают следующие коды состояния.

Замечания

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

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

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

Требования

См. также

DMA_ADAPTER

DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION

DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter

PALLOCATE_COMMON_BUFFER_WITH_BOUNDS