最終更新:2024-11-18 (月) 13:13:35 (80d)
レポートディスクリプタ
Top / レポートディスクリプタ
HIDデバイスからホストに通知するデータのフォーマットを定義するもの。
仕様
概要
- HIDクラスでは、HID/レポートと呼ばれる単位でデータを転送する
- レポートの中にどのような情報がどのように並んでいるかは、レポートディスクリプタによって定義
- レポートディスクリプタは、他のディスクリプタと構造が全く違う
ディスクリプタの階層
- USB/ディスクリプタ > デバイスディスクリプタ > コンフィグレーションディスクリプタ > インターフェイスディスクリプタ > HIDディスクリプタ > レポートディスクリプタ
- HIDディスクリプタに続いて送られ、可変長。
- レポートディスクリプタのサイズはHIDディスクリプタのwDescriptorLengthで定義
HID/レポート
- HIDインターフェースでは、Input、Output、Featureの3タイプのレポートをデバイスとホストの間で転送する
種類 説明 レポートディスクリプタのタグ 転送の種類 パイプ Inputレポート ホストへ入力するレポート。ボタンとかスイッチとか レポートディスクリプタ/Input インタラプト転送 インタラプトIN、コントロールパイプ Outputレポート ホストから出力するレポート。LEDの制御とか レポートディスクリプタ/Output インタラプト転送 コントロールパイプ (オプションでインタラプトOUT?) Featureレポート デバイスのコンフィギュレーション情報を指定するレポート。エンドポイント0を使用する。(双方向) レポートディスクリプタ/Feature コントロール転送 コントロールパイプ - Only Input reports are sent via the Interrupt In pipe. Feature and Output reports must be initiated by the host via the Control pipe or an optional Interrupt Out pipe.
3ボタンマウスの例
- レポートディスクリプタ/マウス
- 左側がレポートのバイナリ。右のは説明。
- Device Class Definition for Human Interface Devicesより
- The following is a coding sample of items being used to define a 3-button mouse.
- In this case, Main items are preceded by Global items like Usage, Report Count or Report Size (each line is a new item).
05 01 G Usage Page (Generic Desktop), ;Use the Generic Desktop Usage Page 09 02 L Usage (Mouse), A1 01 M Collection (Application), ;Start Mouse collection 09 01 L Usage (Pointer), A1 00 M Collection (Physical), ;Start Pointer collection 05 09 G Usage Page (Buttons), 19 01 L Usage Minimum (01), 29 03 L Usage Maximum (03), ;3 Button 15 00 G Logical Minimum (0), 25 01 G Logical Maximum (1), ;Fields return values from 0 to 1 95 03 G Report Count (3), ;Create three 1 bit fields (button 1, 2, & 3) 75 01 G Report Size (1), 81 02 M Input (Data, Variable, Absolute), ;3 button bits 95 01 G Report Count (1), 75 05 G Report Size (5), ;Create 5 bit constant field 81 01 M Input (Constant), ;5 bit padding 05 01 G Usage Page (Generic Desktop), 09 30 L Usage (X), 09 31 L Usage (Y), 15 81 G Logical Minimum (-127), 25 7F G Logical Maximum (127), ;Fields return values from -127 to 127 75 08 G Report Size (8), 95 02 G Report Count (2), ;Create two 8 bit fields (X & Y position) 81 06 M Input (Data, Variable, Relative), ;2 position bytes (X & Y) C0 M End Collection, ;Close Pointer collection C0 M End Collection ;Close Mouse collection
バイト 0 1 2 ビット 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 値 Padding ボタン3 ボタン2 ボタン1 X Y - バイナリをエンコード/デコードするHID Descriptor Toolというツールが用意されている
ドキュメント (USB.org)
レポートディスクリプタ/アイテム
- レポートディスクリプタはデバイスに関する情報を提供するまとまり(アイテム)から構成される
- アイテムはショートアイテムとロングアイテムの2種類
- item type には「Main」「Global」「Local」の 3 種類があり、Main item type(レポートディスクリプタ内のデータフィールドを定義もしくはグループ化に使用)は 5 種類、Global item type(データを記述に使用)は12 種類、Local item type(特性を定義に使用)は 10 種類の item tag がある
- これらの item tag を組み合わせることにより、ホスト PC とデバイス間で転送するデータのフォーマットを記述
アイテムの形式
- すべてのアイテムは1バイトのプレフィックスを持つ
- アイテムは「data」、「item tag」、「item type」と「itemSize」の 4 種類から構成される
ショートアイテム
- dataのサイズは0,1,2,4バイト
データ プレフィックス ビット 32〜39 24〜31 16〜23 8〜15 7 6 5 4 3 2 1 0 バイト 4 3 2 1 0 フィールド data4 data3 data2 data1 bTag bType bSize
ロングアイテム
- bSizeが2
- dataは最大255バイト
- プレフィックスは0xFEになる
例
05 01 Usage Page (Generic Desktop), ;Use the Generic Desktop Usage Page
- これはプレフィックス(0x05)が 0000 01 01 なので下記のようになる。
- bTag = Usage Page (0000)
- bType = Global (01)
- bSIze = 1 (01)
- data0 = 0x01
メインアイテム (5種類)
- レポートディスクリプタ内のデータフィールドの定義もしくはグループ化に使用
タグ
item tag bTag bType bSize 意味 bSize=0 bSize=1 bSize=2 bSize=3 Input 1000 00 nn 1つ以上の物理的なコントロールが提供するデータに関する情報について記述 - 0x81 0x82 - Output 1001 00 nn 出力データフィールドを定義するために使用 - 0x91 0x92 - Collection 1010 00 nn 2 つ以上のデータ(Input、Output あるいは Feature)のグループ化を開始 - 0xA1 0xA2 - Feature 1011 00 nn デバイスに送ることができるデバイスコンフィギュレーション情報について記述 - 0xB1 0xB2 - End Collection 1100 00 nn Collection に対応し、2 つ以上のデータ(Input、Output あるいは Feature)のグループ化を終了 0xC0 - - -
グローバルアイテム (12種類)
- データの記述に使用
- 続くフィールドのデフォルト属性になる
- Global items become the default attributes for all subsequent data fields in that descriptor.
タグ
item tag bTag bType bSize 意味 bSize=0 bSize=1 bSize=2 bSize=3 Usage Page (必須) 0000 01 nn 現在の Usage Page を指定している値。アイテム使用法のインデックスを定義 - 0x05 0x06 0x07 Logical Minimum (必須) 0001 01 nn 変数または配列のアイテムが報告する最小値。たとえば、0~128 まで X位置価値を報告するマウスは、0 の論理的な最小値をもつ。 0x14 0x15 0x16 0x17 Logical Maximum (必須) 0010 01 nn 変数または配列のアイテムが報告する最大値。たとえば、0~128 まで X位置価値を報告するマウスは、128 の論理的な最大値をもつ。 0x24 0x25 0x26 0x27 Physical Minimum? 0011 01 nn 物理的な最小範囲値(論理値xUnit値) 0x34 0x35 0x36 0x37 Physical Maximum 0100 01 nn 物理的な最大範囲値(論理値xUnit値) 0x44 0x45 0x46 0x47 Unit Exponent 0101 01 nn 基数を 10 としたときの指数(2 の補数) 0x54 0x55 0x56 0x57 Unit 0110 01 nn 単位値 0x64 0x65 0x66 0x67 Report Size (必須) 0111 01 nn レポートフィールドのサイズをビットで指定する符号なし値 0x74 0x75 0x76 0x77 Report ID 1000 01 nn レポート ID を指定する符号なし値 0x84 0x85 0x86 0x87 Report Count (必須) 1001 01 nn アイテムのデータフィールド数を指定する符号なし整数
何個のフィールドがこの特定のアイテムのためにレポートに含められるかを決定する(したがってビットが何個であるかがレポートに付け加えられる)0x94 0x95 0x96 0x97 Push 1010 01 nn グローバル・アイテムの状態一覧をスタックに保管 0xA4 0xA5 0xA6 0xA7 Pop 1011 01 nn スタックの先頭に保管されているグローバル・アイテムの状態一覧を取り出す 0xB4 0xB5 0xB6 0xB7
ローカルアイテム (10種類)
- 特性の定義づけに使用
- Local items only describe the data fields defined by the next Main item
タグ
item tag bTag bType bSize 意味 bSize=0 bSize=1 bSize=2 bSize=3 Usage (必須) 0000 10 nn アイテムまたはコレクションの用法(Usage)インデックスを定義 0x08 0x09 0x0A 0x0B Usage Minimum 0001 10 nn 配列あるいはビットマップと関連づけた用法(Usage)の開始を定義 0x18 0x19 0x1A 0x1B Usage Maximum 0010 10 nn 配列あるいはビットマップと関連づけた用法(Usage)の終了を定義 0x28 0x29 0x2A 0x2B Designator Index 0011 10 nn フィジカルディスクリプタのID 0x38 0x39 0x3A 0x3B Designator Minimum 0100 10 nn 配列あるいはビットマップと関連づけた Designator の開始インデックスを定義 0x48 0x49 0x4A 0x4B Designator Maximum 0101 10 nn 配列あるいはビットマップと関連づけた Designator の終了インデックスを定義 0x58 0x59 0x5A 0x5B String Index 0111 10 nn ストリングディスクリプタのID 0x78 0x79 0x7A 0x7B String Minimum 1000 10 nn 配列またはビットマップのコントロールに対して、ひとまとまりの連続するストリングを割り付けるときの始めのストリングのインデックス 0x88 0x89 0x8A 0x8B String Maximum 1001 10 nn 配列またはビットマップのコントロールに対して、ひとまとまりの連続するストリングを割り付けるときの終わりのストリングのインデックス 0x98 0x99 0x9A 0x9B Delimiter 1010 10 nn ローカルアイテムの開始か終了を定義 0xA8 0xA9 0xAA 0xAB
パース時の動作
- メインアイテムがでてくると新しいレポート構造が一時状態テーブルに割り当てられる。
- グローバルアイテムはメインアイテムが出てきても一時状態テーブルに残る。
- ローカルアイテムはメインアイテムが出てきたら一時状態テーブルから消える。
- 次に出てくるメインアイテムで定義されるフィールドについて記述
例
http://www.cygnal.org/ubb/Forum9/HTML/002068.html
global items | local item USAGE_PAGE LOGICAL_MIN/MAX REPORT_COUNT REPORT_SIZE | USAGE _______________________________________________________________________________________________________________ USAGE_PAGE (Generic Desktop) Generic Desktop --- --- --- --- (UNDEFINED) USAGE (Mouse) | --- --- --- {Mouse} COLLECTION (Application) | --- --- --- (applied and cleared) USAGE (Pointer) | --- --- --- {Pointer} COLLECTION (Physical) v --- --- --- (applied and cleared) USAGE_PAGE (Button) Button --- --- --- --- USAGE_MINIMUM (Button 1) | --- --- --- {Button 1.. USAGE_MAXIMUM (Button 3) | --- --- --- {Button 1..3} LOGICAL_MINIMUM (0) | [0.. --- --- | LOGICAL_MAXIMUM (1) | [0..1] --- --- | REPORT_COUNT (3) | | 3 --- | REPORT_SIZE (1) | | | 1 v INPUT (Data,Var,Abs) | | v | (applied and cleared) REPORT_COUNT (1) | | 1 v --- REPORT_SIZE (5) | | | 5 --- INPUT (Cnst,Var,Abs) v | | | --- (padding) USAGE_PAGE (Generic Desktop) Generic Desktop | | | --- USAGE (X) | | | | {X} USAGE (Y) | | | | {X, Y} LOGICAL_MINIMUM (-127) | [-127..1] | | | LOGICAL_MAXIMUM (127) | [-127..127] | v | REPORT_SIZE (8) | | v 8 | REPORT_COUNT (2) | | 2 | v INPUT (Data,Var,Rel) | | | | (applied and cleared) END_COLLECTION | | | | --- END_COLLECTION v v v v ---
タグの例
Report Size (3) //Global Report Count (2) //Global Input //Main Report Size (8) //Global Input //Main Output //Main
結果
- Input:3bitのフィールド2つ、8ビットのフィールド2つ
- Output:8bitのフィールド2つ。
レポートディスクリプタ/必須項目
HID/コレクション
- 2 つ以上のデータ(Input、Output あるいは Feature)のグループ化を開始
0xa1, 0x01, // COLLECTION (Application)
HID/トップレベルコレクション
- HIDにはコンポジットデバイス以外にも、複数のHID機能を一つのインターフェースに押込めてしまう方法が用意されている
- レポートデスクリプタでは通常単独のトップレベルコレクションが宣言される
- しかしここで複数のトップレベルコレクションを宣言すると、それぞれのトップレベルコレクションは独立して機能する
関連
チュートリアル
表示ツール
- USB Device Tree Viewer (Windows) - USBViewの改造版
- USB Monitor (Windows,有償)
- USB Prober (Mac OS X)
- lsusb (Linux)
- usbhid-dump (Linux)
- USBスニッファ
解析ツール
参考
http://documentation.renesas.com/doc/products/mpumcu/apn/sh_family/r01an0294jj_sh7216_an.pdf
http://documentation.renesas.com/doc/products/mpumcu/apn/rjj05b1417_m16cap.pdf
http://esyokunin.dee.cc/30xSub_USB_Siyou/331_Siyou1_HidKb/331_Siyou1_HidKb.html
http://www.itf.co.jp/tech/road-to-usb-master/hid_class
http://eleccelerator.com/tutorial-about-usb-hid-report-descriptors/