WdfCommonBufferCreateWithConfig 函数（wdfcommonbuffer.h）

项目
02/07/2025

[仅适用于 KMDF]

WdfCommonBufferCreateWithConfig 方法创建一个内存缓冲区，驱动程序和直接内存访问（DMA）设备都可以同时访问，并且该方法还指定缓冲区配置信息。

语法

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

参数

[in] DmaEnabler

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

[in] Length

新缓冲区的所需大小（以字节为单位）。

[in] Config

指向包含有关缓冲区的配置信息的 WDF_COMMON_BUFFER_CONFIG 结构的指针。

[in, optional] Attributes

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

[out] CommonBuffer

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

返回值

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

返回代码	描述
STATUS_INVALID_PARAMETER	驱动程序提供了无效参数。
STATUS_INSUFFICIENT_RESOURCES	框架无法分配通用缓冲区对象，或者系统无法分配缓冲区。

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

言论

WdfCommonBufferCreateWithConfig 方法分配内存并映射内存，以便驱动程序和设备都可以同时访问它以执行 DMA作。

此外，WdfCommonBufferCreateWithConfig 使驱动程序能够指定缓冲区的缓冲区对齐要求。缓冲区对齐要求将替代驱动程序在调用 WdfDeviceSetAlignmentRequirement时指定的缓冲区对齐要求。如果希望驱动程序创建与 WdfDeviceSetAlignmentRequirement 不同的缓冲区，驱动程序可以使用 WdfCommonBufferCreate，而不是 WdfCommonBufferCreate。

驱动程序调用 WdfCommonBufferCreateWithConfig后，驱动程序必须：

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

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

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

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

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

例子

下面的代码示例初始化 WDF_COMMON_BUFFER_CONFIG 结构，然后创建一个 10 字节缓冲区，该缓冲区在 32 字节边界上对齐。

WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

要求

要求	价值
目标平台	普遍
最低 KMDF 版本	1.1
标头	wdfcommonbuffer.h （包括 WdfCommonBuffer.h）
库	Wdf01000.sys（请参阅框架库版本控制。
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）