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

Статья
03/18/2023

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

Синтаксис

PALLOCATE_COMMON_BUFFER_EX PallocateCommonBufferEx;

PVOID PallocateCommonBufferEx(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in, optional] PPHYSICAL_ADDRESS MaximumAddress,
  [in]           ULONG Length,
  [out]          PPHYSICAL_ADDRESS LogicalAddress,
  [in]           BOOLEAN CacheEnabled,
  [in]           NODE_REQUIREMENT PreferredNode
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER . Эта структура представляет собой объект адаптера, представляющий master устройства DMA или системного канала DMA водителя. Вызывающий объект получил этот указатель из предыдущего вызова процедуры IoGetDmaAdapter .

[in, optional] MaximumAddress

Указатель на переменную, содержащую максимальный логический адрес общего буфера. Этот параметр указывает, что буфер должен быть выделен из памяти под этим адресом. Этот параметр является необязательным и может быть указан как NULL, чтобы указать, что максимальный адрес отсутствует.

[in] Length

Размер (в байтах) общего буфера, выделяемого для операции DMA.

[out] LogicalAddress

Указатель на переменную, в которую эта подпрограмма записывает логический адрес, который устройство может использовать для доступа к общему буферу. Устройство DMA должно использовать этот логический адрес вместо физического адреса, возвращаемого подпрограммой, такой как MmGetPhysicalAddress.

[in] CacheEnabled

Указывает, должна ли подпрограмма включать или отключать кэшированную память в общем буфере, который должен быть выделен. Если задано значение TRUE, кэширование включено. Если значение FALSE, оно отключено. Если аппаратная платформа не обеспечивает когерентность кэша для операций DMA, передайте значение FALSE. Сведения об этом параметре на компьютерах на базе ARM или ARM 64-разрядных процессоров см. в разделе Примечания.

[in] PreferredNode

Предпочтительный узел NUMA, из которого будет выделена память. Если N — это число узлов NUMA в многопроцессорной системе, PreferredNode — это число в диапазоне от 0 до N–1. Для однопроцессорной системы или многопроцессорной системы, отличной от NUMA, задайте для PreferredNode значение 0.

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

Функция AllocateCommonBufferEx возвращает виртуальный адрес памяти, выделенной для общего буфера. Если буфер не может быть выделен, возвращается значение NULL.

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

AllocateCommonBufferEx — это расширенная версия подпрограммы AllocateCommonBuffer . В следующем списке перечислены функции, доступные только в расширенной версии:

Вызывающий объект может указать максимальный логический адрес для общего буфера, который должен быть выделен.
Вызывающий объект может указать предпочтительный узел NUMA, в котором будет выделен общий буфер.

На компьютерах с процессорами arm или ARM 64 параметры кэша в системном ACPI имеют более высокий приоритет, чем значение параметра CacheEnabled, переданное драйвером. Если метод ACPI _CCA указывает, что устройство не является кэш-когерентным, операционная система отключает кэширование, даже если драйвер выделяет кэшированную память с параметром CacheEnabled, равным TRUE.

На компьютерах с процессорами arm или ARM 64 операционная система выделяет общий буфер без кэширования в качестве памяти устройства. Дополнительные сведения о буфере см. в разделах A3.5.1 и A3.5.6 справочного руководства по архитектуре ARMv7.

Процессор не разрешает неправильный доступ к памяти устройства. Драйвер всегда должен получать доступ к данным из общего буфера с помощью естественно выровненных операций. Большинство подпрограмм ядра не принимают память устройства в качестве входных параметров. Например, сетевой драйвер не может передать память устройства в NdisMIndicateReceiveNetBufferLists. Если драйверу необходимо передать данные из общего буфера DMA в подпрограмму ядра, выделите буфер с параметром CacheEnabled значение TRUE или скопируйте данные из общего буфера без кэширования во временное выделение пула.

Дополнительные сведения об операциях DMA, использующих общий буфер, см. в следующих разделах:

Использование общих буферов

Использование Common-Buffer Bus-Master DMA

Использование DMA системы Common-Buffer

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
IRQL	PASSIVE_LEVEL

См. также раздел