WdfDmaEnablerCreate 函数 (wdfdmaenabler.h)

  • 项目

[仅适用于 KMDF]

WdfDmaEnablerCreate 方法创建 DMA enabler 对象。

语法

NTSTATUS WdfDmaEnablerCreate(
  [in]           WDFDEVICE               Device,
  [in]           PWDF_DMA_ENABLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES  Attributes,
  [out]          WDFDMAENABLER           *DmaEnablerHandle
);

参数

[in] Device

框架设备对象的句柄。

[in] Config

指向 WDF_DMA_ENABLER_CONFIG 结构的指针。 驱动程序必须通过调用 WDF_DMA_ENABLER_CONFIG_INIT 来初始化此结构。

[in, optional] Attributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构指定新的 DMA 启用程序对象的对象属性。 此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[out] DmaEnablerHandle

新的 DMA 启用程序对象的句柄。

返回值

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

返回代码 说明
STATUS_INVALID_PARAMETER
 检测到参数无效。
STATUS_INSUFFICIENT_RESOURCES

内存不足，无法构造新的 DMA 启用程序对象。
STATUS_INFO_LENGTH_MISMATCH
 WDF_DMA_ENABLER_CONFIG结构的大小不正确。
STATUS_NOT_SUPPORTED
 驱动程序在早于 Windows 8 的操作系统上请求了 DMA 版本 3。
 

有关 WdfDmaEnablerCreate 方法可能返回的其他返回值的列表，请参阅 框架对象创建错误。

此方法还可能返回其他 NTSTATUS 值。

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

注解

在为设备创建 DMA 事务之前，基于框架的驱动程序必须调用 WdfDmaEnablerCreate 。

在驱动程序调用 WdfDmaEnablerCreate 之前，它必须调用 WdfDeviceSetAlignmentRequirement。

WdfDmaEnablerCreate 的 Device 参数指定的框架设备对象始终成为新 DMA 启用程序对象的父对象。 如果驱动程序在 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员中指定了不同的父级，则框架将忽略此值。 框架在删除父对象时删除 DMA 启用程序对象。

当使用请求系统模式 DMA 配置文件的 Config 参数调用时， WdfDmaEnablerCreate 会创建一个部分初始化的 DMA 启用程序。 驱动程序随后必须调用 WdfDmaEnablerConfigureSystemProfile 来设置基础通道的 DMA 设置。

有关 DMA 启用程序对象和 WdfDmaEnablerCreate 的详细信息，请参阅 启用 DMA 事务。

示例

下面的代码示例来自 PLX9x5x 示例驱动程序。 此示例设置设备的缓冲区对齐要求，初始化WDF_DMA_ENABLER_CONFIG结构，并调用 WdfDmaEnablerCreate。

//
// PLx PCI9656 DMA_TRANSFER_ELEMENTS must be 16-byte aligned.
//
WdfDeviceSetAlignmentRequirement(
                                 DevExt->WdfDevice,
                                 PCI9656_DTE_ALIGNMENT_16
                                 );

//
// Create a new DMA enabler object instance. 
// Use scatter/gather, 64-bit addresses, and duplex-type profile.
//
{
    WDF_DMA_ENABLER_CONFIG   dmaConfig;
    WDF_DMA_ENABLER_CONFIG_INIT(
                                &dmaConfig,
                                WdfDmaProfileScatterGather64Duplex,
                                DevExt->MaximumTransferLength
                                );
    status = WdfDmaEnablerCreate(
                                 DevExt->WdfDevice,
                                 &dmaConfig,
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 &DevExt->DmaEnabler
                                 );
    if (!NT_SUCCESS (status)) {
        // Cannot continue, so release device resources.
        return status;
    }
}

要求

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

另请参阅

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement