WdfCommonBufferCreateWithConfig 函数 (wdfcommonbuffer.h)

项目
02/29/2024

[仅适用于 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

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

[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 指定的对齐要求不同的缓冲区，驱动程序可以使用 WdfCommonBufferCreateWithConfig 而不是 WdfCommonBufferCreate。

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

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

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

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

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

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

示例

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

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)
Library	Wdf01000.sys (请参阅框架库 Versioning.)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)