TinyUSB
tinyusb回调函数
2026-06-14
本文链接为:http://www.usbzh.com/article/detail-1716.html ,欢迎转载，转载请附上本文链接。
TinyUSB 的回调函数采用“按名调用”机制：不需要注册，只需实现特定名称的函数，协议栈就会自动调用。
这些回调主要分为两类：USB 核心描述符回调（定义设备结构）和各类设备功能回调（实现具体通信逻辑）。
核心描述符回调 (必须实现)
用于向主机报告 USB 设备的能力和结构，是枚举过程的必经环节。
| 回调函数 | 功能说明 | 调用时机 |
|---|---|---|
| tud_descriptor_device_cb | 返回设备描述符（Device Descriptor） | 主机请求获取设备信息（如 VID/PID、版本号） |
| tud_descriptor_configuration_cb | 返回配置描述符（Configuration Descriptor） | 主机请求获取配置信息（如供电方式、总功耗、接口和端点数量） |
| tud_descriptor_string_cb | 返回字符串描述符（String Descriptor） | 主机请求获取可读的文本信息（如制造商名、产品名、序列号） |
| tud_descriptor_device_qualifier_cb | 返回设备限定符描述符 | 用于支持高速模式的设备，查询在其他速度下的信息 |
| tud_descriptor_other_speed_configuration_cb | 返回其他速率配置描述符 | 用于支持高速模式的设备，获取在其他速度下的配置 |
| tud_descriptor_bos_cb | 用于向主机返回 BOS（Binary Device Object Store，二进制设备对象存储）描述符 | 可选 的回调函数 |
注意：如果没有正确实现上述核心回调（特别是前两个），编译时会直接报 undefined reference 错误，这也是最常见的入门问题。
厂商自定义回调
| 函数 | 功能说明 | 调用时机 | 典型用途 |
|---|---|---|---|
| tud_vendor_control_xfer_cb | 厂商自定义控制传输回调 | 主机通过端点 0 发送厂商请求（bmRequestType 的接收方为 TUSB_REQ_RCPT_VENDOR） | 实现自定义控制协议（如配置参数、读取状态、执行特殊命令） |
设备回调
| 函数 | 功能说明 | 调用时机 | 典型用途 |
|---|---|---|---|
| tud_mount_cb | 设备挂载成功回调 | USB 枚举完成，主机已配置设备，可以开始通信 | 初始化应用层状态、点亮指示灯、记录日志表示设备已就绪 |
| tud_umount_cb | 设备卸载回调 | 主机断开连接或去配置设备 | 清理资源、关闭指示灯、进入待机模式 |
| tud_suspend_cb | 总线挂起回调 | 主机进入睡眠或空闲模式，USB 总线进入挂起状态 | 执行省电操作（如降低时钟、关闭外设）、记录挂起事件 |
| tud_resume_cb | 总线恢复回调 | 主机从挂起状态唤醒，总线恢复正常通信 | 恢复全速运行、重新初始化通信通道 |
设备功能回调 (按需实现)
根据你在 tusb_config.h 中开启的 CFG_TUD_XXX 宏来选择性实现，未使用的类无需实现。
1. CDC (通信设备类)
实现虚拟串口功能，用于与 PC 或其他主机进行双向数据通信。
| 回调函数 | 功能说明 | 常用场景 |
|---|---|---|
| tud_cdc_rx_cb | 收到数据时触发 | 读取主机发来的数据 |
| tud_cdc_tx_complete_cb | 数据发送完成时触发 | 确认数据已成功发出，可用于流控 |
| tud_cdc_line_state_cb | 主机端串口状态变化时触发（DTR, RTS） | 通知 MCU 主机是否已打开串口终端，可用于控制数据发送 |
| tud_cdc_line_coding_cb | 主机端串口配置改变时触发（波特率、数据位等） | 获取主机设置的波特率参数，同步应用逻辑 |
| tud_cdc_rx_wanted_cb | 接收到预设的特定字符时触发 | 实现命令识别、快速响应特定信号 |
| tud_cdc_notify_complete_cb | 通知消息发送完成时触发 | 确认串口状态通知已送达主机 |
| tud_cdc_send_break_cb | 主机发送 Break 信号时触发 | 检测到通信中断信号，执行复位或特殊处理 |
2. MSC (海量存储设备类)
模拟 U 盘、SD 卡读卡器等块存储设备。
| 回调函数 | 功能说明 | 调用时机 |
|---|---|---|
| tud_msc_inquiry_cb | 响应 SCSI 询问命令，返回设备信息 | 主机查询设备类型、厂商、产品 ID 等 |
| tud_msc_capacity_cb | 响应读容量命令，返回存储介质信息 | 主机获取磁盘的扇区数量和扇区大小 |
| tud_msc_read10_cb | 响应读 (READ10) 命令 | 主机要从设备读取数据块 |
| tud_msc_write10_cb | 响应写 (WRITE10) 命令 | 主机要向设备写入数据块 |
| tud_msc_test_unit_ready_cb | 响应测试就绪命令，报告设备状态 | 主机检查存储介质是否已准备好（如 SD 卡是否插入/初始化完成） |
| tud_msc_start_stop_cb | 响应启停命令，处理介质加载/弹出 | 主机请求加载或卸载存储介质 |
| tud_msc_is_writable_cb | 响应写保护查询，报告介质是否可写 | 主机在写入前检查设备是否为只读状态 |
| tud_msc_scsi_cb | 处理其他 SCSI 命令 | 当需要实现标准 SCSI 命令集以外的特殊功能时 |
3. HID (人机接口设备类)
模拟键盘、鼠标、游戏手柄等输入设备。
| 回调函数 | 功能说明 |
|---|---|
| tud_hid_report_complete_cb | HID 报告发送完成时触发，可用于确认数据已发出 |
| tud_hid_set_report_cb | 收到主机发来的 SET_REPORT 请求时触发（如键盘 LED 状态、输出报告） |
| tud_hid_get_report_cb | 收到主机发来的 GET_REPORT 请求时触发 |
| tud_hid_set_protocol_cb | 收到 SET_PROTOCOL 请求时触发（在启动协议和报告协议间切换） |
4. Audio & MIDI (音频与音乐设备接口)
| 回调函数 | 功能说明 |
|---|---|
| tud_audio_rx_done_pre_read_cb | 音频数据接收完成，准备读取前调用 |
| tud_audio_set_itf_close_other_cb | 切换备用音频接口时调用 |
| tud_midi_rx_cb | 收到 MIDI 消息时触发，用于读取实时演奏数据 |
| tud_midi_tx_complete_cb | MIDI 消息发送完成时触发 |
5. Vendor (自定义类)
实现自定义协议或 WinUSB 设备，使用批量端点进行高速数据传输。
| 回调函数 | 功能说明 |
|---|---|
| tud_vendor_control_xfer_cb | 处理端点 0 的厂商自定义控制请求 |
| tud_vendor_rx_cb | 批量 OUT 端点收到数据时触发 |
| tud_vendor_tx_complete_cb | 批量 IN 端点数据发送完成时触发 |
设备状态与总线事件回调
| 回调函数 | 功能说明 | 触发场景 |
|---|---|---|
| tud_mount_cb | 设备挂载成功（已被主机识别和配置） | USB 枚举成功，主机准备就绪 |
| tud_umount_cb | 设备卸载（主机断开连接或去配置） | USB 线缆拔出，或主机禁用设备 |
| tud_suspend_cb | USB 总线挂起 | 主机进入睡眠或空闲状态以省电 |
| tud_resume_cb | USB 总线恢复 | 主机从挂起状态唤醒设备 |
本文链接为:http://www.usbzh.com/article/detail-1716.html ,欢迎转载，转载请附上本文链接。一个关键点：这些回调函数本质上都是可选的弱符号定义（TU_ATTR_WEAK），这意味着如果你不实现它们，协议栈会使用一个空的默认实现，不会导致编译错误。
