WdfCommonBufferCreate 函数 （wdfcommonbuffer.h）

[仅适用于 KMDF]

WdfCommonBufferCreate 方法创建一个内存缓冲区，驱动程序和直接内存访问（DMA）设备都可以同时访问。

语法

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

参数

[in] DmaEnabler

一个 DMA 启用器对象的句柄，该对象由之前调用 WdfDmaEnablerCreate获取的驱动程序。

[in] Length

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

[in, optional] Attributes

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

[out] CommonBuffer

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

返回值

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

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

言论

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

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

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

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

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

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

WdfCommonBufferCreateDmaEnabler 参数指定的 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); 
}

要求

另请参阅

EvtDriverDeviceAdd

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreateWithConfig

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate