HID 报表描述符/报告描述符

报表描述符用于描述USB HID设备与主机之间数据交互的格式。根据数据的传输方向，分为输入报告和输出报告。

• 输入报告是USB设备发送数据给主机的。大部分的USB HID设备主要实现的是输入报告。如我们平常使用的USB鼠标，就是通过我们点击鼠标按键或滑动鼠标流轮实现给主机上报鼠标的报告信息。
• 输出报告是由USB主机向USB设备发送的数据。例如我们在主机中接入多个USB键盘后。当我们使用任意一键盘如打开数字键盘开关指示灯时，主机会给系统所有连接的USB HID键盘设备发送一个HID数据报告，这样可以使所有连接到该主机的USB HID键盘状态保持一致。

USB HID设备与主机传输的是数据，这些原始的数据就像内存里的数据一样，如果没有人告诉我们这些字节干什么的，也许我们永远也不知道的。USB报表描述符的功能就是用于描述这些报告数据格式。当主机或设备收到报告数据后，会根据报告描述符的内容解析并理解这些数据的含义。

为什么不设计一种固定的数据结构呢？如像设备描述符一样的数据格式？
这是因为第一USB HID设备种类太多，而且支持多种自定义数据格式，很难定义出一种适用于所以HID设备的数据结构，第二是由于HID设备传输数据的实时性，如果在数据中填充大量的描述性信息，会导致传输的数据变的冗长，而USB HID设备使用中断传输降低了数据的传输效率，这与中断传输的快而简的设计宗旨不符。

报表描述符用于描述USB HID与主机之间传输的数据的用途和数据格式的。通过报表描述符，USB主机可以区分出报告里的数据表的含义。报表描述符和设备描述符、配置描述符和字符串描述一样，都有一个固定的描述符类型ID,并且是通过GET_DESCRIPTOR来获取的，只不过该请求发向的是USB设备的接口。

一个报表描述符可以多个数据格式，就如同一个我们可以将要传输的多种数据结构放在一个大的结构体中一样，不同的报表内容区分可以使用报告ID来识别。报告ID在报表描述符的最前端，即第一个字节。如果报描述符只包含一个报告，可以不设计报告ID.报告ID之后一般是实际的报告数据。

在报告描述符里没有写报告ID，默认报告ID是0。

报表描述符的传输

报表描述符是在设备枚举时通过控制端点0获取的，所以是控制传输。
而报告内容是通过中断端点传输的。所以对于输入报告，是通过中断输入端点传输的，而输出报告既可以通过中断输出端点传输也可以通过控制端点0传输（无输出中断端点时）。

USB的控制端点可以进行Input，Output，Feature项目的传输，中断端点可以进行Input，Output传输。

报表描述符的格式

报表描述符必须先描述数据的大小与内容。报表描述符的内容与大小因设备的不同而不同，在进行报表传输之前，主机必须先请求设备的报表描述符，只有得到了报表描述符才可正确解析报表的数据。

报表描述符并不像描述符那样包含描述符长度和描述符类型的信息，而是由一个一个的条目（item)组成。每个条目描述其条目的信息。这就类似于C语言的结构体的成员一样，有成员类型和成员名，成员类型也描述符其数据所占的长度。

HID定义了两种条目类型，分为短条目项和长条目项。

长项目我们一般不用，只用短项目。这里我们只介绍短项目。

报表描述符由描述HID设备的数据项目（Item）组成，项目的第一个字节（项目前缀）由三部分构成，即项目类型（item type）、项目标志（item tag）和项目长度（item size）。其中项目类型说明项目的数据类型，项目标签说明项目的功能，项目长度说明项目的数据部分的长度。

长项目（long item）

长项目项可以携带较多的数据，其格式如下图。

长项目中的第一个字节为上图中的特定值时表明该项目是一个长项目。长项目中的bDataSize说明Data部分的字节数，bLongItemTag在HID规范中没有定义。

短项目(short item)

• 短项目的格式如下图。
  

短项目的数据字节数由bSize的值定义：

• bSize为0、1、2、3时Data部分的字节数分别为0、1、2、4个字节。
  • 0 = 0 bytes
  • 1 = 1 byte
  • 2 = 2 bytes
  • 3 = 4 bytes
• bType为0、1、2时分别为Main、Global和Local类型。
  • 0 = Main
  • 1 = Global
  • 2 = Local
  • 3 = Reserved
• bTag:表示该条目的功能。

主项目(main item)

主项目用于定义数据域或者用于进行数据域的分组。
主项目其有5个，分别为Input,Output,Feature,Collection和End Collection.

Input、Outpot和Feature项目

Input项目可以应用到任何控制、计数器读数或其他设备传给主机的信息。一个输入报表包含一个或多个Input项目，主机使用中断输入传输来请求输入报表。

Ouput项目用来定义主机传送给设备的信息。一个输出报表包含一个或多个Outpot项目。输出报表包含控制状态的数据。如果有中断输出管道，HID1.1兼容主机使用中断输出传输来传送输出报表，否则使用Set_Report控制请求。

Feature项目应用到主机传送给设备的信息，或是主机从设备读取Feature项目。一个特征报表包含一个或多个Feature项目，Feature项目通常是包合影响设备与其组件整体行为的配置。特征报表通常是控制可以使用实际的控制面板调整的设置，例如主机可以使用虚拟控制面板来让用户选择控制特征。主机使用 Set_Report与Get_Report请求来传送与接收特征报表。

在每一个Input、Output和Feature项目的前缀字之后是32位描述数据，目前最多定义了9个位，余的位则是保留。位0~8的定义中只有位7不能应用于Input项目，除此之外其他的位定义都适应于Input、Output和Feature项目。

Input、Outpot和Feature项目,这3个项目用来定义报表中的数据字段。

FEATURE(Data,Ary,Abs) B1 00
INPUT(Data,Ary,Abs) 81 00
OUTPUT(Data,Ary,Abs) 91 00

Input,Output,Feature,Collection都是用于描述数据域信息的，其各位可选的值如：

• BIT0:表示数据域是变量还是常量。
• BIT1:表示是数组还是变量
• BIT2:给示是绝对值还是相对值
• BIT3 :Wrap或No Wrap
• BIT4:线性或非线性
• BIT5 :PREFERRED或非PREFERRED
• BIT6 :NOT NULL Postion或Null State
• BIT7:NO Volatitle或Volatitle
• BIT8 :BitFiled或Buffered

Collection和End Collection项目

Collection共有四种，分别为Physical,Application,Logical和Vendoer Defined.

所有的报表类型都可以使用Collection与 End Collection项目来将相关的Main类型项目组成群组。这两个项目分别用于打开和关闭集合。所有在Collection与End Collection项目之间的Main类型项目都是 Collection的一部分。

Collection有3种类型：Application、Physical与Logical，其项目的数据项的值分别为1、0和2。厂商也可以自己定义Collection类型，数据项的值为80h~FFh保留给厂商定义。End Collection项目无数据项。

Application Collection包含有共同用途的项目或执行单一功能的项目。例如键盘的开机描述符将键盘的按键与LED指示灯数据集合成一个Application Collection。所有的报表必须在一个Application Collection内。

Physical Collection包含在一个单一几何点上的数据项目，可以将每个位置的数据集合成一个 Physical Collection。在设备报告多个传感器的位置的时候，使用Physical Collection指明不同的数据来自不同的传感器。

Logical Collection形成一个数据结构，包含由 Collection所连结的不同类型的项目。例如数据缓冲区的内容以及缓冲区内字节数目的计数。

COLLCTION(Physical) A1 00
COLLCTION(Application) A1 01
COLLCTION(Logical) A1 02
COLLCTION(Vendoer Defined.) A1 xx

End Collection是Collection条目的结束标志：

END_COLLECTION C0

全局项目（Global Item）

全局项目主要用来选择用途页(Usage Page)，定义数据域的长度(Report Count)、数量（Report Size）、报告ID(ReportId)等。

全局项目描述对后续的所有项目有效，除非遇到有新的全局项目。

常见的全局项目有：

• Usage Page(用途页)
• Logical Minimum(逻辑最小值)
• Logical Maxinum(逻辑最大值)
• Physical Minimum（物理最小值）
• Physical Maximum（物理最大值）
• Report Size：数据域大小,表示每个数据域有多少位
• Report Count:数据域有多少个数据域。
• ReportId:报告ID

局部项目（local Item）

局部项目用于定义数据的控制特性，如该数据域的用途，用途的最大值，用途的最小值等。

局部项目只在局部有效，遇到一个主条目后，它的失效。

常见的局部数据项目有：

• Usage :用途
• Usage Minmum:用途的最小值
• Usage Maxmum:用途的最大值。

##报表描述符示例

下面是通过汇编实现的一个简单的报表描述符，描述符的每一行是一个项目，该描述符描述了一个从设备接收2个字节的输入报表和发送2个字节到设备的输出报表。

HID_Report_desc_table:
db 06h, A0h, FFh ; Usage Page(Vendor defined) 定义设备功能
db 09h, A5h ; Usage(Vendor Defined) 定义用法
db A1h, 01h ; Collection(Application) 开一个集合
db 09H, A6h ; Usage(Vendor defined) 定义用法

                    ;   输入报表 
db  09h, A7h        ;   Usgae(Vendor defined)      定义用法 
db  15h, 80h        ;   Logical Minimum             定义输入最小值=-128 
db  25h, 7Fh        ;   Logical Maximum             定义输入最大值=+27 
db  75h, 08h        ;   Report Size                  定义报表数据项大小=8 
db  95h, 02h        ;   Report Count                 定义报表数据向个数=2 
db  81h, 02h        ;   Input(Data,Variable,Absolute)  输入项目 

                    ;   输出报表 
db  09h, A9h        ;   Usgae(Vendor defined)      定义用法 
db  15h, 80h        ;   Logical Minimum             定义输入最小值=-128 
db  25h, 7Fh        ;   Logical Maximum             定义输入最大值=+27 
db  75h, 08h        ;   Report Size                  定义报表数据项大小=8 
db  95h, 02h        ;   Report Count                 定义报表数据向个数=2 
db  91h, 02h        ;   Output(Data,Variable,Absolute)   输出项目 

db  C0h             ; End Collection                关闭集合 

```