如何检测设备连接状态

对于自供电 USB 设备,当 USB 连接状态改变时,设备类驱动及应用层需要及时获悉相关事件并做对应处理,从而达成支持热插拔、降低功耗等目的。

USB 设备核心驱动提供了如下 API 用于设备类驱动及应用层检测 USB 连接状态:

上述 API 需要在 USB 上电之后,访问 USB 相关寄存器才能获得有效数据,因此需要在加载 USB 核心驱动之后才能调用。 如果要在 USB 未上电时就能获取 USB 状态信息,需要借助外部电路的支持,例如通过 GPIO 中断来检测 VBUS 的上电掉电事件,具体请参考硬件设计手册(Hardware Design Guide)中的 USB 插入检测电路参考设计。

借助上述软硬件检测方案,可以分辨如下 USB 设备连接状态改变事件:

事件

usbd_get_status

status_changed

VBUS GPIO中断

VBUS状态

设备复位(保持与主机连接)

ATTACHED

INIT -> ATTACHED

N/A

ON

设备复位(保持连接断开)

INIT

N/A

N/A

OFF

设备复位(保持与充电器连接)

INIT

N/A

N/A

ON

连接到主机

ATTACHED

DETACHED -> ATTACHED

Y (上升沿)

OFF -> ON

从主机断开

DETACHED

ATTACHED -> DETACHED

Y (下降沿)

ON -> OFF

连接到充电器

INIT

or

DETACHED

N/A

Y (上升沿)

OFF -> ON

从充电器断开

INIT

or

DETACHED

N/A

Y (下降沿)

ON -> OFF

连接挂起(suspend)

DETACHED

ATTACHED -> DETACHED

与主机设置相关

与主机设置相关

连接恢复(resume)

ATTACHED

DETACHED -> ATTACHED

与主机设置相关

与主机设置相关

两个典型的应用场景:

基于软件的解决方案

如果对功耗要求不严苛,允许 USB 电源常开,可通过 status_changed,只借助软件的方式获取设备连接状态改变事件,一般用法如下:

  • 检测到与 USB 主机断开连接时,终止通信,注销并重新注册 USB 设备,等待下次与 USB 主机连接

  • 检测到与 USB 主机连接时,恢复通信

具体处理流程参考下图:

../../../_images/usb_status_detection_sw_zh.svg

基于硬件辅助的解决方案

如果对功耗要求严苛,希望在 USB 设备与主机未连接时能够关闭 USB 相关电源,可通过 GPIO 中断来检测 VBUS 的上电掉电事件,一般用法如下:

  • 检测到与 USB 主机断开连接或者连接到 USB 充电器时,注销 USB 设备,以达省电目的

  • 检测到与 USB 主机连接时,注册 USB 设备,使能 USB 通信

具体处理流程参考下图:

../../../_images/usb_status_detection_hw_zh.svg

如何定制设备描述符

描述符概述

USB 设备通过描述符定义设备功能,USB 描述符的拓扑结构示例如下图所示:

../../../_images/usb_device_descriptors_zh.svg

其中:

  • 一个 USB 设备只有一个设备描述符(Device Descriptor)

  • 一个 USB 设备可以有多个(由设备描述符的 bNumConfigurations 指定)配置描述符(Configuration Descriptor),但同时只允许一个配置描述符生效

  • 一个配置描述符下可以有多个(由配置描述符的 bNumInterfaces 指定)接口描述符(Interface Descriptor),且多个接口描述符可以同时生效

  • 一个接口描述符下可以有多个(由接口描述符的 bNumEndPoints 指定)端点描述符(Endpoint Descriptor),且多个端点描述符可以同时生效

另外,还有其它一些常用的描述符:

  • 设备描述符、配置描述符和接口描述符都有一些相关的功能描述,这些描述定义为字符描述符(String Descriptor)

  • 对于需要同时支持高速和全速模式的设备,还需要同时定义设备限定描述符(Device Qualifier Descriptor)和其它速率配置描述符(Other Speed Configuration Descriptor)

  • 对于复合设备,还需要在多个类接口描述符之前,增加一个接口关联描述符(Interface Association Descriptor,IAD)

  • 某些 USB 设备类需要定义与设备类相关的特定描述符,比如 HID 设备需要定义报表描述符(Report Descriptor)

High-speed Mode:
Device Descriptor
└─ Identifies basic device information (USB version, class, VID/PID, EP0 MPS, etc)

Configuration Descriptor
└─ Contains total length of the entire configuration(power supply information, interface count, etc)

Device Qualifier Descriptor
└─ Provides device class/EP0 MPS/config count for the other speed (HS↔FS)

Other Speed Configuration Descriptor
└─ Mirrors the configuration at the other speed (interfaces/endpoints/attributes)

String Descriptor
└─ Provides language IDs and textual identifiers (Manufacturer/Product, etc)

备注

具体的描述符定义,请参考 USB 规范。

描述符数据结构

一般情况下,USB 主机会按如下顺序获取 USB 设备的描述符信息:

  • 获取设备描述符,USB 设备需要返回设备描述符信息

  • 获取配置描述符,USB 设备需要返回描述符拓扑结构中当前有效的配置描述符及其以下节点(包含接口描述符和端点描述符)的全部描述符信息

  • 获取配置描述符对应的字符串描述符,USB 设备需要根据主机控制请求中的字符串类型信息,返回当前有效配置描述符下对应的字符串描述符信息,包含语言 ID、串号、厂商、产品等字符串信息

另外,USB 主机可能还会尝试获取 USB 设备的以下描述符信息:

  • 获取设备限定描述符,如果 USB 设备有支持,需要返回设备限定描述符信息

  • 获取其它速率配置描述符,如果 USB 设备有支持,需要返回描述符拓扑结构中当前有效的配置描述符对应的其它速率配置描述符及其节点(包含接口描述符和端点描述符)的全部描述符信息

  • 获取其它速率配置描述符对应的字符串描述符,USB 设备需要根据主机控制请求中的字符串类型信息,返回当前有效配置描述符对应的其它速率配置描述符下对应的字符串描述符信息,包含语言 ID、串号、厂商、产品等字符串信息

  • 获取设备类相关的描述符,USB 设备需要根据设备类规范返回相关的描述符信息

  • 获取 USB 主机相关的描述符,比如 Windows 主机会尝试获取索引值为 238(对应 16 进制数字 0xEE)的 Microsoft OS 字符串描述符(Microsoft OS String Descriptor)

备注

如果 USB 设备不支持某些描述符,在收到 USB 主机端相关请求时,需要返回 STALL 状态,复合规范的 STALL 并不会影响 USB 主机与设备间的通信,也不会影响 USB 设备的功能。

鉴于上述 USB 主机获取 USB 设备描述符的行为,建议 USB 设备定义以下几个独立数组用于存储 USB 主机需要获取的描述符信息:

  • 设备描述符,仅包含设备描述符信息

  • 配置描述符,每个配置描述符分别定义,包含其自身及其以下节点(包含接口描述符和端点描述符)的全部描述符信息

  • 字符串描述符,包含语言 ID 在内的每个字符串描述符分别定义

  • 设备限定描述符,仅包含设备限定描述符信息

  • 其它速率配置描述符,每个其它速率配置描述符分别定义,包含其自身及其以下节点(包含接口描述符和端点描述符)的全部描述符信息;为节省存储资源,也可与配置描述符共用一个数组,运行时动态替换描述符类型数据

  • 设备类相关的描述符,按设备类规范定义

  • USB 主机相关的描述符,按 USB 主机相关规范和应用需求定义

描述符定制项

USB 设备协议栈中定义的所有设备类,其全部描述符信息均开源并允许开发者根据设计需求定制。 但为兼容性,对于基于 USB 规范的标准类设备,一般仅建议对以下描述符信息进行定制:

VID 与 PID

开发者可以直接使用 USB 协议栈默认使用的 Realtek VID 和 PID,如需自定义,需要注册成为 USB-IF 成员(参考 https://www.usb.org/members),然后按照 USB-IF 的流程申请 VID 和 PID。 开发者如果需要使用 Realtek VID,并自定义 PID,请与 Realtek FAE 联系。

备注

使用 Realtek VID 和 PID, 并不意味着产品符合 USB 规范,仍需要进行 USB 认证。

字符串描述符

字符串描述符是可选的,设备描述符、配置描述符和接口描述符都有字符串描述符索引字段,如果不支持字符串描述符,描述符索引为 0。可定义非 0 的索引值并定义对应的字符串描述符:

Device Descriptor
│   iManufacturer            (Manufacturer String Index)
│   iProduct                 (Product String Index)
│   iSerialNumber            (SerialNumber String Index)
│
├── Configuration Descriptor
│   ├── iConfiguration       (Configuration String Index)
│   └── Interface Descriptor
│       └── iInterface       (Interface String Index)
│
└── USB String Table
    ├── String Descriptor    (Index 0, Must be read first)
    ├── String Descriptor    (Index 1)
    ├── String Descriptor    (Index 2)
    ├── String Descriptor    (Index 3)
    │    ...

字符串描述符结构

主机在枚举初期读取设备描述符,其中包含了三个字段:iManufacturer/iProduct/iSerialNumber。 这些字段的值只是索引号,当对于某些设备不没有与之对应的字符串时,开发者只需要将这些字符串索引的值设为 0 即可。

当设备插入电脑时,操作系统会读取这些字符串并在设备管理器或弹窗中显示,比如依次设为 1, 2, 3。

  • 索引 1 (iManufacturer): 厂商名称。例如: "Realtek Semiconductor Corp."

  • 索引 2 (iProduct): 产品名称。例如: "Realtek USB Controller"

  • 索引 3 (iSerialNumber): 序列号。例如: "00E04C000001"

USB String Table
│
├── String Descriptor     (Index 0: Must be read first!)
│   └── LANGID Code Array (Language ID Array)
│       └── 0x0409        (English - United States)
│
├── String Descriptor     (Index 1: Pointed by `iManufacturer` index)
│   └── "Realtek Semiconductor Corp." (Unicode)
│
├── String Descriptor     (Index 2: Pointed by the `iProduct` index)
│   └── "Realtek USB Controller" (Unicode)
│
├── String Descriptor     (Index 3: Pointed by the `iSerialNumber` index)
│   └── "00E04C000001" (Unicode)
│
└── String Descriptor     (Index 4/5/6/...: Optional/Customizable)
  • 字符串描述符(索引 0)

    String Descriptor     (Special: Language ID)
    │   bLength           (Descriptor length)
    │   bDescriptorType   (String descriptor type. Fixed to 0x03)
    └── LANGID Code Array
        │ wLANGUAGEID(0)  (First Language ID)
        │ wLANGUAGEID(1)  (Second Language ID)
        │ ...
    
    • 地位:它是“字符串描述符的描述符”,主机在获取任何具体字符串之前,必须优先读取 Index 0,以确认设备支持的语言类型。

    • 特殊性:它不包含字符串,而是包含设备支持的语言 ID 列表。当主机向设备发送获取字符串索引为 0 时,这并不表示要获取索引为 0 的字符串,而是表示获取设备支持的 语言 ID (LANGID) 列表。

    • 参数值:一般情况下,语言 ID 为通常是 0x0409 美式英语。如当为中文时,可以将语言 ID 设为 0x0804。

    备注

    即使开发者的设备只在某国使用,也建议支持 0x0409,因为这是 Windows/Linux 默认尝试的 ID。

  • 字符串描述符(索引 1, 2, 3)

    String Descriptor
    │   bLength         (Descriptor length)
    │   bDescriptorType (String descriptor type. Fixed to 0x03)
    └── bString         (UNICODE encoded string)
    

    bString 字符串必须是 UNICODE (UTF-16LE) 编码,每个字符占 2 字节。例如 'A' -> 0x41, 0x00。

    备注

    • USB 规范要求字符串描述符使用 UNICODE 编码,设备核心驱动提供了 usbd_get_str_descriptor() 函数用于将 UTF-8 编码的字符串转为 UNICODE 编码的字符串描述符,方便开发者用普通字符串来维护字符串信息。设备全局字符串(厂商、产品、序列号)在 usbd_dev_info_t 中以普通字符串配置,转换由 Core 自动完成。

    • 协议栈目前仅提供了英文字符串描述符示例,如需支持其它语言类型,请参考 USB 规范定义所需的语言 ID 描述符及对应的字符串描述符

  • 其他自定义字符串(索引 4, 5, 6...)

    只要不与标准冲突,可以自定义索引为 4, 5, 6...的字符串。

端点描述符

对于一般应用,端点描述符中的以下字段支持自定义:

  • bEndpointAddress:端点地址

  • wMaxPacketSize:最大包长,一般建议按 USB 规范定义的最大值(不高于 SoC 硬件支持的最大值)来设定,除非有特别需求,不建议随意修改

  • bInterval:传输间隔

备注

协议栈保证默认提供的端点配置对所有 SoC 可用,如需调整,请参考 硬件配置 ,务必熟知相关 USB 规范和 SoC 硬件限制后再做谨慎调整,否则可能导致兼容性问题甚至枚举失败。