RK3588 Gadget 部署、DWC3 集成与排障

1. 硬件路径

RK3588 的 Device 模式由 DWC3 控制器提供，驱动在drivers/usb/dwc3（详见linuxDoc/drivers/usb/04-DWC3双角色核心与RK3588集成.md），本目录只提供其上的 UDC 框架和 function。

SoC DTS（rk3588s.dtsi）：

• usbdrd3_0（3330 行）：rockchip,rk3588-dwc3glue，子节点usb@fc000000（3340 行）snps,dwc3，dr_mode = "otg"，PHY 为u2phy0_otg+usbdp_phy0_u3（USB2+USB3/DP Combo）；
• 另一实例usb@fcd00000（3450 行）dr_mode = "host"，不做 gadget。

因此 gadget 只能在 OTG 口（通常是 Type-C 调试/OTG 口）工作，UDC 名即fc000000.usb。

2. 角色切换链

Type-C/extcon 或 role-switch 事件
 -> dwc3 drd 切换到 device 模式
 -> dwc3 gadget 注册 usb_add_gadget()
 -> /sys/class/udc/fc000000.usb 出现
 -> ConfigFS 写 UDC -> bind -> pullup

dr_mode="otg"时若无角色事件（缺 extcon/typec 配置或插的是 host 线），UDC 可能不进入 device 模式；板级 DTS 有时直接固定dr_mode="peripheral"规避。

3. 内核配置

三份 Rockchip defconfig 的 gadget 相关项：

CONFIG_USB_GADGET=y
CONFIG_USB_GADGET_DEBUG_FILES=y
CONFIG_USB_GADGET_VBUS_DRAW=500
CONFIG_USB_CONFIGFS=y
CONFIG_USB_CONFIGFS_UEVENT=y      (Android扩展)
CONFIG_USB_CONFIGFS_ACM=y
CONFIG_USB_CONFIGFS_MASS_STORAGE=y
CONFIG_USB_CONFIGFS_F_FS=y
CONFIG_USB_CONFIGFS_F_UVC=y       (仅 rockchip_linux)
CONFIG_USB_CONFIGFS_F_UAC1/UAC2/F_HID=y (仅 cpcem)

未启用任何 legacy gadget；网络 function（NCM/ECM/RNDIS）默认全关，需要时补配置。自定义usb_f_bytrans.ko/usb_f_audio_raw.ko为强制模块，确认打包进 rootfs。

4. 标准部署脚本模板

modprobe usb_f_bytrans 2>/dev/null   # 如需自定义function
mount -t configfs none /sys/kernel/config 2>/dev/null
cd /sys/kernel/config/usb_gadget
mkdir -p g1 && cd g1
echo 0x2207 > idVendor            # Rockchip VID
echo 0x0011 > idProduct
mkdir -p strings/0x409
echo "0123456789ABCDEF" > strings/0x409/serialnumber
echo "Rockchip" > strings/0x409/manufacturer
echo "RK3588 Device" > strings/0x409/product
mkdir -p configs/c.1/strings/0x409
echo "config1" > configs/c.1/strings/0x409/configuration
echo 500 > configs/c.1/MaxPower
mkdir functions/acm.usb0
ln -s functions/acm.usb0 configs/c.1/
ls /sys/class/udc/                 # 确认 fc000000.usb
echo fc000000.usb > UDC

含 ffs 时先 mount functionfs、等 daemon 写完描述符再写 UDC。

5. 分层排障

A. /sys/class/udc 为空
   -> DWC3 probe / PHY / 电源域 / dr_mode / 角色切换(extcon,typec)
B. 写 UDC 失败
   -> 名字、UDC被占用、config缺function、ffs未就绪、端点不足
C. Host 不枚举
   -> pullup是否执行(state属性)、VBUS、线缆、EP0日志(dmesg dwc3)
D. 枚举成功某function不工作
   -> set_alt是否被调、端点enable、function自身日志
E. 传输错误/慢
   -> 协商速度(current_speed)、描述符速度组、DMA/中断、Host侧驱动

常用命令：

cat /sys/class/udc/fc000000.usb/state
cat /sys/class/udc/fc000000.usb/current_speed
dmesg | grep -iE 'dwc3|gadget|configfs'
cat /proc/interrupts | grep dwc3

Host 侧配合lsusb -v、usbmon抓包定位描述符与协议问题。

6. 速度与带宽核对

链路	bulk 理论	实际预期
HS (480Mbps)	512B×13×8/ms ≈ 53MB/s	35-42MB/s
SS (5Gbps)	1024B×burst	300-450MB/s

OTG0 走 USBDP Combo PHY 支持 USB3；若板级仅接 USB2 差分线，则永远协商 HS，isoc 类 function（UVC 高分辨率、audio_raw 多声道）要按 HS 带宽重新核算。

7. 电源与挂起

• USB_GADGET_VBUS_DRAW=500：配置态最大取电 500mA，从 VBUS 取电的设计要处理 SUSPEND（composite_suspend 分发后应降至 2.5mA 规范值）；
• 自供电设备在描述符标 self-powered，并实现get_status正确应答；
• 系统休眠时 DWC3 controller suspend 与 gadget 状态恢复由 dwc3 glue 处理，恢复后 Host 可能重新枚举，用户态服务要能重放 ConfigFS 状态。

8. 安全清单

• ConfigFS 目录仅 root 写；
• 量产固件固定 VID/PID 与 function 集合，不留任意组装接口；
• ADB(ffs)默认关闭或强认证；
• mass_storage 避免导出系统分区、优先只读；
• 自定义 function（bytrans/audio_raw）的/dev节点设专用属组权限，Host 输入视为不可信。