WdfDmaEnablerConfigureSystemProfile 函式（wdfdmaenabler.h）

2025-03-22

[僅適用於 KMDF]

WdfDmaEnablerConfigureSystemProfile 方法會設定系統模式 DMA 啟用程式的硬體特定設定，並完成資源初始化。

語法

NTSTATUS WdfDmaEnablerConfigureSystemProfile(
  [in] WDFDMAENABLER                  DmaEnabler,
  [in] PWDF_DMA_SYSTEM_PROFILE_CONFIG ProfileConfig,
  [in] WDF_DMA_DIRECTION              ConfigDirection
);

參數

[in] DmaEnabler

DMA enabler 物件的句柄。

[in] ProfileConfig

WDF_DMA_SYSTEM_PROFILE_CONFIG 結構的指標。驅動程式必須藉由呼叫 WDF_DMA_SYSTEM_PROFILE_CONFIG_INIT來初始化這個結構。

[in] ConfigDirection

WDF_DMA_DIRECTION型別值，指定 DMA 傳輸作業的方向。如果此啟用器的 WDF_DMA_PROFILE 值未 WdfDmaProfileSystemDuplex，則架構會忽略此參數。

返回值

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

回傳碼	說明
STATUS_NOT_SUPPORTED	驅動程式要求目前作系統不支援的 DMA 組態。
STATUS_INVALID_PARAMETER	驅動程式在 ProfileConfig 參數中提供 NULL。
STATUS_INFO_LENGTH_MISMATCH	ProfileConfig 參數所指向之結構 Size 成員不等於 WDF_DMA_SYSTEM_PROFILE_CONFIG 結構的大小。
STATUS_INVALID_PARAMETER	ProfileConfig 參數所指向之結構的 DmaDescriptor 成員為 NULL，或 ConfigDirection 參數包含無效的值。

備註

在呼叫 WdfDmaEnablerConfigureSystemProfile之前，驅動程式必須呼叫 WdfDmaEnablerCreate 來建立 enabler 物件。

驅動程式通常會從其 EvtDevicePrepareHardware 回呼函式呼叫 WdfDmaEnablerConfigureSystemProfile。

如果您的驅動程式在呼叫 WdfDmaEnablerCreate時指定雙工配置檔，則 WdfDmaEnablerConfigureSystemProfile 方法的 ConfigDirection 參數值必須 WdfDmaDirectionReadFromDevice，才能取得讀取作業的 DMA_ADAPTER 結構，WdfDmaDirectionWriteToDevice，以取得寫入作業的 DMA_ADAPTER 結構。

如果 DMA 啟用器是雙工啟用程式，驅動程式必須先初始化特定方向，才能使用它。

如果您的驅動程式未指定雙工配置檔，驅動程式可以指定 WdfDmaDirectionReadFromDevice 或 WdfDmaDirectionWriteToDevice。

範例

下列程式代碼範例來自驅動程式的 EvtDevicePrepareHardware 回呼函式。此範例會初始化 WDF_DMA_SYSTEM_PROFILE_CONFIG 結構，並呼叫 WdfDmaEnablerConfigureSystemProfile。


WDF_DMA_SYSTEM_PROFILE_CONFIG systemDmaConfig;  
PHYSICAL_ADDRESS pa;  
 
pa.QuadPart = 0;  
  
WDF_DMA_SYSTEM_PROFILE_CONFIG_INIT(&systemDmaConfig,   
                                   pa,  
                                   Width8Bits,  
                                   partial);  
  
systemDmaConfig.DemandMode = true;  
 
ntStatus = WdfDmaEnablerConfigureSystemProfile(fdoExtension->DmaEnabler,   
                                               &systemDmaConfig,   
                                               WdfDmaDirectionReadFromDevice);

需求

要求	價值
最低支援的用戶端	Windows 8
目標平臺	普遍
最低 KMDF 版本	1.11
標題	wdfdmaenabler.h （包括 Wdf.h）
程式庫	Wdf01000.sys （請參閱架構連結庫版本控制。）
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate（kmdf）