通过

WdfDmaEnablerCreate 函数 （wdfdmaenabler.h）

  • 项目

[仅适用于 KMDF]

WdfDmaEnablerCreate 方法创建 DMA 启用器对象。

语法

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 方法可能返回的其他返回值的列表，请参阅 Framework 对象创建错误。

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

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

注解

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

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

WdfDmaEnablerCreateDevice 参数指定的框架设备对象始终成为新 DMA 启用器对象的父对象。 如果驱动程序在 ParentObjectWDF_OBJECT_ATTRIBUTES 结构的成员中指定了不同的父级，框架将忽略此值。 框架在删除父对象时删除 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）
图书馆 Wdf01000.sys（请参阅框架库版本控制。
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