WdfDmaEnablerCreate 函式 (wdfdmaenabler.h)

發行項
02/27/2024

[僅適用於 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

指定新 DMA 啟用器物件之物件屬性之WDF_OBJECT_ATTRIBUTES 結構的指標。這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out] DmaEnablerHandle

新 DMA 啟用表示式物件的句柄。

傳回值

如果作業成功，WdfDmaEnablerCreate 會傳回STATUS_SUCCESS。否則，方法可能會傳回下列其中一個值。

傳回碼	Description
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值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

架構型驅動程序必須先呼叫 WdfDmaEnablerCreate ，才能為裝置建立 DMA 交易。

在驅動程式呼叫 WdfDmaEnablerCreate 之前，它必須呼叫 WdfDeviceSetAlignmentRequirement。

WdfDmaEnablerCreate 的 Device 參數所指定的架構裝置物件，一律會成為新 DMA 啟用器物件的父物件。如果驅動程式在 WDF_OBJECT_ATTRIBUTES 結構的 ParentObject 成員中指定不同的父代，架構會忽略此值。架構會在刪除父物件時刪除 DMA enabler 物件。

使用要求系統模式 DMA 設定檔的 Config 參數呼叫時， WdfDmaEnablerCreate 會建立部分初始化的 DMA 啟用程式。驅動程式後續必須呼叫 WdfDmaEnablerConfigureSystemProfile ，才能設定基礎通道的 DMA 設定。

如需 DMA enabler 物件和 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;
    }
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
標頭	wdfdmaenabler.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)