USB 描述符速查摘要USB 描述符用于告诉主机设备是什么、有哪些配置、接口、端点以及 HID 设备的数据报告格式。目录1. 描述符层级2. 设备描述符 Device Descriptor3. 配置描述符 Configuration Descriptor4. 接口描述符 Interface Descriptor5. HID 描述符 HID Descriptor6. 端点描述符 Endpoint Descriptor7. 字符串描述符 String Descriptor8. HID 报告描述符 Report Descriptor9. 常用速记1. 描述符层级描述符作用设备描述符说明“我是什么设备”配置描述符说明“这个配置包含多少接口、怎么供电、总长度多少”接口描述符说明“这个接口是什么功能”类特殊描述符说明 HID、CDC、Audio 等类的专用信息端点描述符说明“数据通过哪些端点传输”Device Descriptor └── Configuration Descriptor ├── Interface Descriptor 0 │ ├── Class-specific Descriptor │ └── Endpoint Descriptor └── Interface Descriptor 1 ├── Class-specific Descriptor └── Endpoint DescriptorTips:端点 0 是默认控制端点不需要端点描述符。端点描述符只描述非 0 端点。2. 设备描述符 Device Descriptor设备描述符固定长度为18字节即0x12。偏移字段大小类型说明0bLength1Number描述符长度设备描述符固定为18即0x121bDescriptorType1Constant描述符类型设备描述符为DEVICE 0x012bcdUSB2BCDUSB 协议版本例如 USB 2.0 为0x02004bDeviceClass1Class设备类代码由 USB-IF 定义5bDeviceSubClass1SubClass设备子类代码6bDeviceProtocol1Protocol设备协议代码7bMaxPacketSize01Number端点 0 最大包长只能是8、16、32、648idVendor2ID厂商 ID即 VID由 USB-IF 分配10idProduct2ID产品 ID即 PID由厂商分配12bcdDevice2BCD设备版本号由厂商自定义14iManufacturer1Index厂商字符串描述符索引为0表示没有15iProduct1Index产品字符串描述符索引为0表示没有16iSerialNumber1Index序列号字符串描述符索引为0表示没有17bNumConfigurations1Number设备支持的配置数量示例constuint8_tDeviceDescriptor[]{0x12,// bLength0x01,// bDescriptorType: Device0x00,0x02,// bcdUSB: USB 2.0小端 0x02000x00,// bDeviceClass0x00,// bDeviceSubClass0x00,// bDeviceProtocol0x40,// bMaxPacketSize0: 64 bytes0x34,0x12,// idVendor: 0x1234小端0x78,0x56,// idProduct: 0x5678小端0x00,0x01,// bcdDevice: 1.000x01,// iManufacturer0x02,// iProduct0x03,// iSerialNumber0x01// bNumConfigurations};3. 配置描述符 Configuration Descriptor配置描述符自身固定长度为9字节但wTotalLength包含该配置下的所有相关描述符。偏移字段大小类型说明0bLength1Number配置描述符长度固定为91bDescriptorType1Constant描述符类型配置描述符为CONFIGURATION 0x022wTotalLength2Number当前配置下所有描述符的总长度4bNumInterfaces1Number当前配置支持的接口数量5bConfigurationValue1Number配置值主机通过SetConfiguration选择该配置6iConfiguration1Index配置字符串描述符索引为0表示没有7bmAttributes1Bitmap配置属性如总线供电、自供电、远程唤醒8bMaxPower1mA最大功耗单位是2 mAbmAttributes常见位含义位含义bit7固定为1bit61表示自供电0表示总线供电bit51表示支持远程唤醒bit4~0保留必须为0常见值值含义0x80总线供电不支持远程唤醒0xA0总线供电支持远程唤醒0xC0自供电不支持远程唤醒0xE0自供电支持远程唤醒bMaxPower单位为2 mAbMaxPower实际电流50100 mA100200 mA250500 mA示例constuint8_tConfigDescriptor[]{0x09,// bLength: 9 bytes0x02,// bDescriptorType: Configuration0x22,0x00,// wTotalLength: 34 bytes小端0x01,// bNumInterfaces: 1 interface0x01,// bConfigurationValue0x00,// iConfiguration0x80,// bmAttributes: Bus-powered0x32// bMaxPower: 100mA, 0x32 50 * 2mA};4. 接口描述符 Interface Descriptor接口描述符用于说明某个接口的功能类型例如 HID、CDC、MSC。偏移字段大小类型说明0bLength1Number接口描述符长度固定为91bDescriptorType1Constant描述符类型接口描述符为INTERFACE 0x042bInterfaceNumber1Number当前接口编号从0开始3bAlternateSetting1Number备用接口设置编号4bNumEndpoints1Number该接口使用的端点数量不包括端点05bInterfaceClass1Class接口类代码6bInterfaceSubClass1SubClass接口子类代码7bInterfaceProtocol1Protocol接口协议代码8iInterface1Index接口字符串描述符索引为0表示没有常见接口类代码类bInterfaceClass说明HID0x03鼠标、键盘、自定义 HIDCDC0x02/0x0A虚拟串口、通信设备MSC0x08U 盘、大容量存储Audio0x01USB 音频Vendor Specific0xFF厂商自定义协议常见接口三元组设备/接口bInterfaceClassbInterfaceSubClassbInterfaceProtocolHID 自定义设备0x030x000x00HID Boot 键盘0x030x010x01HID Boot 鼠标0x030x010x02MSC U 盘 SCSI/Bulk-Only0x080x060x50CDC 控制接口 ACM0x020x020x01CDC 数据接口0x0A0x000x00厂商自定义0xFF自定义自定义Note:很多复合设备会把bDeviceClass设置为0x00或0xEF具体功能由接口描述符里的bInterfaceClass决定。5. HID 描述符 HID DescriptorHID Descriptor 是 HID 类特殊描述符不属于 USB 2.0 通用描述符表。它最重要的作用是告诉主机Report Descriptor 的类型和长度。偏移字段大小说明0bLength1HID 描述符长度通常为91bDescriptorType1HID 描述符类型固定为0x212bcdHID2HID 类规范版本如 HID 1.11 为0x01114bCountryCode1国家代码通常为05bNumDescriptors1下级类描述符数量6bDescriptorType1下级描述符类型Report Descriptor 为0x227wDescriptorLength2Report Descriptor 的总长度单位字节示例constuint8_tHIDDescriptor[]{0x09,// bLength: 9 bytes0x21,// bDescriptorType: HID Descriptor0x11,0x01,// bcdHID: HID 1.11小端 0x01110x00,// bCountryCode: Not localized0x01,// bNumDescriptors: 10x22,// bDescriptorType: Report Descriptor0x3F,0x00// wDescriptorLength: 63 bytes小端};注意wDescriptorLength必须等于实际 Report Descriptor 数组长度否则主机读取报告描述符时容易失败。6. 端点描述符 Endpoint Descriptor端点描述符用于描述非 0 端点的方向、类型、最大包长和轮询间隔。偏移字段大小类型说明0bLength1Number端点描述符长度固定为71bDescriptorType1Constant端点描述符为ENDPOINT 0x052bEndpointAddress1Endpoint端点地址包含方向和端点号3bmAttributes1Bitmap端点属性主要表示传输类型4wMaxPacketSize2Number该端点最大包长6bInterval1Number轮询间隔主要用于中断/同步传输6.1bEndpointAddress位含义bit7方向1 IN0 OUTbit6~4保留必须为0bit3~0端点号范围1 ~ 15方向站在主机角度看IN 设备 - 主机 OUT 主机 - 设备常见端点地址地址含义0x81Endpoint 1 IN0x01Endpoint 1 OUT0x82Endpoint 2 IN0x02Endpoint 2 OUT6.2bmAttributes低 2 位表示传输类型bit1~0传输类型00Control 控制传输01Isochronous 同步传输10Bulk 批量传输11Interrupt 中断传输常见值0x02 Bulk 0x03 Interrupt6.3wMaxPacketSize速度/类型常见最大包长Full-Speed Interrupt最大64字节Full-Speed Bulk最大64字节High-Speed Bulk最大512字节Low-Speed Interrupt最大8字节多字节字段小端存储64 0x0040 数组中写成 0x40, 0x006.4bIntervalbInterval是主机轮询端点的间隔。端点类型含义Interrupt轮询间隔Isochronous服务间隔Bulk通常可填0主机按需调度Control非 0 端点通常不用控制传输Full-Speed HID 中断端点常见bInterval 1 ~ 10HID 键盘端点示例constuint8_tEndpointDescriptor[]{0x07,// bLength0x05,// bDescriptorType: Endpoint0x81,// bEndpointAddress: EP1 IN0x03,// bmAttributes: Interrupt0x08,0x00,// wMaxPacketSize: 8 bytes0x0A// bInterval: 10 ms};7. 字符串描述符 String Descriptor字符串描述符用于给主机提供厂商名、产品名、序列号等人类可读信息。偏移字段大小说明0bLength1描述符总长度1bDescriptorType1字符串描述符类型固定为0x032bStringNUTF-16LE 编码的字符串内容长度计算bLength 2 字符数 * 2英文字符在 UTF-16LE 中的写法A 0x41, 0x00 B 0x42, 0x00 C 0x43, 0x007.1 字符串描述符 0LANGID字符串描述符索引0比较特殊不是普通字符串而是语言 ID 表。constuint8_tStringLangID[]{0x04,// bLength: 4 bytes0x03,// bDescriptorType: String0x09,0x04// LANGID: English (United States) 0x0409小端};常见 LANGIDLANGID小端写法含义0x04090x09, 0x04English - United States0x08090x09, 0x08English - United Kingdom0x08040x04, 0x08Chinese - Simplified / China0x04040x04, 0x04Chinese - Traditional / Taiwan0x0C040x04, 0x0CChinese - Traditional / Hong Kong0x04110x11, 0x04Japanese0x04120x12, 0x04Korean0x04070x07, 0x04German0x040C0x0C, 0x04French - France0x0C0A0x0A, 0x0CSpanish - Spain0x04100x10, 0x04Italian0x04190x19, 0x04Russian常见字符串层级String 0: LANGID String 1: Manufacturer String 2: Product String 3: Serial Number8. HID 报告描述符 Report DescriptorHID Report Descriptor 用于告诉主机HID 数据包里的每一位、每一个字节分别代表什么含义。注意:Report Descriptor 不是实际传输的数据而是“数据格式说明书”。常见项目项目作用Usage Page用途页例如 Generic Desktop、Keyboard、ConsumerUsage具体用途例如 Keyboard、Mouse、Volume IncrementCollection开始一个集合Logical Min/Max数据逻辑取值范围Report Size每个字段占多少 bitReport Count字段数量Input设备发给主机Output主机发给设备Feature双向配置类数据8.1 Boot Keyboard 报告描述符最终定义Input Report: 8 字节 Byte0: Modifier Byte1: Reserved Byte2~Byte7: 最多 6 个普通按键 KeyCode Output Report: 1 字节 bit0~bit4: Num Lock / Caps Lock / Scroll Lock / Compose / Kana bit5~bit7: paddingconstuint8_tHID_ReportDescriptor[]{0x05,0x01,// Usage Page (Generic Desktop)0x09,0x06,// Usage (Keyboard)0xA1,0x01,// Collection (Application)0x05,0x07,// Usage Page (Keyboard/Keypad)0x19,0xE0,// Usage Minimum (Keyboard LeftControl)0x29,0xE7,// Usage Maximum (Keyboard Right GUI)0x15,0x00,// Logical Minimum (0)0x25,0x01,// Logical Maximum (1)0x75,0x01,// Report Size (1)0x95,0x08,// Report Count (8)0x81,0x02,// Input (Data, Variable, Absolute)0x95,0x01,// Report Count (1)0x75,0x08,// Report Size (8)0x81,0x03,// Input (Constant, Variable, Absolute)0x95,0x05,// Report Count (5)0x75,0x01,// Report Size (1)0x05,0x08,// Usage Page (LEDs)0x19,0x01,// Usage Minimum (Num Lock)0x29,0x05,// Usage Maximum (Kana)0x91,0x02,// Output (Data, Variable, Absolute)0x95,0x01,// Report Count (1)0x75,0x03,// Report Size (3)0x91,0x03,// Output (Constant, Variable, Absolute)0x95,0x06,// Report Count (6)0x75,0x08,// Report Size (8)0x15,0x00,// Logical Minimum (0)0x25,0x65,// Logical Maximum (101)0x05,0x07,// Usage Page (Keyboard/Keypad)0x19,0x00,// Usage Minimum (Reserved)0x29,0x65,// Usage Maximum (Keyboard Application)0x81,0x00,// Input (Data, Array, Absolute)0xC0// End Collection};该描述符长度63 字节 0x3F发送小写auint8_treport[8]{0x00,// modifier0x00,// reserved0x04,// A0x00,0x00,0x00,0x00,0x00};发送大写Auint8_treport[8]{0x02,// Left Shift0x00,0x04,// A0x00,0x00,0x00,0x00,0x00};松开按键uint8_treport[8]{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00};8.2 Consumer Control音量、静音PC 音量加、音量减、静音属于 Consumer Control不是普通键盘页。功能Usage ID静音 Mute0xE2音量加 Volume Increment0xE9音量减 Volume Decrement0xEA1 字节报告格式bit0: Mute bit1: Volume bit2: Volume - bit3~bit7: paddingconstuint8_tHID_ReportDescriptor[]{0x05,0x0C,// Usage Page (Consumer)0x09,0x01,// Usage (Consumer Control)0xA1,0x01,// Collection (Application)0x15,0x00,// Logical Minimum (0)0x25,0x01,// Logical Maximum (1)0x09,0xE2,// Usage (Mute)0x09,0xE9,// Usage (Volume Increment)0x09,0xEA,// Usage (Volume Decrement)0x75,0x01,// Report Size (1)0x95,0x03,// Report Count (3)0x81,0x02,// Input (Data, Variable, Absolute)0x75,0x05,// Report Size (5)0x95,0x01,// Report Count (1)0x81,0x03,// Input (Constant, Variable, Absolute)0xC0// End Collection};该描述符长度29 字节 0x1D实际发送uint8_treport;report0x01;// Mutereport0x02;// Volumereport0x04;// Volume-report0x00;// Release[!tip]HID 按键类动作通常要发送“按下”再发送“松开”。例如音量加一次先发0x02再发0x00。9. 常用速记描述符类型值固定长度/重点Device0x01固定18字节Configuration0x02固定9字节重点wTotalLengthString0x03UTF-16LE索引 0 是 LANGIDInterface0x04固定9字节Endpoint0x05固定7字节HID0x21HID 类特殊描述符HID Report0x22HID 数据格式说明多字节字段全部小端存储Input 设备 - 主机 Output 主机 - 设备 IN/OUT 方向也是站在主机角度命名Report Size * Report Count 当前字段占用 bit 数 所有 Input 字段累加 设备发送报告长度 所有 Output 字段累加 主机下发报告长度