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

Статья
02/07/2025

Подпрограмма 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, представляющей адаптер шины или контроллер 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 главного шины.

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

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

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 2000.
целевая платформа	Настольный
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	irqlDispatch(wdm)

См. также

Поделиться через