WdfCommonBufferCreateWithConfig 函数 (wdfcommonbuffer.h)

[仅适用于 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 后,驱动程序必须:

驱动程序通常从其 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)

另请参阅

EvtDriverDeviceAdd

WDF_COMMON_BUFFER_CONFIG

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreate

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate