最終更新:2016-10-14 (金) 06:11:29 (228d)  

レポートディスクリプタ はてなブックマークを見る
Top / レポートディスクリプタ

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

概要

HID/レポート

3ボタンマウスの例

  • レポートディスクリプタ/マウス
  • 左側がレポートのバイナリ。右のは説明。
    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
    バイト012
    ビット765432107654321076543210
    Paddingボタン3ボタン2ボタン1XY
  • バイナリをエンコード/デコードする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〜3924〜3116〜238〜1576543210
    バイト43210
    フィールドdata4data3data2data1bTagbTypebSize

ロングアイテム

  • bSizeが2
  • dataは最大255バイト
    データタグとかプレフィックス
    ビット...16〜238〜1576543210
    バイト3〜258210
    フィールドdatabLongItemTag?bDataSize?11111110
  • プレフィックスは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 tagbTagbTypebSize意味bSize=0bSize=1bSize=2bSize=3
    Input100000nn1つ以上の物理的なコントロールが提供するデータに関する情報について記述-0x810x82-
    Output100100nn出力データフィールドを定義するために使用-0x910x92-
    Collection101000nn2 つ以上のデータ(Input、Output あるいは Feature)のグループ化を開始-0xA10xA2-
    Feature101100nnデバイスに送ることができるデバイスコンフィギュレーション情報について記述-0xB10xB2-
    End Collection110000nnCollection に対応し、2 つ以上のデータ(Input、Output あるいは Feature)のグループ化を終了0xC0---

グローバルアイテム (12種類)

  • データの記述に使用
  • 続くフィールドのデフォルト属性になる
    • Global items become the default attributes for all subsequent data fields in that descriptor.

タグ

  • item tagbTagbTypebSize意味bSize=0bSize=1bSize=2bSize=3
    Usage Page (必須)000001nn現在の Usage Page を指定している値。アイテム使用法のインデックスを定義-0x050x060x07
    Logical Minimum (必須)000101nn変数または配列のアイテムが報告する最小値。たとえば、0~128 まで X位置価値を報告するマウスは、0 の論理的な最小値をもつ。0x140x150x160x17
    Logical Maximum (必須)001001nn変数または配列のアイテムが報告する最大値。たとえば、0~128 まで X位置価値を報告するマウスは、128 の論理的な最大値をもつ。0x240x250x260x27
    Physical Minimum?001101nn物理的な最小範囲値(論理値xUnit値)0x340x350x360x37
    Physical Maximum010001nn物理的な最大範囲値(論理値xUnit値)0x440x450x460x47
    Unit Exponent010101nn基数を 10 としたときの指数(2 の補数)0x540x550x560x57
    Unit011001nn単位値0x640x650x660x67
    Report Size (必須)011101nnレポートフィールドのサイズをビットで指定する符号なし値0x740x750x760x77
    Report ID100001nnレポート ID を指定する符号なし値0x840x850x860x87
    Report Count (必須)100101nnアイテムのデータフィールド数を指定する符号なし整数
    何個のフィールドがこの特定のアイテムのためにレポートに含められるかを決定する(したがってビットが何個であるかがレポートに付け加えられる)
    0x940x950x960x97
    Push101001nnグローバル・アイテムの状態一覧をスタックに保管0xA40xA50xA60xA7
    Pop101101nnスタックの先頭に保管されているグローバル・アイテムの状態一覧を取り出す0xB40xB50xB60xB7

ローカルアイテム (10種類)

  • 特性の定義づけに使用
  • Local items only describe the data fields defined by the next Main item

タグ

  • item tagbTagbTypebSize意味bSize=0bSize=1bSize=2bSize=3
    Usage (必須)000010nnアイテムまたはコレクションの用法(Usage)インデックスを定義0x080x090x0A0x0B
    Usage Minimum000110nn配列あるいはビットマップと関連づけた用法(Usage)の開始を定義0x180x190x1A0x1B
    Usage Maximum001010nn配列あるいはビットマップと関連づけた用法(Usage)の終了を定義0x280x290x2A0x2B
    Designator Index001110nnフィジカルディスクリプタのID0x380x390x3A0x3B
    Designator Minimum010010nn配列あるいはビットマップと関連づけた Designator の開始インデックスを定義0x480x490x4A0x4B
    Designator Maximum010110nn配列あるいはビットマップと関連づけた Designator の終了インデックスを定義0x580x590x5A0x5B
    String Index011110nnストリングディスクリプタのID0x780x790x7A0x7B
    String Minimum100010nn配列またはビットマップのコントロールに対して、ひとまとまりの連続するストリングを割り付けるときの始めのストリングのインデックス0x880x890x8A0x8B
    String Maximum100110nn配列またはビットマップのコントロールに対して、ひとまとまりの連続するストリングを割り付けるときの終わりのストリングのインデックス0x980x990x9A0x9B
    Delimiter101010nnローカルアイテムの開始か終了を定義0xA80xA90xAA0xAB

パース時の動作

  • メインアイテムがでてくると新しいレポート構造が一時状態テーブルに割り当てられる。
    • グローバルアイテムはメインアイテムが出てきても一時状態テーブルに残る。
    • ローカルアイテムはメインアイテムが出てきたら一時状態テーブルから消える。
  • 次に出てくるメインアイテムで定義されるフィールドについて記述

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

関連

チュートリアル

表示ツール

解析ツール

参考