WdfDmaEnablerCreate 函式（wdfdmaenabler.h）

2025-03-22

[僅適用於 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	偵測到無效的參數。
資源不足狀態	記憶體不足，無法建構新的 DMA 啟用器物件。
STATUS_INFO_LENGTH_MISMATCH	WDF_DMA_ENABLER_CONFIG 結構的大小不正確。
STATUS_NOT_SUPPORTED	驅動程式在 Windows 8 之前的作系統上要求 DMA 第 3 版。

如需 WdfDmaEnablerCreate 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

此方法也可能傳回其他NTSTATUS 值。

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

備註

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

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

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

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

如需 DMA enabler 物件和 WdfDmaEnablerCreate的詳細資訊，請參閱啟用 DMA 交易。

範例

下列程式代碼範例來自 PLX9x5x5x 範例驅動程式。本範例會設定裝置對緩衝區對齊的需求、初始化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）