SerCx2 Custom-Receive 交易

發行項
06/15/2023

某些序列控制器硬體可能會實作 PIO 或系統 DMA 以外的資料傳輸機制，以便從序列控制器讀取資料。序列控制器驅動程式可以支援自訂接收交易，讓此資料傳輸機制可供 SerCx2 使用。

若要啟動自訂接收交易，SerCx2 會呼叫驅動程式的 EvtSerCx2CustomReceiveTransactionStart 事件回呼函式，並提供做為參數的讀取 (IRP_MJ_READ) 要求和交易讀取緩衝區的描述。在此呼叫中，函式會起始交易並傳回。然後，驅動程式會負責完成交易並完成讀取要求。

建立自訂接收物件

在 SerCx2 可以呼叫任何序列控制器驅動程式的 EvtSerCx2CustomReceiveTransactionXxx** 函式之前，驅動程式必須呼叫 SerCx2CustomReceiveTransactionCreate 方法，以向 SerCx2 註冊這些函式。這個方法接受作為輸入參數的指標，指向包含驅動程式EvtSerCx2CustomReceiveTransactionXxx** 函式指標的SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG結構。

驅動程式必須實作下列兩個函式：

作為選項，驅動程式可以實作下列三個函式的任何或全部：

SerCx2CustomReceiveTransactionCreate方法會建立自訂接收物件，並提供呼叫驅動程式與SERCX2CUSTOMRECEIVETRANSACTION控制碼給這個物件。驅動程式的 EvtSerCx2CustomReceiveTransactionXxx** 函式全都會採用此控制碼作為其第一個參數。下列 SerCx2 方法會採用此控制碼作為其第一個參數：

硬體初始化和清除

某些序列控制器驅動程式可能需要在自訂接收交易開始時初始化序列控制器硬體，或在交易結束時清除序列控制器的硬體狀態。

如果驅動程式實作 EvtSerCx2CustomReceiveTransactionInitialize 事件回呼函式，SerCx2 會先呼叫此函式來初始化序列控制器，再啟動交易。如果實作， EvtSerCx2CustomReceiveTransactionInitialize 函式必須呼叫 SerCx2CustomReceiveTransactionInitializeComplete 方法，以在驅動程式完成初始化序列控制器時通知 SerCx2。

如果驅動程式實作 EvtSerCx2CustomReceiveTransactionCleanup 事件回呼函式，SerCx2 會呼叫此函式，以清除交易結束時的硬體狀態。如果實作， EvtSerCx2CustomReceiveTransactionInitialize 函式必須呼叫 SerCx2CustomReceiveTransactionCleanupComplete 方法，以在驅動程式完成清除序列控制器時通知 SerCx2。

新資料通知

作為選項，序列控制器驅動程式可以實作 EvtSerCx2CustomReceiveTransactionEnableNewDataNotification 事件回呼函式。如果實作，SerCx2 會使用此函式有效率地管理在處理做為自訂接收交易的讀取要求期間發生的時間間隔逾時。

如果序列控制器收到的兩個連續位元組之間的間隔超過用戶端指定的最大時間，就會發生間隔逾時。在周邊驅動程式將讀取要求傳送至 SerCx2 之後，除非從串列連線的周邊裝置收到至少一個位元組的資料之後，才會發生時間間隔逾時。從周邊裝置收到第一個位元組的資料抵達和收到第一個位元組資料之間的時間，可能比收到第一個位元組之後接收讀取要求其餘資料所需的時間還長。如需詳細資訊，請參閱 SERIAL_TIMEOUTS。

SerCx2 會在實作 時呼叫 EvtSerCx2CustomReceiveTransactionEnableNewDataNotification 函式，以啟用新的資料通知。如果啟用此通知，且序列控制器會從周邊裝置接收一或多個位元組的新資料，或已在接收 FIFO 中擁有資料，序列控制器驅動程式必須呼叫 SerCx2CustomReceiveTransactionNewDataNotification 方法來通知 SerCx2。

若要偵測可能的時間間隔逾時， SerCx2 會定期呼叫 EvtSerCx2CustomReceiveTransactionQueryProgress 事件回呼函式，以檢查先前間隔期間是否收到任何資料。 SerCx2 如何偵測第一個位元組的資料接收，取決於序列控制器驅動程式是否實作 EvtSerCx2CustomReceiveTransactionEnableNewDataNotification 函式。如果實作此函式，SerCx2 會呼叫函式來啟用新的資料通知，並在收到第一個資料位元組時由驅動程式通知。否則， SerCx2 會定期呼叫 EvtSerCx2CustomReceiveTransactionQueryProgress 函式來偵測收到第一個位元組，而且可能需要定期喚醒處理器進行這些呼叫。因此，實作 EvtSerCx2CustomReceiveTransactionEnableNewDataNotification 函式的驅動程式，不需要處理器經常喚醒，即可降低耗電量。

SerCx2 不會明確取消自訂接收交易的暫止新資料通知。不過，如果已啟用通知，且驅動程式必須基於下列其中一個原因完成相關聯的讀取要求，序列控制器驅動程式可能需要隱含地取消新的資料通知：

讀取要求逾時或已取消。
序列控制器即將結束 D0 裝置電源狀態，以進入低電源狀態。

驅動程式通常會呼叫 WdfRequestComplete 之類的方法來完成要求。驅動程式絕對不能在要求完成之後呼叫 SerCx2CustomReceiveTransactionNewDataNotification 。

存取要求物件

若要啟動自訂接收交易，SerCx2 會呼叫驅動程式的 EvtSerCx2CustomReceiveTransactionStart 函式，並將封裝在 WDFREQUEST 物件控制碼中) (相關聯的讀取要求傳遞至此函式作為參數。驅動程式負責呼叫 WdfRequestComplete 之類的方法，以在交易完成時完成此要求。除非可以立即完成要求，否則 EvtSerCx2CustomReceiveTransactionStart 函式傳回之前，驅動程式必須呼叫 WdfRequestMarkCancelableEx 之類的方法，將要求標示為可取消。

序列控制器驅動程式不得使用 WdfRequestRetrieveOutputBuffer 之類的方法來存取讀取要求中的資料緩衝區。相反地，驅動程式應該使用傳遞至EvtSerCx2CustomReceiveTransactionStart函式的Mdl、Offset和Length參數值來存取此緩衝區。

在自訂接收交易期間，驅動程式可能需要將交易的相關資訊儲存在附加至要求物件的內容中。如果是，驅動程式的 EvtDriverDeviceAdd 事件回呼函式可以呼叫 WdfDeviceInitSetRequestAttributes 方法，以設定要用於要求物件的屬性。這些屬性包括用於要求內容的名稱和配置大小。在此呼叫中指定的要求屬性必須符合驅動程式在呼叫 SerCx2InitializeDevice 方法中指定的要求屬性。這些屬性是在驅動程式傳遞至SerCx2InitializeDevice之SERCX2_CONFIG結構的RequestAttributes成員中指定。如需詳細資訊，請參閱 SERCX2_CONFIG。

對於串列控制器驅動程式在自訂接收交易開始時收到的讀取要求，驅動程式架構所配置的要求內容不會初始化。驅動程式應該最好呼叫 RtlZeroMemory 常式，將此要求內容初始化為所有零。

Share via