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 结构的指针。此结构是表示驱动程序的总线主 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 参数的 Version 成员设置为 DEVICE_DESCRIPTION_VERSION3。如果 IoGetDmaAdapter 返回 NULL，则例程在平台上不可用。

AllocateCommonBufferEx 是 AllocateCommonBuffer 例程的扩展版本。以下列表汇总了仅在扩展版本中可用的功能：

调用方可以为要分配的公共缓冲区指定最大逻辑地址。
调用方可以指定要在其中分配公共缓冲区的首选 NUMA 节点。

在具有基于 ARM 或 ARM 64 的处理器的计算机上，系统 ACPI 中的缓存设置的优先级高于驱动程序传递的 CacheEnabled 参数值。如果 ACPI _CCA 方法指示设备缓存不一致，则即使驱动程序分配缓存内存且 CacheEnabled 设置为 TRUE，操作系统也会禁用缓存。

在具有基于 ARM 或 ARM 64 的处理器的计算机上，操作系统将未缓存的通用缓冲区分配为设备内存。有关缓冲区的详细信息，请参阅 ARMv7 体系结构参考手册中的 A3.5.1 和 A3.5.6 部分。

处理器不允许对设备内存进行未对齐的访问。驱动程序必须始终使用自然对齐的操作从公共缓冲区访问数据。大多数内核例程不接受设备内存作为输入参数。例如，网络驱动程序无法将设备内存传递到 NdisMIndicateReceiveNetBufferLists。如果驱动程序需要将数据从 DMA 公共缓冲区传递到内核例程，请分配缓存设置为 TRUE 的缓冲区，或将数据从未缓存的公共缓冲区复制到临时池分配中。

有关使用公共缓冲区的 DMA 操作的详细信息，请参阅以下主题：

使用常用缓冲区

使用公用缓冲区总线主控 DMA

使用公用缓冲区系统 DMA