PALLOCATE_COMMON_BUFFER回调函数 (wdm.h)

  • 项目

AllocateCommonBuffer 例程分配内存并映射内存，以便同时从处理器和设备访问内存，以便执行 DMA 操作。

语法

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

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

参数

[in] DmaAdapter

指向 IoGetDmaAdapter 返回的 DMA_ADAPTER 结构的指针，该结构表示总线-主适配器或 DMA 控制器。

[in] Length

指定要分配的内存字节数。

[out] LogicalAddress

指向变量的指针，该变量接收设备可用于访问分配的缓冲区的逻辑地址。 使用此地址而不是调用 MmGetPhysicalAddress ，因为系统可以考虑任何特定于平台的内存限制。

[in] CacheEnabled

指定是否可以缓存分配的内存。

忽略此参数。 操作系统确定是否在要分配的公共缓冲区中启用缓存内存。 该决策基于处理器体系结构和设备总线。

在具有基于 x86、基于 x64 和基于 Itanium 的处理器的计算机上，将启用缓存内存。 假设设备执行的所有 DMA 操作都与相关的 CPU 缓存（可能正在缓存该内存）保持一致。 如果驱动程序需要禁用缓存，请改为调用 AllocateCommonBufferEx 。

在具有基于 ARM 或 ARM 64 的处理器的计算机上，操作系统不会自动为所有设备启用缓存内存。 系统依赖于每个设备的 ACPI_CCA 方法来确定设备是否与缓存一致。

返回值

AllocateCommonBuffer 返回已分配范围的基虚拟地址。 如果无法分配缓冲区，则返回 NULL。

注解

AllocateCommonBuffer 不是可直接按名称调用的系统例程。 此例程只能由 DMA_OPERATIONS 结构中返回的地址中的指针调用。 驱动程序通过调用 IoGetDmaAdapter 获取此例程的地址。

AllocateCommonBuffer 支持 DMA，其中设备和处理器通过系统内存持续通信，就像在总线主 DMA 设备的控制结构中一样。

AllocateCommonBuffer 还支持其驱动程序使用系统 DMA 控制器的自动初始化模式的从属设备。

AllocateCommonBuffer 执行以下操作：

  • 分配可从处理器和设备访问的内存。 此内存与设备相邻。
  • 分配映射寄存器以映射缓冲区（如果系统需要）。
  • 设置设备的转换，包括在必要时加载映射寄存器。
若要经济地使用驻留系统内存，驱动程序应为每个设备分配尽可能少的缓冲区。 无论请求的长度如何，AllocateCommonBuffer 都会分配至少一页内存。 成功分配请求少于 PAGE_SIZE 个字节后，调用方只能访问请求的 Length。 成功分配请求超过PAGE_SIZE个字节的整数倍数后，调用方无法访问上次分配的页上的任何剩余字节。

如果驱动程序需要多页公共缓冲区空间，但页不需要连续，则驱动程序应向 AllocateCommonBuffer 发出多个单页请求，而不是向一个大型请求发出。 此方法可节省连续内存。

驱动程序通常在响应 PnP IRP_MN_START_DEVICE请求期间调用 AllocateCommonBuffer 作为设备启动的一部分。 启动后，可能只有单页请求成功（如果有）。

要求

要求 值
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 桌面
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL PASSIVE_LEVEL
DDI 符合性规则 IrqlDispatch (wdm)

另请参阅

DMA_ADAPTER

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter