パイプ ポリシー修正のための WinUSB 関数

  • [アーティクル]

アプリケーションがエンドポイント パイプの既定ポリシー パラメーターを取得および設定できるようにするために、Winusb.dll はパイプの既定ポリシーを取得する WinUsb_GetPipePolicy 関数を公開します。 WinUsb_SetPipePolicy 関数を使用して、アプリケーションはポリシー パラメーターを新しい値に設定できます。

WinUSB では、エンドポイントのパイプにポリシーを適用することで、既定の振る舞いを変更できます。 これらのポリシーを使用することで、WinUSB をデバイスの機能に最も適合するように構成できます。 次の表に、WinUSB でサポートされているパイプ ポリシーの一覧を示します。

Note

表で説明されているポリシーは、指定したエンドポイントに対してのみ有効です。 他のエンドポイントにポリシーを設定しても、読み取りまたは書き込み要求に対する WinUSB の振る舞いには影響しません。

ポリシー番号 ポリシー名 説明 エンドポイント (方向) 規定値
0x01 SHORT_PACKET_TERMINATE バッファーがエンドポイントでサポートされている最大パケット サイズの倍数である場合、書き込み要求の完了時に長さ 0 のパケットを送信します。 Bulk (OUT)

Interrupt (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL データ フローを停止することなく、停止したパイプを自動的にクリアします。 Bulk (IN)

Interrupt (IN)		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT 要求をキャンセルする前に、タイムアウト間隔 (ミリ秒単位) が経過するまで待機します。 Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)		 制御の場合は 5 秒 (5,000 ミリ秒)。その他の場合は 0
0x04 IGNORE_SHORT_PACKETS ショート パケットを受信するか、一定数のバイトが読み取られると、読み取り要求が完了します。 ファイル サイズが不明な場合、要求はショート パケットで終了します。 Bulk (IN)

Interrupt (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS 呼び出し元が要求したよりも多くのデータを返すデバイスからの読み取り要求を許可します。 Bulk (IN)

Interrupt (IN)		 TRUE
0x06 AUTO_FLUSH 読み取り要求からの超過データを保存し、次の読み取り要求に追加するか、超過データを破棄します。 Bulk (IN)

Interrupt (IN)		 FALSE
0x07 RAW_IO キューとエラー処理をバイパスして、複数の読み取り要求のパフォーマンスを向上させます。 Bulk (IN)

Interrupt (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE WinUSB でサポートされている USB 転送の最大サイズを取得します。 これは読み取り専用ポリシーであり、WinUsb_GetPipePolicy を呼び出すことで取得できます。 Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)
0x09 RESET_PIPE_ON_RESUME サスペンドから復帰した後、新しい要求を受け入れる前にエンドポイントのパイプをリセットします。 Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)		 FALSE

次の表では、各パイプ ポリシーの使用方法のベスト プラクティスを示し、ポリシーを有効にした場合の振る舞いについて説明します。

ポリシー 有効にする場合 動作
SHORT_PACKET_TERMINATE(0x01) デバイスで OUT 転送が長さ 0 のパケットで終了する必要がある。 ほとんどのデバイスにはこの要件はありません。 有効にした場合 (ポリシー パラメーター値が TRUE であるか 0 以外の場合)、エンドポイントでサポートされている最大パケット サイズの倍数であることが前提で、各書き込み要求の完了時に長さ 0 のパケットが送信されます。

ホスト コントローラーにデータを送信した後、WinUSB は長さ 0 のパケットで書き込み要求を送信し、WinUsb_WritePipe によって作成された要求を完了します。
AUTO_CLEAR_STALL 失敗した転送によりエンドポイントが停止状態になることを避ける必要がある。 このポリシーは、RAW_IO が無効になっているときにエンドポイントに対する保留中の読み取り要求が複数ある場合にのみ便利です。
  • 有効にした場合 (ポリシー パラメーター値が TRUE であるか 0 以外の場合)、停止状態は自動的にクリアされます。 このポリシー パラメーターは制御パイプには影響しません。

    読み取り要求が失敗し、ホスト コントローラーが STATUS_CANCELLED または STATUS_DEVICE_NOT_CONNECTED 以外のステータスを返した場合、WinUSB は失敗した要求を完了する前にパイプをリセットします。 パイプをリセットすることで、データフローを中断することなく停止状態をクリアします。 新しい転送がデバイスから到着し続ける限り、データはエンドポイント内を流れ続けます。 新しい転送には、停止状態になったときにキューにあった転送が含まれる場合があります。

    このポリシーを有効にしても、パフォーマンスに大きな影響はありません。

  • 無効にした場合 (ポリシー パラメーター値が FALSE であるか 0 の場合)、呼び出し元が WinUsb_ResetPipe を呼び出してエンドポイントのパイプを手動でリセットするまで、停止した転送の後にエンドポイントに到着するすべての転送は失敗します。
PIPE_TRANSFER_TIMEOUT エンドポイントへの転送が特定の時間内に完了する必要がある。
  • 0 (既定) に設定された場合、ホスト コントローラーが転送をキャンセルしないため、転送はタイムアウトになりません。 この場合、転送は手動でキャンセルされるか、転送が正常に完了するまで無期限に待機します。
  • 0 以外の値 (タイムアウト間隔) に設定されている場合、ホスト コントローラーは転送要求を受信するとタイマーを開始します。 タイマーが設定されたタイムアウト間隔を超えると、要求はキャンセルされます。

    タイマー管理により、パフォーマンスのわずかな低下が生じます。

    WinUSB キューで待機中の要求はタイムアウトしません。

    Windows Vista では、すべての転送 (RAW_IO が有効な転送を除く) について、宛先エンドポイントでの以前の転送がすべて完了するまで、WinUSB は要求をキューに入れます。 ホスト コントローラーでは、タイムアウト間隔の計算にキュー時間は含まれません。

    RAW_IO を有効にした場合、WinUSB は要求をキューに入れません。 代わりに、USB スタックが前の転送の処理でビジー状態であるかどうかに関わらず、要求を直接 USB スタックに渡します。 USB スタックがビジー状態の場合、新しい要求の処理が遅れることがあります。 これによりタイムアウトが発生する可能性があります。
IGNORE_SHORT_PACKETS RAW_IO が無効になっており、読み取り要求を完了するためのショート パケットが必要ない。
  • 有効にした場合 (ポリシー パラメーター値が TRUE であるか 0 以外の場合)、ホスト コントローラーはショート パケットを受信してもすぐに読み取り操作を完了しません。 代わりに、次の場合にのみ操作が完了します。
    • エラーが発生しました。
    • 要求がキャンセルされた。
    • 要求されたすべてのバイトが受信された。
  • 無効にした場合 (ポリシー パラメーター値が FALSE または 0 の場合)、ホスト コントローラーは、要求されたバイト数を読み取った後、またはショート パケットを受信した後に、読み取り操作を完了します。
ALLOW_PARTIAL_READS 要求バッファーのサイズがエンドポイントの最大パケット サイズの倍数である場合、デバイスが要求よりも多くのデータを送信できる。

アプリケーションが読み取る合計バイト数を特定するために、先に数バイトを読み取る必要がある場合に使用します。
  • 無効にした場合 (ポリシー パラメーター値が FALSE または 0 の場合)、デバイスが要求されたデータよりも多くのデータを返すと、WinUSB は要求をエラーで終了します。
  • 有効にした場合 (ポリシー パラメーター値が TRUE であるか 0 以外の場合)、デバイスが要求されたよりも多くのデータを返すと、WinUSB は (AUTO_FLUSH 設定に応じて) 読み取り要求からの超過データを次の読み取り要求の先頭に追加するか、超過データを破棄できます。

    有効にした場合、WinUSB は 0 バイトの読み取り要求を直ちに正常に完了し、要求をスタックに送信しません。
AUTO_FLUSH ALLOW_PARTIAL_READS ポリシーが有効になっている。

デバイスは要求されたよりも多くのデータを送信でき、アプリケーションは他のデータを必要としません。 これは、要求バッファーのサイズが最大エンドポイント パケット サイズの倍数であることが前提です。		 AUTO_FLUSH は、ALLOW_PARTIAL_READS が有効な場合の WinUSB の振る舞いを定義します。 ALLOW_PARTIAL_READS を無効にした場合、AUTO_FLUSH 値は WinUSB によって無視されます。

WinUSB は残りのデータを破棄するか、呼び出し元の次の読み取り要求と共に送信できます。

  • 有効にした場合 (ポリシー パラメーター値が TRUE でるか 0 以外の場合)、WinUSB はエラー コードなしで超過バイトを破棄します。
  • 無効にした場合 (ポリシー パラメーター値が FALSE または 0 の場合)、WinUSB は超過バイトを保存し、呼び出し元の次の読み取り要求の先頭に追加して、次の読み取り操作でデータを呼び出し元に送信します。
RAW_IO パフォーマンスが優先され、アプリケーションは同じエンドポイントに同時に読み取り要求を送信する。

RAW_IO は、WinUsb_ReadPipe で呼び出し元から渡されるバッファーに特定の制限を課します。

  • バッファー長は、最大エンドポイント パケット サイズの倍数である必要がある。
  • バッファー長は、WinUsb_GetPipePolicy によって取得される MAXIMUM_TRANSFER_SIZE の値以下である必要がある。
 有効にした場合、転送はキューとエラー処理をバイパスして、複数の読み取り要求のパフォーマンスを向上させます。 WinUSB は読み取り要求を次のように処理します。

  • 最大エンドポイント パケット サイズの倍数ではない要求は失敗とする。
  • WinUSB でサポートされている最大転送サイズを超える要求は失敗とする。
  • 形式が正しいすべての要求は直ちに USB コアスタックに送られて、ホスト コントローラーでスケジュールされます。


この設定を有効にした場合、ある転送の最後のパケットと次の転送の最初のパケットとの間の遅延が短くなるため、複数の読み取り要求のパフォーマンスが大幅に向上します。
RESET_PIPE_ON_RESUME デバイスはサスペンド後のデータのトグル状態を保持しません。 サスペンドから復帰すると、WinUSB は呼び出し元がエンドポイントに新しい要求を送信できるようになる前に、エンドポイントをリセットします。