EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER回呼函式 (sercx.h)

發行項
02/29/2024

EvtSerCx2PioTransmitWriteBuffer 事件回呼函式是由序列架構延伸模組第 2 版 (SerCx2) 呼叫，以使用程式化 I/O (PIO) ，將寫入緩衝區的內容傳送至序列控制器中的傳輸 FIFO。

語法

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER EvtSercx2PioTransmitWriteBuffer;

ULONG EvtSercx2PioTransmitWriteBuffer(
  [in] SERCX2PIOTRANSMIT PioTransmit,
  [in] PUCHAR Buffer,
  [in] ULONG Length
)
{...}

參數

[in] PioTransmit

PIO 傳輸物件的 SERCX2PIOTRANSMIT 句柄。序列控制器驅動程式先前稱為 SerCx2PioTransmitCreate 方法來建立這個物件。

[in] Buffer

寫入緩衝區的指標。此參數是系統記憶體中鎖定緩衝區的虛擬位址。

[in] Length

寫入緩衝區中可供傳輸的位元元組數目。

傳回值

EvtSerCx2PioTransmitWriteBuffer 函式會傳回成功從寫入緩衝區傳輸到序列控制器硬體中傳送 FIFO 的數據位元組數目。

備註

您的序列控制器驅動程序必須實作此函式。驅動程式會在建立 PIO 傳輸物件的 SerCx2PioTransmitCreate 呼叫中註冊函式。

SerCx2 可能會在 PIO 傳輸交易期間多次呼叫 EvtSerCx2PioTransmitWriteBuffer 函式。如果這個呼叫可以將寫入緩衝區的完整內容傳輸到傳輸 FIFO，則單一 EvtSerCx2PioTransmitWriteBuffer 呼叫就已足夠。否則，SerCx2 會繼續呼叫此函式，因為傳輸 FIFO 中有更多空間可供使用，直到寫入緩衝區已清空為止。

從寫入緩衝區中的第一個字節開始， EvtSerCx2PioTransmitWriteBuffer 函式會使用 PIO 將位元組數目從緩衝區傳輸到傳輸 FIFO。只要緩衝區不是空的，而且 行狀態緩存器 (LSR) 表示 FIFO 可以接受更多數據，函式就會繼續從緩衝區傳輸數據。如果 LSR 指出 FIFO 無法再接受任何數據，則函式會傳回，而不會清空緩衝區。否則，函式會傳輸緩衝區中的所有位元組，並傳回。不論是哪一種情況，此函式所傳回的值都是成功從寫入緩衝區傳送到傳輸 FIFO 的數據位元組數目。

一般而言， EvtSerCx2PioTransmitWriteBuffer 函式不會啟用任何中斷。相反地，如果函式無法將寫入緩衝區的整個內容傳送至傳輸 FIFO，SerCx2 會呼叫 EvtSerCx2PioTransmitEnableReadyNotification 事件回呼函式來啟用就緒通知，而此函式會啟用傳輸 FIFO 變成空白時所發生的中斷。

針對 EvtSerCx2PioTransmitWriteBuffer 函式的每個連續呼叫，SerCx2 會調整 Buffer 以指向緩衝區中的其餘數據，並將 Length 設定為緩衝區中剩餘的數據位元組數目。

當 SerCx2 呼叫 EvtSerCx2PioTransmitEnableReadyNotification 函式時，永遠不會啟用就緒通知。不過，SerCx2 可能會從驅動程式呼叫 SerCx2PioTransmitReady 方法的相同線程呼叫此函式。

如果驅動程序實作 EvtSerCx2PioTransmitInitializeTransaction 函式，SerCx2 會在 PIO 傳輸交易開始時呼叫此函式，然後再呼叫 EvtSerCx2PioTransmitWriteBuffer 函式。如果驅動程序實作 EvtSerCx2PioTransmitCleanupTransaction 函式， SerCx2 會在 PIO 傳輸交易結束時呼叫此函式、最後一個 EvtSerCx2PioTransmitWriteBuffer 呼叫之後，以及在實作 EvtSerCx2PioTransmitDrainFifo、 EvtSerCx2PioTransmitCancelDrainFifo 和 EvtSerCx2PioTransmitPurgeFifo 函式之後呼叫此函式。

如需 PIO 傳輸交易的詳細資訊，請參閱 SerCx2 PIO-Transmit Transactions。

範例

若要定義 EvtSerCx2PioTransmitWriteBuffer 回呼函式，您必須先提供函式宣告來識別您要定義的回呼函式類型。 Windows 提供一組驅動程式的回呼函式類型。使用回呼函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證器 (SDV) ，以及其他驗證工具會尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為 MyPioTransmitWriteBuffer的 EvtSerCx2PioTransmitWriteBuffer 回呼函式，請使用 EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER 函式類型，如下列程式代碼範例所示：

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER  MyPioTransmitWriteBuffer;

然後，實作您的回呼函式，如下所示：

_Use_decl_annotations_
ULONG
  MyPioTransmitWriteBuffer(
    SERCX2PIOTRANSMIT  PioTransmit,
    PUCHAR Buffer,
    ULONG Length
    )
  {...}

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER函式類型定義於 Sercx.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 註釋新增至函式定義。 Use_decl_annotations註釋可確保使用頭檔中套用至EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER函式類型的批註。如需函數宣告需求的詳細資訊，請參閱使用 KMDF 驅動程式的函式角色類型來宣告函式。如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。