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 から読み取りバッファーに正常に転送されたデータのバイト数を返します。

注釈

シリアル コントローラー ドライバーでは、この関数を実装する必要があります。 ドライバーは、PIO 受信オブジェクトを作成する SerCx2PioReceiveCreate 呼び出しに関数を登録します。

SerCx2 は、PIO 受信トランザクション中に EvtSerCx2PioReceiveReadBuffer 関数を複数回呼び出す場合があります。 この呼び出しで読み取りバッファーに受信 FIFO からのデータを入力できる場合は、1 つの EvtSerCx2PioReceiveReadBuffer 呼び出しで十分です。 それ以外の場合、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 は、 EvtSerCx2PioReceiveReadBuffer 関数の最後の呼び出しの後、PIO 受信トランザクションの最後にこの関数を呼び出します。

SerCx2 は、PIO 受信トランザクション中に EvtSerCx2PioReceiveReadBuffer 関数を呼び出すことに加えて、この関数を呼び出して、シリアル コントローラーが D0 デバイスの電源状態を終了する直前の受信 FIFO の状態を保存します。 詳細については、「 SerCx2SaveReceiveFifoOnD0Exit」を参照してください。

PIO 受信トランザクションの詳細については、「 SerCx2 PIO-Receive トランザクション」を参照してください。

例

EvtSerCx2PioReceiveReadBuffer コールバック関数を定義するには、まず、定義するコールバック関数の種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数型のセットが用意されています。 コールバック関数の種類を使用して関数を宣言すると、 ドライバーのコード分析、 静的ドライバー検証ツール (SDV)、およびその他の検証ツールでエラーが検出され、Windows オペレーティング システムのドライバーを記述するための要件になります。

たとえば、 という名前MyPioReceiveReadBufferの EvtSerCx2PioReceiveReadBuffer コールバック関数を定義するには、次のコード例に示すように、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 以降で使用できます。
対象プラットフォーム デスクトップ
Header sercx.h
IRQL IRQL <= DISPATCH_LEVELで呼び出されます。

こちらもご覧ください

EvtSerCx2PioReceiveCleanupTransaction

EvtSerCx2PioReceiveEnableReadyNotification

EvtSerCx2PioReceiveInitializeTransaction

SERCX2PIORECEIVE

SerCx2PioReceiveCreate