WDF_USB_CONTINUOUS_READER_CONFIG 構造体 (wdfusb.h)

[アーティクル]
08/08/2023

[KMDF と UMDF に適用]

WDF_USB_CONTINUOUS_READER_CONFIG構造体には、フレームワークが USB パイプの連続リーダーを構成するために使用する情報が含まれています。

構文

typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
  ULONG                                 Size;
  size_t                                TransferLength;
  size_t                                HeaderLength;
  size_t                                TrailerLength;
  UCHAR                                 NumPendingReads;
  PWDF_OBJECT_ATTRIBUTES                BufferAttributes;
  PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete;
  WDFCONTEXT                            EvtUsbTargetPipeReadCompleteContext;
  PFN_WDF_USB_READERS_FAILED            EvtUsbTargetPipeReadersFailed;
} WDF_USB_CONTINUOUS_READER_CONFIG, *PWDF_USB_CONTINUOUS_READER_CONFIG;

メンバー

Size

この構造体のサイズ (バイト単位)。

TransferLength

デバイスから受信できるデータの最大長 (バイト単位)。

HeaderLength

デバイスからデータを受信するバッファーへのオフセット (バイト単位)。フレームワークは、オフセット値から始まる読み取りバッファーにデバイスからのデータを格納します。つまり、この領域は、フレームワークがデバイスからのデータを格納する TransferLength サイズの領域の前に置きます。

TrailerLength

末尾のバッファー領域の長さ (バイト単位)。この領域は、フレームワークがデバイスからのデータを格納する TransferLength サイズの領域に従います。

NumPendingReads

I/O ターゲットからデータを受信するためにフレームワークがキューに登録する読み取り要求の数。この値が 0 の場合、フレームワークは既定の数の読み取り要求を使用します。指定した値が許可された最大値を超える場合、フレームワークは許可された最大値を使用します。 NumPendingReads メンバーの詳細については、次の「解説」セクションを参照してください。

BufferAttributes

フレームワークが読み取り要求ごとに作成するフレームワークメモリオブジェクトのオブジェクト属性を指定する WDF_OBJECT_ATTRIBUTES 構造体。このメンバーは NULL にすることができます。 WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーを設定することはできません。

EvtUsbTargetPipeReadComplete

ドライバーの EvtUsbTargetPipeReadComplete コールバック関数へのポインター。

EvtUsbTargetPipeReadCompleteContext

フレームワークがドライバーの EvtUsbTargetPipeReadComplete コールバック関数に渡す、ドライバー定義のコンテキスト情報への型指定されていないポインター。

EvtUsbTargetPipeReadersFailed

ドライバーの EvtUsbTargetPipeReadersFailed コールバック関数へのポインター。このポインターは省略可能であり、 NULL にすることができます。このパラメーターの詳細については、「 WdfUsbTargetPipeConfigContinuousReader」の「解説」セクションを参照してください。

注釈

WDF_USB_CONTINUOUS_READER_CONFIG構造体は、WdfUsbTargetPipeConfigContinuousReader メソッドへの入力として使用されます。

WDF_USB_CONTINUOUS_READER_CONFIG構造体を初期化するには、ドライバーが WDF_USB_CONTINUOUS_READER_CONFIG_INIT を呼び出す必要があります。

NumPendingReads メンバーの値を選択する場合は、次のガイドラインを使用します。

ドライバーでフレームワークの既定値を使用する場合は、 NumPendingReads を 0 に設定します。
既定値は 1 より大きく、多くのプロセッサ構成の多くのデバイスに適切なパフォーマンスを提供することが決定されています。
デバイスがデータを配信する正確な順序でドライバーがデータバッファーを受信することが重要な場合は、 NumPendingReads を 1 に設定します。
NumPendingReads を、徹底的なパフォーマンス測定に基づいて、デバイスのパフォーマンス要件を満たす数値に設定します。
まず、 NumPendingReads の既定値 (0) でデバイスをテストします。テストには、さまざまな種類のプロセッサと数、さまざまな USB ホストコントローラーと USB 構成など、さまざまなハードウェア構成が含まれている必要があります。その後、同じテストを使用して、より高い値を試すことができます。より高い値を必要とする可能性があるドライバーは、割り込み速度が高いデバイスでは 1 つであり、割り込みが迅速に処理されない場合にデータが失われる可能性があります。

NumPendingReads の値が大きすぎると、システムのパフォーマンスが低下する可能性があります。パフォーマンス要件を満たす最小値を使用する必要があります。通常、3 または 4 より大きい値では、データのスループットは向上しません。ただし、値を大きくすると、高周波パイプでの待機時間やデータの欠落の可能性が低下する可能性があります。