HID 报表描述符
报表描述符用于描述USB设备与主机之间数据交互的格式。
报表描述符定义了执行设备功能的数据格式和使用方法。
报表描述符和USB的其他描述符是不一样的,它不是一个简单的表格,报表描述符是USB所有描述符中最复杂的。报表描述符非常复杂而有弹性,因为它需要处理各种用途的设备。报表的数据必须以简洁的格式来储存,这样才不会浪费设备内的储存空间以及数据传输时的总线时间。
实际上可以这样理解,报表内容的简洁,是通过报表描述符全面的、复杂的数据描述实现的。
报表描述符必须先描述数据的大小与内容。报表描述符的内容与大小因设备的不同而不同,在进行报表传输之前,主机必须先请求设备的报表描述符,只有得到了报表描述符才可正确解析报表的数据。
报表描述符是报表描述项目(Item)的集合,每一个描述项目都有相对统一的数据结构,项目很多,通过编码实现。
(1)项目
报表描述符由描述HID设备的数据项目(Item)组成,项目的第一个字节(项目前缀)由三部分构成,即项目类型(item type)、项目标志(item tag)和项目长度(item size)。其中项目类型说明项目的数据类型,项目标签说明项目的功能,项目长度说明项目的数据部分的长度。
HID的项目有短项目和长项目两种,其中短项目的格式如下图。
短项目的数据字节数由bSize的值定义,bSize为0、1、2、3时Data部分的字节数分别为0、1、2、4个字节。短项目的项目类型由bType定义,bType为0、1、2时分别为Main、Global和Local类型。
长项目可以携带较多的数据,其格式如下图。
项目中的第一个字节为上图中的特定值时表明该项目是一个长项目。长项目中的bDataSize说明Data部分的字节数,bLongItemTag在HID规范中没有定义。
下面是通过汇编实现的一个简单的报表描述符,描述符的每一行是一个项目,该描述符描述了一个从设备接收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 关闭集合
2)项目的分类
报表的项目有Main、Global和Local三大类,每一类都有多个不同的项目,实现不同的描述。
Main类项目用于定义报表描述符中的数据项。也可以组合其中的若干数据项成为一个集合。Main项目可以分为带数据的Main项目和不带数据的Main项目。带数据项的Main用于生成报表中的数据项,包括Input、Output和Feature项目。不带数据的Main项目不生成报表中的数据项,包括Collection和End Collection项目。
Global类项目实现对数据的描述,用来识别报表并且描述报表内的数据,包括数据的功能、最大与最小允许值以及数据项的大小与数目等。改变由Main类项目生成的项目状态表。Global类项目描述对后续的所有项目有效,除非遇到有新的Global类项目。
Local类项目定义控制的特征,这一类项目的作用域不超过下一个Main项目,所以在每一Main项目之前可能有多个Local项目。Local项目用于描述后面的Input、Output和Feature项目。
下表列出的是全部的项目的前缀字和简要功能说明。
项目类型 | 项目标志(Tag) | 项目前缀,nn为数据长度 | 功能说明 | |
---|---|---|---|---|
Main | Input | 8x | 1000 00 nn | 定义输入报表,主机利用该信息解析设备提供的数据。主机向控制端口发送Get_Report实现输入 |
Main | Output | 9X | 1001 00 nn | 创建输出报表,通过向设备发送Set_Report实现输出 |
Main | Feature | BX | 1011 00 nn | 定义送往设备的设置信息 |
Main | Collection | AX | 1010 00 nn | 定义2个以上数据(Input、Output和Feature)的关系为集合,Collection开始一个集合,之后的End Collection结束集合。Collection项目的数据部分说明Collection的类型 |
Main | End Collection | C0 | 1100 00 nn | 无数据 |
local | Usage Page | 0X | 0000 01 nn | 指定设备的功能.另外由于Usage项目有32位数据值,Usage Page项目用于为Usage项目在报表描述符中占居存储空间。用于存放后续的Usage项目的高16位。 |
local | Logical Minimum | 1X | 0001 01 nn | 定义变量或数组项目的逻辑最小值和最大值 |
local | Logical Maximum | 2X | 0010 01 nn | |
local | Physical Minimum | 3X | 0011 01 nn | 定义变量或数组项目的物理最小值和最大值,分别和Logical Minimum、Logical Maximum对应 |
local | Physical Maximum | 4X | 0100 01 nn | |
local | Unit Exponent | 5X | 0101 01 nn | 定义数值是基于10的指数 |
local | Unit | 6X | 0110 01 nn | 单位 |
local | Report Size | 7X | 0111 01 nn | 指定报表数据区域所包含的位数 |
local | Report ID | 8X | 1000 01 nn | 报表ID,该项目在报表中插入一个字节的报表ID |
local | Report Count | 9X | 1001 01 nn | 报表中数据域的数目 |
local | Push | AX | 1010 01 nn | 将Global项目状态表送入堆栈 |
local | Pop | BX | 1011 01 nn | 从堆栈恢复Global项目状态表 |
local | CX | 1100 01 nn – | 保留 | |
Local | Usage | 0X | 0000 10 nn | 用法索引值,表示对项目或集合建议的用法,用于当一个项目描述多个控制,对每一个变量和数组元素都有建议的用法 |
Local | Usage Minimum | 1X | 0001 10 nn | 定义阵列或位图中控制操作的第一个和最后一个用法 |
Local | Usage Maximum | 2X | 0010 10 nn | |
Local | Designator Index | 3X | 0011 10 nn | 确定用于控制的实体,指向物理描述符中的目标 |
Local | Designator Minimum | 4X | 0100 10 nn | 定义阵列或位图目标的起始和终止索引值 |
Local | Designator Maximum | 5X | 0101 10 nn | |
Local | String Index | 7X | 0111 10 nn | 确定字符串描述符中的索引值 |
Local | String Minimum | 8X | 1000 10 nn | 定义用于阵列或位图控制中字符串序列索引值的最小值和最大值 |
Local | String Maximum | 9X | 1001 10 nn | |
Local | Delimiter | AX | 1010 10 nn | 定义一组Local项目的开始和结束,1=开始,0=结束 |
Local | 1010 10 nn –1111 10 nn | 保留 |
在这些项目中,Usage Page用来指定设备的功能,而Usage项目用来指定个别报表的功能。Usage Page项目相当于是HID的子集合,Usage相当于是Usage Page的子集合。
2. 报表描述符的项目
(1)Input、Outpot和Feature项目
这3个项目用来定义报表中的数据字段。
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项目。
(2)Collection和End Collection项目
所有的报表类型都可以使用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所连结的不同类型的项目。例如数据缓冲区的内容以及缓冲区内字节数目的计数。
(3)Usage Page和Usage项目
Usage page项目的数据部分为1~2个字节,目前的定义全部都是一个字节。Usage Page定义了常用的设备功能,关于Usage Page(以及其他项目)的具体定义内容,可以查阅HID Usage tables,下表是来自HID Usage tables的Usage Page定义。
关于Usage Page的每一个有效定义项,都有一个相应的下一级定义,如Usage Page的数据项数值为1,则设备定义为Generic Desktop Controls,关于该类设备的具体功能可以在HID Usage Tables中查到具体的定义。下表是HID Usage Tables中对Generic Desktop Controls设备的功能定义。