瑞芯微RK系列USB排障指南｜Host枚举、DWC3性能、configfs Gadget与UVC实测

当你的RK3576开发板USB接口今天插 U 盘当 Host，明天接电脑当 Gadget，角色切换时“设备不识别”“速度只有2.0”“UVC 出图卡顿”到底该先查哪？排障第一步不是改驱动，而是分清这口USB现在是什么角色，问题出在枚举、性能、角色切换还是某个Gadget 功能。

本文基于触觉智能Purple Pi OH2（RK3576开发板），按枚举→性能→角色/Gadget→UVC/UAC→合规测试一路拆解，本文思路可通用各类RK平台。

触觉智能Purple Pi OH2默认标定数据：RK_USB_GADGET=y、RK_USB_ADBD=y（VID 0x2207、厂商Rockchip）。USB 问题九成能归到"角色没切对/枚举没成功/gadget 没配好/性能不够"四类。

枚举失败：设备插上没反应

枚举是USB一切功能的前提。设备插上没反应，按"硬件 → PHY → 控制器 → 总线 → 驱动"逐级看：

第一分水岭是 lsusb/dmesg 里有没有设备；"插上没反应"先别怀疑驱动，先确认线/供电/PHY。本板 USB 走的 DWC3（drivers/usb/dwc3/），其 debugfs.c 提供端点和控制器状态，是查"控制器到底看没看到设备"的好入口。

板上排查（adb 直连）：先看设备在不在 USB 树、什么速率，再看枚举日志，最后进 DWC3 控制器状态。注意：dwc3 debugfs 实际路径是 /sys/kernel/debug/usb/<控制器名>/（RK3576 为 23000000.usb），不是 /sys/kernel/debug/usb/dwc3/*：

# 1) 总线枚举：设备在不在、什么速率（5000M=USB3 / 480M=USB2）
adb shell lsusb -t
# 2) 枚举日志：USB2/USB3 协商、controller reset/disconnect 事件
adb shell dmesg | grep -iE "usb|dwc3|xhci|phy"
# 3) DWC3 控制器状态（本板实测路径；23000000=usb_drd0，23400000=usb_drd1）
adb shell ls /sys/kernel/debug/usb/23000000.usb/    # ep* / mode / link_state / regdump
adb shell cat /sys/kernel/debug/usb/23000000.usb/mode

本板实测：lsusb 可见 USB2（Bus1, 480M）与 USB3（Bus2, 5000M）两条总线，接了一个 1a86:8091 的 USB HUB；dmesg 里 dwc3 23000000.usb 的 "device reset / device disconnect" 就是枚举成功/断开时的事件。

USB性能与带宽

性能问题先分清"理论多少vs实测多少"：

• 理论带宽
  USB2.0 高速 480Mbps（实际约 35-40MB/s）、USB3.0 5Gbps（实际约 350-450MB/s）——别拿理论值当实测；
• 带宽去向
  同一控制器下多端点共用带宽，UVC 出流 + ADB 同时跑会互相挤；
• 排查
  用dd实测块设备、或官方USB性能分析工具测吞吐，对比是否达到该协议层的实际水平；低于预期再看PHY是跑在USB2还是USB3（链路协商）。

官方《USB Performance Analysis》文档给出了逐层（PHY/控制器/总线/应用）的性能分析方法，先确认"协议层没降级"（比如明明USB3设备却协商成 USB2）再谈优化。

板上排查（adb直连）：先确认链路协商没有降级，再看控制器状态，最后拿实际吞吐对比：

# 1) 链路协商速率：5000M=super-speed(USB3)、480M=high-speed(USB2)
adb shell lsusb -t
# 2) 控制器链路状态 + 寄存器（link_state: On/Suspend/Not available…）
adb shell cat /sys/kernel/debug/usb/23000000.usb/link_state
adb shell head -5 /sys/kernel/debug/usb/23000000.usb/regdump
# 3) 实测吞吐（接 USB 存储时）：读 /dev/sdX 对比理论值
adb shell dd if=/dev/sda of=/dev/null bs=4M count=256 2>&1 | tail -1

角色与Gadget：OTG/DRD与configfs

本板usb_drd0_dwc3/usb_drd1_dwc3是双角色（DRD/OTG）控制器，角色由 dwc3/drd.c 按 USB-C 控制器（本板husb311 TCPC）或 extcon 切换。当 Device（Gadget）时，功能通过 configfs配置：

ls /sys/kernel/config/usb_gadget/           # 已配置的 gadget
cat /sys/kernel/config/usb_gadget/rockchip/UDC
cat /sys/kernel/config/usb_gadget/rockchip/idVendor   # 0x2207
# 角色：/sys/class/usb_role/.../role 本板无此属性，改用 dwc3 mode / typec data_role

常见问题：角色没切到Device（插电脑没反应先看角色是不是 host）、UDC 没绑定（configfs 配了但 UDC 为空）、gadget 功能没 enable。本板 RK_USB_ADBD=y 走 gadget 实现 adbd（RK_USB_VID=0x2207），ADB 连不上先查 gadget 是否 enable。

板上排查（adb 直连，RK3576 实测）：本机adb连的就是23000000.usb这个 gadget（UDC已绑定、function 为 ffs.adb、VID=0x2207）。两个DRD口当前角色用 dwc3 debugfs 的 mode看最直接，USB-C方向/供电看typec类：

# configfs gadget 实测状态
adb shell cat /sys/kernel/config/usb_gadget/rockchip/idVendor      # 0x2207
adb shell cat /sys/kernel/config/usb_gadget/rockchip/idProduct     # 0x0006
adb shell cat /sys/kernel/config/usb_gadget/rockchip/UDC           # 23000000.usb（已绑定）
adb shell ls /sys/kernel/config/usb_gadget/rockchip/functions/     # ffs.adb
# 两个 DRD 口当前角色（dwc3 debugfs mode）
adb shell cat /sys/kernel/debug/usb/23000000.usb/mode             # device（跑 ADB）
adb shell cat /sys/kernel/debug/usb/23400000.usb/mode             # host（接 U 盘/网卡）
# USB-C 方向/供电（husb311 TCPC 驱动）：host [device] 当前=device；source [sink] 对端供电
adb shell cat /sys/class/typec/port0/data_role /sys/class/typec/port0/power_role

UVC/UAC：板子当摄像头/声卡

把板子做成USB UVC摄像头或UAC声卡，用的是external/uvc_app（uvc_config.sh 通过 configfs 配 uvc.gs6 功能，含 YUYV/MJPEG/framebased各分辨率的帧率档）与 external/uac_app。

UVC/UAC 排障的两份官方 Trouble_Shooting（Gadget 与 Host）是现成方法：先确认"枚举到没、什么描述符、什么格式"，再谈"出不出流"。

板上排查（adb 直连，RK3576 实测）：先确认内核编译了哪些 configfs 功能——本板 CONFIG_USB_CONFIGFS_F_UVC=y（UVC可用），但UAC1/UAC2 未编译，要做UAC声卡需先改内核配置重编，再谈uac_app：

# 查内核编译的 gadget 功能
adb shell zgrep -E "CONFIG_USB_CONFIGFS_F_(UVC|UAC1|UAC2)" /proc/config.gz
# 实测输出：
# CONFIG_USB_CONFIGFS_F_UVC=y
# # CONFIG_USB_CONFIGFS_F_UAC1/UAC2 is not set   ← UAC 需改内核配置

合规性与SQ测试

量产前验证USB电气/信号质量，走官方USB2_Compliance_Test与 USB_SQ_Test（信号质量测试）。这类需要示波器/USB测试仪等硬件，判定按官方流程与眼图标准。

本节涉及测试仪器，软件侧结论以PHY/链路协商检查（如 lsusb -t 的速率、dmesg的USB3/USB2协商日志）为主。

USB排障先定位角色与链路：枚举失败按 硬件→PHY→控制器→总线→驱动 逐级看（lsusb/dmesg/dwc3 debugfs）→ 性能对比协议层实测 → 角色/Gadget 看 configfs 与 UDC → UVC/UAC 用官方两份 Trouble_Shooting → 合规上仪器。

RK3576板端实测记录

以下触觉智能Purple Pi OH2（RK3576开发板）+Debian Bookworm（内核 6.1.99，arm64）上通过adb直连执行，本文结论均得到验证；其中两处需注意：dwc3 debugfs路径为 /sys/kernel/debug/usb/23000000.usb/（非 dwc3/），/sys/class/usb_role/.../role无此属性（角色看dwc3 mode / typec data_role）：

• 官方文档依据

docs/cn/Common/USB/Rockchip_Developer_Guide_USB_CN.pdf
docs/cn/Common/USB/Rockchip_Developer_Guide_Linux_USB_Performance_Analysis_CN.pdf
docs/cn/Common/USB/Rockchip_Developer_Guide_USB2_Compliance_Test_CN.pdf
docs/cn/Common/USB/Rockchip_Developer_Guide_USB_SQ_Test_CN.pdf
docs/cn/Common/USB/Rockchip_Developer_Guide_USB_FFS_Test_Demo_CN.pdf
docs/cn/Common/USB/Rockchip_Trouble_Shooting_Linux4.19_USB_Gadget_UVC_CN.pdf
docs/cn/Common/USB/Rockchip_Trouble_Shooting_Linux_USB_Host_UVC_CN.pdf
docs/cn/Linux/ApplicationNote/Rockchip_Quick_Start_Linux_USB_Gadget_CN.pdf
docs/cn/Common/USB/Rockchip_RK3576_Developer_Guide_USB_CN.pdf

• SDK源码依据

kernel-6.1/drivers/usb/dwc3/（core.c、drd.c、debugfs.c）
kernel-6.1/arch/arm64/boot/dts/rockchip/ido-evb7609-v1a.dtsi（usb_drd0/1_dwc3、u2phy0/1、combphy0/1、usbdp_phy、husb311）、rk3576.dtsi（phys 绑定）
external/uvc_app/（main.c、uvc_config.sh、rk3576/usb_config.sh）
external/uac_app/
output/final.env（RK_USB_GADGET/ADBD/VID=0x2207）

Purple Pi OH2开发板，是触觉智能RK3576核心板SOM7609系列配套的评估开发板，搭载4核A72+4核A53+M0多核异构处理器，主频2.2GHz，集成6Tops算力 NPU，轻松应对AI推理、边缘计算与轻量级AI端侧学习。配套完善SDK、丰富资料与Demo，有助于项目前期快速开发验证。

触觉智能SOM7609系列核心板尺寸仅40.5×40.5mm，专为空间受限场景打造。基于RK3576/RK3576J SoC，集成高性能GPU与VPU，支持4K视频编解码与多屏异显；提供PCIe、USB3.2、双路千兆以太网、MIPI-DSI/CSI、eDP、CAN、SPI、I2C等丰富接口，灵活扩展。支持Linux、Android、开源鸿蒙OpenHarmony等丰富系统，配套丰富软硬件资料与技术支持，助力产品快速落地。