ユーティリティー関数

このセクションでは、一般的な用途の関数をいくつか説明します。

デバイス構成機能

このセクションでは、デバイス構成に関係する関数について説明します。

インタフェース番号の取得

マルチインタフェースデバイスを使用していて、usb_mid(7D) ドライバが、呼び出し側ドライバから使用可能なインタフェースを 1 つだけに限定している場合、呼び出し側ドライバがバインドされているインタフェースの番号を認識していなければならない可能性があります。usb_get_if_number(9F) 関数を使用して次のいずれかのタスクを行います。

• 呼び出し元ドライバがバインドされているインタフェースの番号を返します。この場合、usb_get_if_number(9F) 関数はゼロより大きいインタフェース番号を返します。

• 呼び出し元ドライバがマルチインタフェースデバイス全体を管理していることを検出します。このドライバはデバイスレベルでバインドされているため、usb_mid によるデバイスの分割は行われませんでした。この場合、usb_get_if_number(9F) 関数は USB_DEVICE_NODE を返します。

• 呼び出し元ドライバが、現在の構成でデバイスが提供する唯一のインタフェースを管理することでデバイス全体を管理していることを検出します。この場合、usb_get_if_number(9F) 関数は USB_COMBINED_NODE を返します。

デバイス全体の管理

ある複合デバイス全体を管理するドライバは、ベンダー ID、製品 ID、およびリビジョン ID を含む互換名を使用することで、そのデバイス全体にバインドできます。複合デバイス全体にバインドされたドライバは、ネクサスドライバと同様に、そのデバイスのすべてのインタフェースを管理する必要があります。一般に、複合デバイス全体にドライバをバインドするべきではありません。代わりに、汎用マルチインタフェースドライバusb_mid(7D) を使用してください。

ドライバがあるデバイス全体を所有しているかどうかを判定するには、usb_owns_device(9F) 関数を使用します。デバイスは複合デバイスであってもかまいません。ドライバがデバイス全体を所有している場合、usb_owns_device(9F) 関数から TRUE が返されます。

複数の構成を持つデバイス

USB デバイスは、ある時点でホストから使用可能な構成を 1 つだけに限定します。ほとんどのデバイスで、単一の構成しかサポートされていません。ただし、いくつかの USB デバイスでは複数の構成がサポートされています。

複数の構成を持つデバイスは必ず、使用可能なドライバが存在する最初の構成に配置されます。一致を検索するとき、デバイス構成が番号順に検討されます。一致するドライバが見つからなかった場合、デバイスは最初の設定に設定されます。その場合、usb_mid ドライバがデバイスを管理し、デバイスをいくつかのインタフェースノードに分割します。デバイスの現在の構成を返すには、usb_get_cfg(9F) 関数を使用します。

次の 2 つの方法のいずれかを使用すると、別の構成を要求できます。これら 2 つの方法のいずれかを使用してデバイス構成を変更すると、USBA モジュールとデバイスの同期が確実に維持されます。

• cfgadm_usb(1M) コマンドを使用します。

• ドライバからusb_set_cfg(9F) 関数を呼び出します。

  デバイス構成を変更するとデバイス全体に影響が及ぶため、クライアントドライバは次の条件をすべて満たしていないと、usb_set_cfg(9F) 関数の呼び出しが成功しません。

  • クライアントドライバがデバイス全体を所有している必要があります。

  • デバイスの子ノードが 1 つも存在していない必要があります。ほかのドライバが子ノードを通じてデバイスを駆動する可能性があるからです。

  • デフォルトパイプを除くすべてのパイプが閉じられている必要があります。

  • デバイスが複数の構成を持っている必要があります。

---

注意  - SET_CONFIGURATION USB 要求を手動で行うことでデバイス構成を変更しないでください。SET_CONFIGURATION 要求による設定の変更はサポートされていません。

---

代替設定の変更または取得

クライアントドライバからusb_set_alt_if(9F) 関数を呼び出すと、現在選択されているインタフェースの選択済みの代替設定を変更できます。明示的に開かれたパイプを必ずすべて閉じてください。usb_set_alt_if(9F) 関数は、代替設定を切り替える際に、デフォルトパイプのみが開かれていることを確認します。usb_set_alt_if(9F) を呼び出す前に、デバイスの準備が整っていることを確認してください。

代替設定を変更すると、ドライバから使用可能なエンドポイント、クラス固有記述子、およびベンダー固有記述子に影響が及ぶ可能性があります。エンドポイントや記述子の詳細については、記述子ツリーを参照してください。

現在の代替設定の番号を取得するには、usb_get_alt_if(9F) 関数を呼び出します。

その他のユーティリティー関数

このセクションでは、USB デバイスドライバで役立つその他の関数について説明します。

文字列記述子の取得

インデックスを指定して文字列記述子を取得するには、usb_get_string_descr(9F) 関数を呼び出します。一部の構成、インタフェース、またはデバイス記述子には、文字列の ID が関連付けられています。そのような記述子には、ゼロ以外の値を含む文字列インデックスフィールドが含まれています。文字列インデックスフィールドの値を usb_get_string_descr(9F) に渡すと、対応する文字列を取得できます。

パイプの非公開データ機能

各パイプは、クライアントドライバ専用に確保された領域のポインタを 1 つずつ備えています。値をインストールするには、usb_pipe_set_private(9F) 関数を使用します。値を取得するには、usb_pipe_get_private(9F) 関数を使用します。この機能がコールバックで役に立つのは、パイプが独自のクライアント定義状態を特定処理の対象としてコールバックに渡す必要がある場合です。

USB 状態のクリア

usb_clr_feature(9F) 関数を使用すると、次のタスクを実行できます。

• あるエンドポイントの停止状態をクリアするために、USB CLEAR_FEATURE 要求を発行します。

• デバイス上のリモートウェイクアップ状態をクリアします。

• デバイスレベル、インタフェースレベル、またはエンドポイントレベルのデバイス固有状態をクリアします。

デバイス、インタフェース、エンドポイントの各ステータスの取得

USB GET_STATUS 要求を発行してデバイス、インタフェース、またはエンドポイントのステータスを取得するには、usb_get_status(9F) 関数を使用します。

• デバイスのステータス。自己電源とリモートウェイクアップが有効。

• インタフェースのステータス。USB 2.0 仕様に従ってゼロを返す。

• エンドポイントのステータス。エンドポイントが停止。このステータスは機能ストールを示します。停止をクリアしないと、デバイスをふたたび動作させることができません。

  プロトコルストールは、サポートされない制御パイプ要求が行われたことを示します。プロトコルストールは、次回の制御転送の開始時に自動的にクリアされます。

デバイスのバスアドレスの取得

デバイスの USB バスアドレスをデバッグ目的で取得するには、usb_get_addr(9F) 関数を使用します。このアドレスは特定の USB ポートに対応します。