SerCx2SystemDmaReceiveCreate 函式 (sercx.h)
SerCx2SystemDmaReceiveCreate 方法會建立 SerCx2 system-DMA-receive 物件,這是 SerCx2 (SerCx2) 用來執行 system-DMA-receive 交易的第 2 版。
語法
NTSTATUS SerCx2SystemDmaReceiveCreate(
[in] WDFDEVICE Device,
[in] PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] SERCX2SYSTEMDMARECEIVE *SystemDmaReceive
);
參數
[in] Device
代表序列控制器之架構裝置物件的WDFDEVICE句柄。 序列控制器驅動程式在其 EvtDriverDeviceAdd 回呼函式中建立了這個物件。 如需詳細資訊,請參閱 SerCx2InitializeDevice。
[in] SystemDmaReceiveConfig
SERCX2_SYSTEM_DMA_RECEIVE_CONFIG 結構的指標。 呼叫此方法之前,呼叫端必須呼叫 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT 或 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 函式來初始化 結構。 這個結構包含一組由序列控制器驅動程序實作的事件回呼例程指標。 SerCx2 會呼叫這些函式來執行 system-DMA-receive 交易。
[in, optional] Attributes
描述要指派給新 system-DMA-receive 對象的屬性 之WDF_OBJECT_ATTRIBUTES 結構的指標。 呼叫此方法之前,呼叫端必須呼叫 WDF_OBJECT_ATTRIBUTES_INIT 函式來初始化 結構。 此參數是選擇性的,如果序列控制器驅動程式不需要將屬性指派給物件,則可以指定為WDF_NO_OBJECT_ATTRIBUTES。 如需詳細資訊,請參閱<備註>。
[out] SystemDmaReceive
這個方法寫入新建立之 system-DMA-receive 物件 之SERCX2SYSTEMDMARECEIVE 句柄的位置指標。 SerCx2 和序列控制器驅動程式會在後續呼叫中使用這個句柄來參考這個物件。
傳回值
如果呼叫成功,這個方法會傳回STATUS_SUCCESS。 可能的錯誤傳回值包括下列狀態代碼。
傳回碼 | Description |
---|---|
|
來自先前 SerCx2SystemDmaReceiveCreate 呼叫的 system-DMA-receive 對象已經存在;或自定義接收物件已存在於先前呼叫 SerCx2CustomReceiveCreate 方法時;或來自先前呼叫 SerCx2CustomTransmitCreate 方法的自定義傳輸物件存在;或 SerCx2PioReceiveCreate 尚未呼叫來建立 PIO 接收物件。 |
|
Config->Size 值不等於大小of (SERCX2_SYSTEM_DMA_RECEIVE_CONFIG) 。 |
|
參數值無效。 |
|
資源不足,無法執行要求的作業。 |
備註
串行控制器驅動程式會呼叫這個方法,以建立 system-DMA-receive 物件。 SerCx2 使用此對象來執行 system-DMA-receive 交易,也就是使用系統 DMA 控制器讀取序列控制器所接收數據的 I/O 交易。
一般而言,序列控制器驅動程式會從其 EvtDevicePrepareHardware 回呼函式呼叫 SerCx2SystemDmaReceiveCreate。 此函式會接收硬體資源清單,其中包含系統 DMA 通道。
序列控制器驅動程序必須先成功呼叫 SerCx2InitializeDevice 和 SerCx2PioReceiveCreate 方法,再呼叫 SerCx2SystemDmaReceiveCreate。
呼叫 SerCx2SystemDmaReceiveCreate 之前,序列控制器驅動程式必須呼叫 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT 或 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 函式,以初始化 SystemDmaReceiveConfig 所指向的SERCX2_SYSTEM_DMA_RECEIVE_CONFIG結構。 這些函式會將 結構的下列成員設定為零:
- MaximumScatterGatherFragments
- MinimumTransferUnitOverride
- DmaAlignment
- MinimumTransactionLength
- 排除
- 如果 MaximumScatterGatherFragments 為零,SerCx2 會將散佈/收集清單中的元素數目上限設定為 ( (ULONG) -1) 。
- 如果 MinimumTransferUnitOverride 為零,SerCx2 會將最小傳輸單位設定為其預設值,這是在系統 DMA 控制器 的 DMA_ADAPTER 結構中指定。 如需此結構的詳細資訊,請參閱 WdfDmaEnablerWdmGetDmaAdapter。
- 如果 DmaAlignment 為零,SerCx2 會將對齊值設定為最小傳輸單位。 如果 MinimumTransferUnitOverride 為零,則會使用預設的最小傳輸單位。
- 如果 MinimumTransactionLength 為零,SerCx2 會將交易長度下限設定為一個字節。
- 如果 獨佔 為零 (FALSE) ,則會停用獨佔模式。
如果實作回呼函式的指定組合無效, SerCx2SystemDmaReceiveCreate 會失敗並傳回STATUS_INVALID_PARAMETER。 驅動程式必須同時實作 EvtSerCx2SystemDmaReceiveEnableNewDataNotification 和 EvtSerCx2SystemDmaReceiveCancelNewDataNotification 函式。
做為選項,序列控制器驅動程式可以使用 Attributes 參數來建立 system-DMA-receive 對象的內容,並提供指向 EvtCleanupCallback 和 EvtDestroyCallback 函式的指標,以準備要刪除的物件。 如需詳細資訊,請參閱 WDF_OBJECT_ATTRIBUTES。
如果 Attributes 參數指向 WDF_OBJECT_ATTRIBUTES 結構,呼叫端不得覆寫 WDF_OBJECT_ATTRIBUTES_INIT 初始化函式寫入至這個結構的 ParentObject、 ExecutionLevel 和 SynchronizationScope 成員的值。
如需建立 system-DMA-receive 對象的詳細資訊,請參閱 SERCX2SYSTEMDMARECEIVE。 如需 system-DMA-receive 交易的詳細資訊,請參閱 SerCx2 System-DMA-Receive Transactions。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | 從 Windows 8.1 開始提供。 |
目標平台 | Universal |
標頭 | sercx.h |
IRQL | PASSIVE_LEVEL |
另請參閱
EvtSerCx2SystemDmaReceiveCancelNewDataNotification
EvtSerCx2SystemDmaReceiveCleanupTransaction
EvtSerCx2SystemDmaReceiveEnableNewDataNotification
EvtSerCx2SystemDmaReceiveInitializeTransaction
SERCX2_SYSTEM_DMA_RECEIVE_CONFIG
SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應