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

Статья
08/08/2023

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

Синтаксис

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

PVOID PallocateCommonBuffer(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  ULONG Length,
  [out] PPHYSICAL_ADDRESS LogicalAddress,
  [in]  BOOLEAN CacheEnabled
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER, возвращаемую IoGetDmaAdapter, которая представляет адаптер master шины или контроллер DMA.

[in] Length

Указывает количество байтов памяти для выделения.

[out] LogicalAddress

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

[in] CacheEnabled

Указывает, можно ли кэшировать выделенную память.

Этот параметр не учитывается. Операционная система определяет, следует ли включать кэшированную память в общем буфере, который должен быть выделен. Это решение основано на архитектуре процессора и шине устройства.

На компьютерах с процессорами x86, x64 и Itanium включена кэшированная память. Предполагается, что все операции DMA, выполняемые устройством, согласованы с соответствующими кэшами ЦП, которые могут кэшировать эту память. Если драйверу необходимо отключить кэширование, вместо этого вызовите Метод AllocateCommonBufferEx .

На компьютерах с процессорами на основе ARM или ARM 64 операционная система не включает кэшированную память для всех устройств автоматически. Система использует метод ACPI_CCA для каждого устройства, чтобы определить, является ли устройство когерентным в кэше.

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

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

AllocateCommonBuffer не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращенного в структуре DMA_OPERATIONS . Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter.

AllocateCommonBuffer поддерживает DMA, в котором устройство и процессор непрерывно обмениваются данными через системную память, как в структуре управления для устройства DMA с master шины.

AllocateCommonBuffer также поддерживает подчиненные устройства, драйверы которых используют режим автоматической инициализации системного контроллера DMA.

AllocateCommonBuffer выполняет следующие действия:

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

Чтобы использовать память резидентной системы с точки зрения экономии, драйверы должны выделять как можно меньше этих буферов для каждого устройства. AllocateCommonBuffer выделяет по крайней мере страницу памяти независимо от запрошенной длины. После успешного выделения, запрашивающего менее PAGE_SIZE байтов, вызывающий объект может получить доступ только к запрошенной длине. После успешного выделения, запрашивающего больше целочисленного кратного PAGE_SIZE байтов, все оставшиеся байты на последней выделенной странице становятся недоступными вызывающей стороне.

Если драйверу требуется несколько страниц общего буферного пространства, но страницы не должны быть смежными, драйвер должен выполнить несколько одностраничных запросов к AllocateCommonBuffer вместо одного большого запроса. Такой подход обеспечивает экономию непрерывной памяти.

Драйверы обычно вызывают AllocateCommonBuffer при запуске устройства во время ответа на запрос IRP_MN_START_DEVICE PnP. После запуска возможно, что будут выполнены только одностраничные запросы, если таковые будут выполнены.

Требования

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

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