共用方式為

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER回呼函式 （sercx.h）

  • 發行項

EvtSerCx2PioReceiveReadBuffer 事件回呼函式是由序列架構延伸模組 （SerCx2） 第 2 版呼叫，以使用程式化 I/O （PIO） 將數據從序列控制器中的接收 FIFO 傳輸到讀取緩衝區。

語法

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

參數

[in] PioReceive

PIO 接收物件的 SERCX2PIORECEIVE 句柄。 序列控制器驅動程式先前稱為 SerCx2PioReceiveCreate 方法來建立這個物件。

[out] Buffer

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

[in] Length

讀取緩衝區中可用來儲存已接收數據的位元組數目。

傳回值

EvtSerCx2PioReceiveReadBuffer 函式會傳回成功從序列控制器硬體中接收 FIFO 傳送到讀取緩衝區的數據位元組數目。

言論

您的序列控制器驅動程序必須實作此函式。 驅動程式會在 SerCx2PioReceiveCreate 呼叫中註冊函式，以建立 PIO-receive 物件。

SerCx2 可能會在 PIO 接收交易期間多次呼叫 EvtSerCx2PioReceiveReadBuffer 函式。 單一 EvtSerCx2PioReceiveReadBuffer 呼叫就已足夠，如果這個呼叫可以使用接收 FIFO 中的數據填入讀取緩衝區。 否則，SerCx2 會繼續呼叫此函式，因為接收 FIFO 中有更多數據可供使用，直到讀取緩衝區填滿為止。

EvtSerCx2PioReceiveReadBuffer 函式會使用 PIO 將接收 FIFO 中的位元元組數目傳輸至讀取緩衝區。 只要傳遞至此函式的緩衝區未滿，而且行狀態緩存器 （LSR） 表示 FIFO 有更多數據可供使用，函式就會繼續從 FIFO 傳輸數據。 如果 LSR 指出 FIFO 是空的，函式會傳回而不填滿緩衝區。 否則，函式會填滿緩衝區並傳回 。 不論是哪一種情況，此函式傳回的值都是成功從接收 FIFO 傳送至讀取緩衝區的數據位元組數目。

一般而言，EvtSerCx2PioReceiveReadBuffer 函式不會啟用任何中斷。 相反地，如果接收 FIFO 在函式可以填滿讀取緩衝區之前用盡數據，SerCx2 會呼叫 EvtSerCx2PioReceiveEnableReadyNotification 事件回呼函式來啟用就緒通知，而且此函式會啟用在接收 FIFO 中提供更多數據時發生的中斷。

針對每個連續呼叫 EvtSerCx2PioReceiveReadBuffer 函式，SerCx2 會調整 Buffer，以指向要填滿的下一個緩衝區區域，並將 Length 設定為緩衝區中未填入空間的位元組數。

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

如果驅動程式實作 EvtSerCx2PioReceiveInitializeTransaction 函式，則 SerCx2 會在 PIO 傳輸交易開始時呼叫此函式，再呼叫 EvtSerCx2PioReceiveReadBuffer 函式。 如果驅動程式實作 EvtSerCx2PioReceiveCleanupTransaction 函式，則 SerCx2 會在 PIO 接收交易結尾呼叫此函式，最後呼叫 EvtSerCx2PioReceiveReadBuffer 函式。

除了在 PIO 接收交易期間呼叫 EvtSerCx2PioReceiveReadBuffer 函式之外，SerCx2 也會呼叫此函式，以在序列控制器結束 D0 裝置電源狀態之前儲存接收 FIFO 的狀態。 如需詳細資訊，請參閱 SerCx2SaveReceiveFifoOnD0Exit。

如需 PIO 接收交易的詳細資訊，請參閱 SerCx2 PIO-Receive Transactions。

例子

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

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

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

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

要求

要求 價值
最低支援的用戶端 從 Windows 8.1 開始提供。
目標平臺 桌面
標頭 sercx.h
IRQL 在 IRQL <= DISPATCH_LEVEL 呼叫。

另請參閱

EvtSerCx2PioReceiveCleanupTransaction

EvtSerCx2PioReceiveEnableReadyNotification

EvtSerCx2PioReceiveInitializeTransaction

SERCX2PIORECEIVE

SerCx2PioReceiveCreate