SerCx2SystemDmaTransmitCreate 函式 (sercx.h)

發行項
02/26/2024

SerCx2SystemDmaTransmitCreate 方法會建立 SerCx2 system-DMA-transmit 物件，其第 2 版的序列架構延伸模組 (SerCx2) 用來執行 system-DMA-transmit 交易。

語法

NTSTATUS SerCx2SystemDmaTransmitCreate(
  [in]           WDFDEVICE                          Device,
  [in]           PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES             Attributes,
  [out]          SERCX2SYSTEMDMATRANSMIT            *SystemDmaTransmit
);

參數

[in] Device

代表序列控制器之架構裝置物件的WDFDEVICE句柄。序列控制器驅動程式在其 EvtDriverDeviceAdd 回呼函式中建立了這個物件。如需詳細資訊，請參閱 SerCx2InitializeDevice。

[in] SystemDmaTransmitConfig

SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG 結構的指標。呼叫此方法之前，呼叫端必須呼叫 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT 函式來初始化結構。這個結構包含一組由序列控制器驅動程序實作的事件回呼例程指標。 SerCx2 會呼叫這些函式來執行 system-DMA-transmit 交易。

[in, optional] Attributes

WDF_OBJECT_ATTRIBUTES 結構的指標，描述要指派給新 system-DMA-transmit 對象的屬性。呼叫此方法之前，呼叫端必須呼叫 WDF_OBJECT_ATTRIBUTES_INIT 函式來初始化結構。此參數是選擇性的，如果序列控制器驅動程式不需要將屬性指派給物件，則可以指定為WDF_NO_OBJECT_ATTRIBUTES。如需詳細資訊，請參閱＜備註＞。

[out] SystemDmaTransmit

這個方法將 SERCX2SYSTEMDMATRANSMIT 句柄寫入新建立之 system-DMA-transmit 物件的位置指標。 SerCx2 和序列控制器驅動程式會在後續呼叫中使用這個句柄來參考這個物件。

傳回值

如果呼叫成功，這個方法會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列狀態代碼。

傳回碼	Description
STATUS_INVALID_DEVICE_REQUEST	來自先前 SerCx2SystemDmaTransmitCreate 呼叫的系統-DMA 傳輸對象已經存在;或來自先前呼叫 SerCx2CustomTransmitCreate 方法的自定義傳輸物件存在;或來自先前呼叫 SerCx2CustomReceiveCreate 方法的自定義接收物件;或 SerCx2PioTransmitCreate 尚未呼叫來建立 PIO 傳輸物件。
STATUS_INFO_LENGTH_MISMATCH	Config->Size 值不等於大小of (SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG) 。
STATUS_INVALID_PARAMETER	參數值無效。
STATUS_INSUFFICIENT_RESOURCES	資源不足，無法建立 system-DMA-transmit 物件。

備註

您的序列控制器驅動程式可以建立 system-DMA-transmit 物件。 SerCx2 會使用此物件來執行 system-DMA 傳輸交易，這是使用系統 DMA 控制器將數據寫入要傳輸之序列控制器的交易。

一般而言，序列控制器驅動程式會從其 EvtDevicePrepareHardware 回呼函式呼叫 SerCx2SystemDmaTransmitCreate。此函式會接收硬體資源清單，其中包含系統 DMA 通道。

序列控制器驅動程序必須先成功呼叫 SerCx2InitializeDevice 和 SerCx2PioTransmitCreate 方法，再呼叫 SerCx2SystemDmaTransmitCreate。

呼叫 SerCx2SystemDmaTransmitCreate 之前，序列控制器驅動程式必須呼叫 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT 函式，以初始化 SystemDmaTransmitConfig 所指向的SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG結構。此函式會將結構的下列成員設定為零：

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
排除

如有必要，序列控制器驅動程式可以在初始化函式傳回之後，將這些成員設定為非零值。不過，為了方便起見，如果這些成員為零， SerCx2SystemDmaTransmitCreate 會使用下列預設值：

如果 MaximumScatterGatherFragments 為零，SerCx2 會將散佈/收集清單中的元素數目上限設定為 ( (ULONG) -1) 。
如果 MinimumTransferUnitOverride 為零，SerCx2 會將最小傳輸單位設定為其預設值，這是在系統 DMA 控制器的 DMA_ADAPTER 結構中指定。如需此結構的詳細資訊，請參閱 WdfDmaEnablerWdmGetDmaAdapter。
如果 DmaAlignment 為零，SerCx2 會將對齊值設定為最小傳輸單位。如果 MinimumTransferUnitOverride 為零，則會使用預設的最小傳輸單位。
如果 MinimumTransactionLength 為零，SerCx2 會將交易長度下限設定為一個字節。
如果獨佔為零 (FALSE) ，則會停用獨佔模式。

如果呼叫驅動程式將 Exclusive 設定為 TRUE，MinimumTransferUnitOverride、DmaAlignment 和 MinimumTransactionLength 成員必須是零。如需詳細資訊，請參閱 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG。

如果實作回呼函式的指定組合無效， SerCx2SystemDmaTransmitCreate 會失敗並傳回STATUS_INVALID_PARAMETER。驅動程式必須實作所有三個或無 EvtSerCx2SystemDmaTransmitDrainFifo、 EvtSerCx2SystemDmaTransmitCancelDrainFifo 和 EvtSerCx2SystemDmaTransmitPurgeFifo 函式。

做為選項，序列控制器驅動程式可以使用 Attributes 參數來建立 system-DMA-transmit 對象的內容，以及提供指向 EvtCleanupCallback 和 EvtDestroyCallback 函式的指標，以準備要刪除的物件。如需詳細資訊，請參閱 WDF_OBJECT_ATTRIBUTES。

如果 Attributes 參數指向 WDF_OBJECT_ATTRIBUTES 結構，呼叫端不得覆寫 WDF_OBJECT_ATTRIBUTES_INIT 初始化函式寫入至這個結構的 ParentObject、 ExecutionLevel 和 SynchronizationScope 成員的值。

如需建立 system-DMA-transmit 對象的詳細資訊，請參閱 SERCX2SYSTEMDMATRANSMIT。如需 system-DMA 傳輸交易的詳細資訊，請參閱 SerCx2 System-DMA-Transmit Transactions。