WdfCommonBufferCreate 函数 (wdfcommonbuffer.h)

项目
08/08/2023

[仅适用于 KMDF]

WdfCommonBufferCreate 方法创建驱动程序和直接内存访问 (DMA) 设备可以同时访问的内存缓冲区。

语法

NTSTATUS WdfCommonBufferCreate(
  [in]           WDFDMAENABLER          DmaEnabler,
  [in]           size_t                 Length,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFCOMMONBUFFER        *CommonBuffer
);

参数

[in] DmaEnabler

驱动程序通过上一次调用 WdfDmaEnablerCreate 获取的 DMA 启用程序对象的句柄。

[in] Length

新缓冲区的所需大小（以字节为单位）。允许的最大缓冲区大小 (MAXULONG - PAGE_SIZE) 字节。

[in, optional] Attributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构指定公共缓冲区对象的对象属性。 (结构的 ParentObject 成员必须为 NULL。) 此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[out] CommonBuffer

指向 WDFCOMMONBUFFER 类型变量的指针，该变量接收公共缓冲区对象的句柄。

返回值

如果操作成功，WdfCommonBufferCreate 将返回STATUS_SUCCESS。否则，此方法可能会返回以下值之一：

返回代码	说明
STATUS_INVALID_PARAMETER	驱动程序提供的参数无效。
STATUS_INSUFFICIENT_RESOURCES	框架无法分配公共缓冲区对象，或者系统无法分配缓冲区。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

WdfCommonBufferCreate 方法分配并映射内存，以便驱动程序和设备可以同时访问它以执行 DMA 操作。驱动程序调用 WdfCommonBufferCreate 后，驱动程序必须：

调用 WdfCommonBufferGetAlignedVirtualAddress 以获取驱动程序可以使用的缓冲区的虚拟地址。
调用 WdfCommonBufferGetAlignedLogicalAddress 以获取设备可以使用的缓冲区的逻辑地址。

驱动程序通常从其 EvtDriverDeviceAdd 回调函数中调用 WdfCommonBufferCreate。

在驱动程序调用 WdfDmaEnablerCreate 之前，它可以调用 WdfDeviceSetAlignmentRequirement 来设置缓冲区对齐要求。如果驱动程序不调用 WdfDeviceSetAlignmentRequirement，则缓冲区在字边界上对齐。如果驱动程序创建了多个 DMA 启用程序，每个启用程序都有不同的缓冲区对齐要求，则驱动程序可以在每次调用 WdfDmaEnablerCreate 之前调用 WdfDeviceSetAlignmentRequirement。

若要创建一个具有与驱动程序使用 WdfDeviceSetAlignmentRequirement 指定的对齐要求不同的对齐要求的公共缓冲区，驱动程序可以调用 WdfCommonBufferCreateWithConfig ，而不是 WdfCommonBufferCreate。

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

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

WdfCommonBufferCreate 的 DmaEnabler 参数指定的 DMA 启用器对象将成为新的公共缓冲区对象的父对象。驱动程序无法更改此父级，并且 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员必须为 NULL。框架在删除父 DMA 启用程序对象时删除每个公共缓冲区对象。或者，可以通过调用 WdfObjectDelete 显式删除公共缓冲区对象。

有关常见缓冲区的详细信息，请参阅使用通用缓冲区。

示例

下面的代码示例演示如何获取通用缓冲区。该示例将有关常见缓冲区的信息存储在 由 DevExt 指针标识的驱动程序定义的上下文空间中。

DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
标头	wdfcommonbuffer.h (包括 WdfCommonBuffer.h)
Library	Wdf01000.sys (请参阅框架库 Versioning.)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)