• 本文
• リロード
• 差分
• バックアップ
• 名前変更
• リファラ
• 新規ページ
• 編集

USB/ディスクリプタ > デバイスディスクリプタ > コンフィグレーションディスクリプタ > インターフェイスディスクリプタ > HIDディスクリプタ

レポートディスクリプタ

Top / レポートディスクリプタ

HIDデバイスからホストに通知するデータのフォーマットを定義するもの。

仕様

• Device Class Definition for Human Interface Devices

概要

• HIDクラスでは、レポートと呼ばれる単位でデータを転送する
  • レポートの中にどのような情報がどのように並んでいるかは、レポートディスクリプタによって定義
• レポートディスクリプタは、他のディスクリプタと構造が全く違う
  • HIDディスクリプタに続いて送られ、可変長。
  • レポートディスクリプタのサイズはHIDディスクリプタのwDescriptorLengthで定義

HID/レポート

• HIDインターフェースでは、Input、Output、Featureの３タイプのレポートをデバイスとホストの間で転送する

  種類	説明	レポートディスクリプタのタグ	転送の種類	パイプ
  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)

• Device Class Definition for Human Interface Devices
• HID Usage Tables

レポートディスクリプタ/アイテム

• レポートディスクリプタはデバイスに関する情報を提供するまとまり（アイテム）から構成される
  • アイテムはショートアイテムとロングアイテムの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バイト

  	データ	タグとか		プレフィックス
  ビット	...	16〜23	8〜15	7	6	5	4	3	2	1	0
  バイト	3〜258	2	1	0
  フィールド	data	bLongItemTag?	bDataSize?	1111				11		10

• プレフィックスは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機能を一つのインターフェースに押込めてしまう方法が用意されています。レポートデスクリプタでは通常単独のトップレベルコレクションが宣言されます。しかしここで複数のトップレベルコレクションを宣言すると、それぞれのトップレベルコレクションは独立して機能します。

関連

• HIDディスクリプタ
• HID/レポートID
• HID/クラスリクエスト

チュートリアル

• USnooBie's USB HID Report Descriptor Tutorial

表示ツール

• USB Device Tree Viewer (Windows) - USBViewの改造版
• USB Monitor (Windows,有償)
• USB Prober (Mac OS X)
• lsusb (Linux)
• usbhid-dump (Linux)
• USBスニッファ

解析ツール

• USB Descriptor and Request Parser

参考

• 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/

関連

HID/キーボード

HID/マウス