функция обратного вызова PALLOCATE_COMMON_BUFFER_EX (wdm.h)
Подпрограмма 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. Эта структура — это объект адаптера, представляющий основное устройство 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 равным нулю.
Возвращаемое значение
AllocateCommonBufferEx возвращает виртуальный адрес памяти, выделенной для общего буфера. Если буфер не может быть выделен, возвращается значение NULL.
Замечания
AllocateCommonBufferEx не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в DMA_OPERATIONS структуре. Драйверы получают адрес этой подпрограммы путем вызова IoGetDmaAdapter с членом версии параметра deviceDescription, равным DEVICE_DESCRIPTION_VERSION3. Если IoGetDmaAdapter возвращает NULL, подпрограмма недоступна на вашей платформе.
AllocateCommonBufferEx — расширенная версия подпрограммы AllocateCommonBuff er. В следующем списке перечислены функции, доступные только в расширенной версии:
Вызывающий объект может указать максимальный логический адрес для общего буфера, который должен быть выделен.
Вызывающий объект может указать предпочтительный узел NUMA, в котором должен быть выделен общий буфер.
На компьютерах с процессорами на основе ARM или ARM 64 параметры кэша в системе ACPI имеют более высокий приоритет, чем значение параметра CacheEnabled, переданное драйвером. Если метод acPI _CCA ACPI указывает, что устройство не кэшируется, операционная система отключает кэширование, даже если драйвер выделяет кэшированную память с 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 (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | PASSIVE_LEVEL |