2. The Linux USB Subsystem

2.1 The USB Device Driver Framework

2.1.1 Framework Data Structures

• name: 通常はモジュールの名前.
• probe: probe 関数のエントリーポイント.
• disconnect: disconnect 関数のエントリーポイント.
• driver_list: サブシステムの内部の使用のため {NULL, NULL}に初期化
• fops: ドライバーのファイル操作の通常のリスト
• minor: このデバイスにアサインされた基本マイナー番号(値は16の倍数でなければならない)

2.1.2 Framework Entry Points

• void *probe(struct usb_device *dev, unsigned int interface);

  新しいデバイスがバスに取り付けられるときはいつも, このエントリーポイント が呼ばれる. そして, デバイスドライバは新しいデバイスのためにその内部のデータ構造体の新しいインスタンスを生成しなければならない. 引数「dev」はデバイスコンテキストを指定し, それは全ての USB ディスクリプタに たいするポインタをふくんでいる. 引数「interface」はインタフェイス番号を指定する. もし USB ドライバがそれ自身を 特別なデバイスまたはインタフェイスに対して責任を持ちたいなら, ポインタを 返さなければならない. 通常,このポインタはデバイスドライバのコンテキスト構造体 を指す. 通常プローブは, ベンダーと製品識別もしくはクラスとサブクラスの定義のチェックが行なわれる. もしそれらが適合するならインタフェイス番号がドライバによりサポートされたものと比較される. クラスベースでプローブが行なわれる時, デバイスのプロパティは広範囲で異なりうるのでさらなる USB ディスクリプタの説明が必要かもしれない. 図 5 に簡単なプローブルーチンを示す.

• void disconnect(struct usb_device *dev, void *drv_context);

  この関数はこのドライバが取り扱っているデバイスが取り外されさるときにはいつも 呼ばれる. 引数「dev」はデバイスコンテキストを指し「driver_cntext」は, 以前に登録された プローブ関数の「driver_cntext」へのポインターを返す. disconnect 関数から戻った後, USB フレームワークはこのデバイスに関係する すべてのデータ構造体を完全に開放します. それで特別に「usb_device」構造体 はもはや USB ドライバで使用してはいけない. 図 6 に簡単な disconnect 関数を示す.

2.1.3 Framework Functions

• int usb_register(struct usb_driver *drv);

  この関数は,サブシステムで新しい USB デバイスドライバを登録するのに使用される. 引数 drv は完全に初期化された usb_driver 構造体を指す. コールが成功したら 0 を返しそれ以外はエラー値を返す.

• void usb_deregister(struct usb_driver *drv);

  この関数はサブシステムに以前登録済の USB デバイスドライバの登録を抹消する.

• void usb_driver_claim_interface(struct usb_driver *driver, struct usb_interface *ifaice, void *drv_context);

  この関数は, プローブ中に直ちにデバイス上のひとつ以上のインターフェイス要求する USB デバイスドライバによる使用を想定している. 引数 driver は完全に初期化された usb_driver 構造体を指す. 引数 iface は, probe 関数で与えられる usb_device 構造体からアクセス可能な usb_config_descriptor の一部である usb_interface 構造体を指す. drv_context ポインタは通常デバイスドライバのコンテキスト構造体を参照する(probe 関数のリターン値を見なさい).

• int usb_interface_claimed(struct usb_interface *iface);

  この関数は別のデバイスドライバが既に指定されたインタフェースを要求したかどうかチェックするのに使用される. インタフェースがどんなドライバーによっても要求されなかったならば, リターン値は 0 である.

• void usb_driver_release_interface(struct usb_driver *driver, struct usb_interface *iface);

  ドライバが以前に要求したインタフェイスを開放したいならこの関数を呼ばなければならない. disconnect 関数では, probe 関数で追加的に要求したいかなるインタフェイスも開放する必要はない.

2.2 Configuring USB Devices

2.2.1 Descriptor Data Structures

struct usb_device{
  ...
  struct usb_config_descriptor *actconfig;/* the active configuration */
  ...
  struct usb_device_descriptor descriptor;/* Descriptor */
  struct usb_config_descriptor *config;	/* All of the configs */
}

usb_device 構造体はすべての USB の特定のディスクリプタの根源である. 時々, デバイスのコンフィギュア, または適切に転送要求をセットアップするためにドライバーの中のディスクリプタを分析することが必要となる.

• このようにすべての利用可能なコンフィグレーション・ディスクリプタにアクセスすることができる -

  for (i = 0; i < dev->descriptor.bNumConfigurations; i++) {
    struct usb_config_descriptor *cfg = &dev->config[i];
    ...
  }
  

• 特定のコンフィギュレーションのすべての利用可能なインタフェース・ディスクリプタがこのようにアクセスされる -

  for (j = 0; j < cfg->bNumInterfaces; j++) {
    struct usb_interface *ifp = &cfg->interface[j];
    ...
  }
  

  アクティブなコンフィギュレーションの構文解析を始めるには, 単純に dev->actconfig ポインタを使用しなさい.
• このように特定のインタフェースのすべての相互設定にアクセスが可能である -

  for (k = 0; k < ifp->num_altsetting; k++) {
    struct usb_interface_descriptor *as = &ifp->altsetting[k];
    ...
  }
  

  *as = &ifp->altsetting[ifp->act_altsetting] を通してアクティブな相互設定にアクセスすることができる.

• このように特定の相互設定のすべてのエンドポイント・ディスクリプタにアクセス が可能である -

  for(l = 0; l < as->bNumEndpoints; l++) {
    struct usb_endpoint_descriptor *ep=&as->endpoint[k];
    ...
  }
  

2.2.2 Standard Device Requests

相互設定, 特定なコンフィギュレーションの設定もしくは問合せのために多数の関数が存在する. これらは一般的にセットアップの標準の装置が要求する機能を使用した.(指定デバイスへのコントロール転送) -
• int usb_set_configuration(struct usb_device *dev, int configuration);

  特定のコンフィギュレーションをアクティブにするには, この関数を使用する. 引数には以下のような関係がある.

  0 <= configuration < dev->descriptor.bNumConfigurations.

• int usb_set_interface(struct usb_device *dev, int interface, int alternate);

  この関数は指定されたインタフェースの相互設定をアクティブにする. 引数 interface は 以下のような性質を持つ.

  0 <= interface < dev->actconfig->bNumInterfaces.

  引数 alternate は以下のような性質を持つ.

  0 <= alternate < dev->actconfig->interface[interface].num_altsetting

• int usb_get_device_descriptor(struct usb_device *dev);

  この関数は特定のデバイスから完全なディスクリプタ・ツリーを再読する. デバイスがバスに取り付けられるとき, または USB ディスクリプタが変化したときはいつも,自動的に呼ばれる.

• int usb_get_descriptor(struct usb_device *dev, unsigned char desctype, unsigned char descindex, void *buf, int size);

  ただひとつの USB ディスクリプタがデバイスから生データとして読み込み可能である. この関数は, 拡張された, またはベンダーの特定のディスクリプタの構文解析に用いることができる. 引数の desctype と descindex は 「Universal Serial Bus Specification」のセクション 9.4.3 と 9.5 に書かれている.

• int usb_get_string(struct usb_device *dev, unsigned short langid, unsigned char index. void *buf, int size);

  デバイス, コンフィギュレーション, またはインタフェース・ディスクリプタが文字列のインデックス値を参照しているなら(「Universal Serial Bus Specification」のセクション 9.6.5 を見よ), ストリング・ディスクリプタを回復するのに使用することができる. 仕様によると, USB 文字列はユニコードとしてコード化される. コールが成功したら 0 を返し, そうでなければ, エラーコードが返される.

• int usb_string(struct usb_device *dev, int index, char *buf, size_t size);

  この関数は, ユニコード文字列を ASCII 文字列に変えることによって, usb_get_string を簡素化する.

• int usb_get_status(struct usb_device *dev, int type, int target, void *data);

  この USB コントロール要求は「Universal Serial Bus Specification」のセクション 9.4.5 に 書かれている.

• int usb_clear_halt(struct usb_device *dev, int pipe);

  エンドポイントが立往生するならば(「Universal Serial Bus Specification」8.4.4 章を参照), この関数を呼んで, 停止状態をクリアしなさい. 停止状態はは, コントロール・パイプ要求がサポート去れていないかまたは関数がデータの送受信できない状態を示す.

• int usb_get_protocol(struct usb_device *dev);

  この HID USB コントロール要求は, 「Device Class Definition for HID Firmware Specification Ver. 1.1」のセクション 7.2.5 に書かれている.

• int usb_set_protocol(struct usb_device *dev, int protocol);

  この HID USB コントロール要求は, 「Device Class Definition for HID Firmware Specification Ver. 1.1」のセクション 7.2.6 に書かれている.

• int usb_get_report(struct usb_device *dev, unsigned char type, unsigned char id, unsigned char index, void *buf, int size);

  この HID USB コントロール要求は, 「Device Class Definition for HID Firmware Specification Ver. 1.1」のセクション 7.2.1 に書かれている.

• int usb_set_idle(struct usb_device *dev, int duration, int report_id);

  この HID USB コントロール要求は, 「Device Class Definition for HID Firmware Specification Ver. 1.1」のセクション 7.2.4 に書かれている.

2.3 USB Transfers

このセクションでは, バスのデータ転送に関する全てのデータ構造体, マクロそして関数の概要を説明する. この構造体には, いかなるタイプの USB 転送もセットアップするためのパラメータが入っている.

2.3.1 Transfer Data Structures and Macrosn

Linux USB サブシステムは USB Request Block(URB)と呼ばれるただひとつのデータ構造体を使用する. この構造体は, どんなタイプの USB 転送でもセットアップするためのすべてのパラメータが入っている. すべての転送要求は非同期に USB コアに送られ要求の完了はコールバック関数を経由で知らされる.　 図7 に示されるように USB 構造体はすべての転送タイプに共通な要素(C でマーク去れている)が入っている. > でマークされている要素は入力パラメータであり M は命令であり O はオプションである. < でマークされている要素は戻り値である. T でマークされている要素は一時的なパラメータである(入力または出力). 共通でないすべての要素即ちコントロール、インターラプト、アイソクロナス転送は、3 コラム目にマーク去れている。X は関連する転送のタイプとともに要素をマークする。 URB 構造体は一見混乱しているように見えるかもしれないが、それは単にその多才さの概観に過ぎない。正しいパラメータをセットアップするためのいくつかの役にたつマクロがある。それらは非常に重要なので最初に共通の要素について説明する。
• dev [mandatory input parameter]

  この要素は usb_device 構造体へのポインタである(セクション 2.2.2 フレームワークの probe 関数で紹介済)

• pipe [mandatory input parameter]

  要素 pipe はエンドポイント番号とプロパティのエンコードに使われる。いくつかのマクロが適切なパイプ値を作成するために存在する -

  • pipe=usb_sndctrlpipe(dev,endpoint) pipe=usb_rcvctrlpipe(dev,endpoint)

    与えられたエンドポイントへのダウンストリーム(snd)またはアップストリーム(rcv)コントロール転送のための pipe をつくる。

  • pipe=usb_sndbulkpipe(dev,endpoint) pipe=usb_rcvbulkpipe(dev,endpoint)

    与えられたエンドポイントへのダウンストリーム(snd)またはアップストリーム(rcv)バルク転送のための pipe をつくる。エンドポイントは 1 以上、15 以下(アクティブなエンドポイント・ディスクリプタに依存する)

  • pipe=usb_sndintpipe(dev,endpoint) pipe=usb_rcvintpipe(dev,endpoint)

    与えられたエンドポイントへのダウンストリーム(snd)またはアップストリーム(rcv)インタラプト転送のための pipe をつくる。エンドポイントは 1 以上、15 以下(アクティブなエンドポイント・ディスクリプタに依存する)

  • pipe=usb_sndisopipe(dev,endpoint) pipe=usb_rcvisopipe(dev,endpoint)

    与えられたエンドポイントへのダウンストリーム(snd)またはアップストリーム(rcv)アイソクロナス転送のための pipe をつくる。エンドポイントは 1 以上、15 以下(アクティブなエンドポイント・ディスクリプタに依存する)

• transfer_buffer [mandatory input parameter]

  この要素はデバイスから(へ)の転送されたデータが入った関連する転送のバッファへのポインタである。このバッファはページングされない連続物理メモリブロックとして割当てられなければならない。

• transfer_buffer_length [mandatory input parameter]

  この要素はバイト単位で転送サイズを指定する。インターラプトおよびコントロール転送では、その値は関連するエンドポイントの最大パケットサイズ以下でなければならない。最大パケットサイズはエンドポイント・ディスクリプタの wMaxPacketSize 要素で得ることができる。すべてのコントロール転送に使用されるデフォルト・エンドポイント 0 にはエンドポイント・ディスクリプタがないので最大パケットサイズは usb_device 構造体の maxpacketsize 要素として得ることができる。 wMaxPacketSize より大きなバルク転送は自動的に小さな部分に分割される。

• complete [optional input parameter]

  USB サブシステムで述べたようにプロセスは非同期に要求を行なう。この要素はリクエストが完了後に呼ばれる呼び手が与えるハンドラ関数のポインタの指定を許可する。このハンドラの目的は、ホストコントローラのハードウエアインターラプト・ハンドラが起動されるといけないので、できる限り早くリクエストの呼び手側の部分を終了させることです。これは、インターラプト・ハンドラのために書かれたコードに当てはまる、その他すべての制限条件でさえ暗黙に含んでいる。

• context [optional input parameter]

  任意に context 構造体に関係するリクエストへのポインタを与えられる。

• transfer_flags [optional input parameter and return value]

  いくつかの転送のフラッグは、転送リクエストが処理中に振舞を変えるために指定できる。

  • USB_DISABLE_SPD

    このフラグはショート・パケットをディゼーブルにします。もしアップストリームが 関連するエンドポイントの最大パケットサイズより小さな転送を要求するなら ショート・パケット状態が起こる。

  • USB_URB_EARLY_COMPLETE

    上で記述したように、completion handler は要求が処理された後に呼ばれる。この フラグを使用して他の URB が再提出する前に handler を確保しなければいけない。

---

前のページ 目次