前置知識：建議先讀第1章：USB子系統(tǒng)架構(gòu)，了解RK3576的USB硬件拓撲。本文專注軟件層面：DWC3控制器的驅(qū)動、寄存器、調(diào)試接口和實戰(zhàn)排錯。

一、DWC3控制器到底是個什么東西

RK3576里的兩個USB 3.1 OTG控制器（usb@23000000和usb@23400000）都是Synopsys的DWC3 IP。這個IP不是單純的Host控制器，也不是單純的Device控制器，而是一個三合一的架構(gòu)：

三種工作模式由GCTL.PRTCAPDIR寄存器控制：

PRTCAPDIR值	模式	行為
0	DEVICE	純Device，走Gadget模塊，暴露UDC
1	HOST	純Host，走xHCI模塊，暴露USB Host
3	OTG	Dual-Role，監(jiān)聽ID/VBUS，自動切換Host/Device

RK3576 SDK中DTS配的dr_mode = "otg"就是告訴DWC3初始模式為OTG。

二、DWC3 debugfs：第一個調(diào)試入口

很多教程說DWC3的debugfs路徑是/sys/kernel/debug/dwc3/，這在RK3576上是錯的。RK3576內(nèi)核里，DWC3的debugfs掛在平臺設備名下面。

2.1 DRD0（OTG0）調(diào)試路徑

# DRD0 的 debugfs 入口ls/sys/kernel/debug/usb/23000000.usb/# 板子實際輸出：# ep0in  ep1in  ep2in  ep3in  ep4in  ep5in  ep6in# ep0out  ep1out  ep2out  ep3out  ep4out  ep5out# link_state mode regdump testmode

每個文件的作用（對照內(nèi)核源碼kernel-6.1/drivers/usb/dwc3/debugfs.c）：

文件	功能	源碼對應
regdump	轉(zhuǎn)儲所有DWC3全局寄存器	dwc3_regs[]數(shù)組，含GCTL/DCFG/DSTS/GSNPSID等200+寄存器
mode	查看/切換工作模式	dwc3_mode_fops，寫host/device/otg
link_state	查看USB鏈路狀態(tài)	dwc3_link_state_fops，顯示On/Recovery/SS.Disabled等
testmode	設置USB2測試模式	dwc3_testmode_fops，支持test_j/test_k/test_packet等
ep*in/ep*out	端點子目錄	每個端點有tx_fifo_size/trb_ring/transfer_type等屬性

2.2 DRD1（OTG1）調(diào)試路徑

# DRD1 的 debugfs 入口ls/sys/kernel/debug/usb/23400000.usb/# 板子實際輸出：# link_state lsp_dump mode regdump testmode

DRD1沒有ep*子目錄，因為它通常配置為純Host模式（dr_mode = "host"），Gadget端點不會創(chuàng)建。

2.3 XHCI調(diào)試路徑

DWC3切換到Host模式后，內(nèi)核xHCI驅(qū)動會在下面創(chuàng)建入口：

ls/sys/kernel/debug/usb/xhci/# 板子輸出:# xhci-hcd.0.auto

2.4 Trace Events（官方文檔確認的三種trace）

內(nèi)核提供了三組USB相關(guān)的tracepoint，官方PDFRockchip_Trouble_Shooting_Linux4.19_USB_Gadget_UVC_CN.pdf和Rockchip_Developer_Guide_USB_CN.pdf中均有確認：

# DWC3 控制器事件ls/sys/kernel/debug/tracing/events/dwc3/# 確認的事件：# dwc3_alloc_request  dwc3_complete_trb# dwc3_ctrl_req     dwc3_ep_dequeue# dwc3_ep_queue     dwc3_event# dwc3_free_request   dwc3_gadget_ep_cmd# dwc3_gadget_ep_disable dwc3_gadget_ep_enable# dwc3_gadget_generic_cmd dwc3_gadget_giveback# dwc3_prepare_trb   dwc3_readl# dwc3_writel# Gadget/UDC 事件ls/sys/kernel/debug/tracing/events/gadget/# usb_ep_alloc_request  usb_ep_free_request# usb_ep_queue      usb_ep_dequeue# usb_ep_enable      usb_ep_disable# usb_ep_set_halt     usb_ep_clear_halt# usb_gadget_connect   usb_gadget_disconnect# usb_gadget_vbus_connect usb_gadget_vbus_disconnect# XHCI 主機事件ls/sys/kernel/debug/tracing/events/xhci-hcd/

開啟trace的姿勢：

echo1 > /sys/kernel/debug/tracing/events/dwc3/enablecat/sys/kernel/debug/tracing/trace_pipe# 停止echo0 > /sys/kernel/debug/tracing/events/dwc3/enable

三、Core模塊：dwc3_probe()的完整流程

DWC3控制器的初始化是Linux平臺驅(qū)動框架的標準流程，源碼在kernel-6.1/drivers/usb/dwc3/core.c。

3.1 GSNPSID：芯片身份證

dwc3_core_is_valid()讀的第一個寄存器就是GSNPSID：

// kernel-6.1/drivers/usb/dwc3/core.creg = dwc3_readl(dwc->regs, DWC3_GSNPSID);dwc->ip = DWC3_GSNPS_ID(reg);

RK3576用的是DWC31（USB 3.1版本），GSNPSID會返回0x5533xxxx。如果讀到其他值，說明寄存器映射錯了或者時鐘沒開。

實戰(zhàn)驗證：

cat/sys/kernel/debug/usb/23000000.usb/regdump | grep GSNPSID# 正常: GSNPSID: 0x5533102a（示例值，具體隨版本變化）

3.2關(guān)鍵寄存器速查

寄存器	縮寫	用途
GSNPSID	Global Synopsys ID	芯片ID，確認DWC3 IP版本
GCTL	Global Control	核心控制寄存器，PRTCAPDIR就在這里，決定Host/Device/OTG
DCFG	Device Configuration	設備配置：速度、端點數(shù)、地址等
DSTS	Device Status	設備狀態(tài)：當前鏈路狀態(tài)（USBLNKST）、連接速度（CONNECTSPD）

3.3時鐘和復位

dwc3_probe()中時鐘獲取的邏輯：

ret= clk_bulk_get_all(dwc->dev, &dwc->clks);ret= clk_bulk_prepare_enable(dwc->num_clks, dwc->clks);ret= reset_control_deassert(dwc->reset);

probe卡在EPROBE_DEFER通常是時鐘或復位控制器還沒準備好。

四、Gadget模塊：Device模式下的調(diào)試

DWC3處于Device模式時，內(nèi)核會注冊UDC（USB Device Controller）。

4.1 UDC sysfs屬性

# 查看 UDC 列表ls/sys/class/udc/# 正常: 23000000.usb# 查看 UDC 屬性ls/sys/class/udc/23000000.usb/# state current_speed uevent ...cat/sys/class/udc/23000000.usb/state# 正常: configured / not-attached / attached / powered / default / addresscat/sys/class/udc/23000000.usb/current_speed# 正常: SuperSpeed / HighSpeed / FullSpeed / LowSpeed# 板子實際: state=configured, current_speed=high-speed

state的完整狀態(tài)機：not-attached -> attached -> powered -> default -> address -> configured

4.2 ConfigFS Gadget配置

Rockchip SDK使用ConfigFS配置USB Gadget功能（官方PDF確認的路徑）

# 查看 UDC 列表ls/sys/class/udc/# 正常: 23000000.usb# 查看 UDC 屬性ls/sys/class/udc/23000000.usb/# state current_speed uevent ...cat/sys/class/udc/23000000.usb/state# 正常: configured / not-attached / attached / powered / default / addresscat/sys/class/udc/23000000.usb/current_speed# 正常: SuperSpeed / HighSpeed / FullSpeed / LowSpeed# 板子實際: state=configured, current_speed=high-speed

4.3 Gadget Trace

ls/sys/kernel/config/usb_gadget/# rockchip/ls/sys/kernel/config/usb_gadget/rockchip/# UDC bDeviceClass bDeviceProtocol bcdUSB configs functions idProduct idVendor stringsls/sys/kernel/config/usb_gadget/rockchip/functions/# rndis.gs0 uvc.gs6 ...

五、Host模塊：xHCI驅(qū)動分析

DWC3切換到Host模式后，內(nèi)核加載xhci-hcd驅(qū)動。

5.1 xHCI調(diào)試入口

ls/sys/kernel/debug/usb/xhci/# xhci-hcd.0.auto# 查看 USB 設備樹（所有已枚舉的設備）cat/sys/kernel/debug/usb/devices# 典型輸出:# T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=480 MxCh= 1# D: Ver= 2.00 Cls=09(hub ) Sub=00 Prot=00 MxPS=64 #Cfgs= 1

5.2 xHCI Trace

echo1>/sys/kernel/debug/tracing/events/xhci-hcd/enablecat/sys/kernel/debug/tracing/trace_pipe

六、DRD/OTG模塊：角色切換的內(nèi)幕

OTG模式是RK3576 USB最容易出問題的地方。角色切換涉及三層機制。

6.1切換機制總覽

兩種路徑：

1.usb-role-switch（Type-C CC芯片方案）：CC芯片（HUSB311/FUSB302）通過I2C通知內(nèi)核角色變化，內(nèi)核調(diào)用usb_role_switch回調(diào)

2.extcon機制（無CC芯片，直接GPIO檢測ID）：USB2 PHY通過extcon框架傳遞USB_HOST狀態(tài)變化

6.2源碼中的切換流程

// kernel-6.1/drivers/usb/dwc3/drd.cvoiddwc3_otg_update(structdwc3 *dwc,boolignore_idstatus){  id = extcon_get_state(dwc->edev, EXTCON_USB_HOST);  vbus = extcon_get_state(dwc->edev, EXTCON_USB); if(id && !vbus)    dwc3_set_mode(dwc, DWC3_GCTL_PRTCAP_HOST); elseif(vbus)    dwc3_set_mode(dwc, DWC3_GCTL_PRTCAP_DEVICE);}

dwc3_set_mode()把切換請求放入workqueue：

// kernel-6.1/drivers/usb/dwc3/core.cvoiddwc3_set_mode(struct dwc3 *dwc, u32 mode){  dwc->desired_dr_role = mode; queue_work(system_freezable_wq, &dwc->drd_work);}

6.3手動切換模式

官方文檔確認的方法（RK3576 PDF中的OTG mode章節(jié)）：

# [New 方法] 通過 DWC3 debugfs 切換echohost > /sys/kernel/debug/usb/23000000.usb/mode   # 強制 Hostechodevice > /sys/kernel/debug/usb/23000000.usb/mode  # 強制 Deviceechootg > /sys/kernel/debug/usb/23000000.usb/mode    # 恢復 OTG# [Legacy 方法] 通過 USB2 PHY 切換（老版本內(nèi)核）echohost > /sys/devices/platform/2602e000.syscon/2602e000.syscon:usb2-phy@0/otg_modeechoperipheral > /sys/devices/platform/2602e000.syscon/2602e000.syscon:usb2-phy@0/otg_mode

6.4切換過程中的寄存器操作

角色切換的核心是__dwc3_set_mode()（core.c）：

// 切換前：CoreSoftReset 確保時鐘同步reg =dwc3_readl(dwc->regs,DWC3_GCTL);reg |=DWC3_GCTL_CORESOFTRESET;dwc3_writel(dwc->regs,DWC3_GCTL, reg);msleep(100); // 等待時鐘同步reg &= ~DWC3_GCTL_CORESOFTRESET;dwc3_writel(dwc->regs,DWC3_GCTL, reg);// 切換：修改 GCTL.PRTCAPDIRdwc3_set_prtcap(dwc, desired_dr_role);// 切換后：初始化對應模塊// Host -> dwc3_host_init() + phy_set_mode(USB_HOST)// Device -> dwc3_gadget_init() + phy_set_mode(USB_DEVICE)// OTG -> dwc3_otg_init() + dwc3_otg_update()

七、中斷處理：DWC3的中斷架構(gòu)

DWC3的中斷分三類：

7.1全局中斷（GEVT）

處理USB總線級事件：連接、斷開、復位、suspend/resume。通過GEVTEN（Global Event Enable）寄存器使能，事件寫入GEVTADR/GEVTSIZ指定的內(nèi)存隊列。

7.2端點事件（DEP Event）

每個端點有自己的事件寄存器。DEP_BASE(n) + DEPCMD下發(fā)端點命令，DEPEVT上報端點事件（transfer complete、stream event等）。

7.3 OTG事件（OEVT）

OTG模式下獨有的事件：

事件位	含義
CONIDSTSCHNGEN	Connector ID狀態(tài)變化（插入/拔出）
BDEVSESSVLDDETEN	B設備Session有效（VBUS檢測到）
ADEVSESSENDDETEN	A設備Session結(jié)束
HRRCONFNOTIFEN	Host Negotiation Role確認

中斷合并：DWC3支持中斷合并（Interrupt Moderation），通過GUCTL寄存器配置，減少高頻事件下的中斷風暴。在USB視頻傳輸?shù)葓鼍跋?，合理設置合并參數(shù)可以顯著降低CPU占用。

八、調(diào)試方法速查

8.1 regdump：寄存器快照

cat/sys/kernel/debug/usb/23000000.usb/regdump |head-40# 輸出示例（關(guān)鍵字段）：# GSNPSID:   0x5533102a <- DWC31 IP# GCTL: ? ? ? ?0x00000003 ?<- PRTCAPDIR=3 (OTG)# DCFG: ? ? ? ?0x04000000 ?<- 設備配置# DSTS: ? ? ? ?0x00000001 ?<- 設備狀態(tài)# GSTS: ? ? ? ?0x00020001 ?<- 當前模式

正常工作時拍一份，出問題后再拍一份，diff對比差異。

8.2 link_state：鏈路狀態(tài)

cat/sys/kernel/debug/usb/23000000.usb/link_state# 可能的輸出:# On     <- 正常工作# Sleep ? ? ? <- USB2 suspend# Recovery ? ?<- USB3 恢復中# SS.Disabled <- SuperSpeed 被禁用# Compliance ?<- 合規(guī)測試模式

8.3 mode：工作模式

cat/sys/kernel/debug/usb/23000000.usb/mode# 輸出: host / device / otg

8.4 testmode：USB2合規(guī)測試

官方PDF中USB合規(guī)測試章節(jié)確認的五種測試模式：

cat/sys/kernel/debug/usb/23000000.usb/testmode# 輸出: no_test / test_j / test_k / test_se0_nak / test_packet / test_force_enableechotest_j > /sys/kernel/debug/usb/23000000.usb/testmode

九、實戰(zhàn)案例

案例一：DRD模式切換失敗，Type-C正反插沒反應

現(xiàn)象：

RK3576板子，Type-C口插入PC，/sys/class/udc/23000000.usb/state顯示not-attached，dmesg沒有VBUS相關(guān)日志。

排查：

# 1. 查當前模式cat/sys/kernel/debug/usb/23000000.usb/mode# 輸出: otg <- 模式配置對了# 2. 查 TCPM 日志（CC 芯片日志）cat?/sys/kernel/debug/usb/tcpm-2-004e/log |?tail?-20# 沒有日志！說明 CC 芯片沒檢測到插入# 3. 查 extcon 狀態(tài)cat?/sys/class/extcon/usb-role-switch/state# 輸出: HOST=0, USB=0 <- 既不是 Host 也不是 Device# 4. 查 DTS 中 CC 芯片配置cat?/sys/firmware/devicetree/base/i2c@*/husb311@4e/compatible# 輸出空 -> CC 芯片驅(qū)動沒加載# 5. 查 I2C 總線dmesg | grep husb311# 輸出: husb311: probe of 2-004e failed with error -121 (遠程I/O錯誤)

根因：I2C總線不通，HUSB311芯片通信失敗?？赡茉颍篒2C引腳復用配置錯誤、上拉電阻沒焊、或者芯片地址不對。

修復：修復I2C后驗證：

dmesg | grep husb311# 正常: husb311 2-004e: husb311 probedcat/sys/class/udc/23000000.usb/state# 正常: configured

案例二：Gadget枚舉失敗，PC端顯示"未知USB設備"

現(xiàn)象：RK3576通過Type-C連PC，Gadget配置了RNDIS+UVC，但PC端識別為"未知USB設備"。

排查：

# 1. 查 UDC 狀態(tài)cat/sys/class/udc/23000000.usb/state# 輸出: configured <- UDC 層已經(jīng)配置好了cat?/sys/class/udc/23000000.usb/current_speed# 輸出: high-speed <- 只有 USB 2.0 速度# 2. 查 ConfigFS 配置ls?/sys/kernel/config/usb_gadget/rockchip/configs/b.1/# f1 -> ../../functions/rndis.gs0# f2 -> ../../functions/uvc.gs6/# 配置看起來正確# 3. 查 gadget traceecho1 > /sys/kernel/debug/tracing/events/gadget/enablecat/sys/kernel/debug/tracing/trace_pipe |head-20# usb_ep_queue: ep0in req ... len 0/64# usb_gadget_vbus_connect: ...# 沒有錯誤 <- Gadget 層沒問題# 4. 查 DWC3 link_statecat?/sys/kernel/debug/usb/23000000.usb/link_state# 輸出: On <- 鏈路正常# 5. 查 PC 端 USB 枚舉（換到 PC 端）lsusb -v -d 1d6b: ?# 查 RK3576 的 VID/PID# 設備描述符能讀到，但配置描述符失敗# 6. 查 Gadget 描述符配置cat?/sys/kernel/config/usb_gadget/rockchip/bcdUSBcat?/sys/kernel/config/usb_gadget/rockchip/bcdDevicecat?/sys/kernel/config/usb_gadget/rockchip/strings/0x409/serialnumber# 輸出: serialnumber 為空 <- 問題找到了

根因：Gadget的serialnumber字符串描述符沒配置。某些Windows驅(qū)動對serialnumber有嚴格要求，空串會導致枚舉異常。

修復：

mkdir-p/sys/kernel/config/usb_gadget/rockchip/strings/0x409echo"RK3576-001">/sys/kernel/config/usb_gadget/rockchip/strings/0x409/serialnumber# 重新綁定echo"">/sys/kernel/config/usb_gadget/rockchip/UDCecho"23000000.usb">/sys/kernel/config/usb_gadget/rockchip/UDC

案例三：Host模式U盤不識別

現(xiàn)象：DRD1口插U盤，dmesg沒有任何USB設備插入的日志。

排查：

# 1. 確認當前模式cat/sys/kernel/debug/usb/23400000.usb/mode# 輸出: host <- 模式正確# 2. 查 USB 設備樹cat?/sys/kernel/debug/usb/devices# 只有一個 Root Hub，沒有下游設備 <- U 盤沒枚舉# 3. 查 VBUS 供電ls?/sys/kernel/debug/regulator/ | grep hostcat?/sys/kernel/debug/regulator/vcc5v0_host/uevent# 正常: POWER_SUPPLY_ONLINE=1 <- 供電正常# 4. 查 xHCI 日志dmesg | grep xhci# xhci-hcd xhci-hcd.0.auto: xHCI Host Controller# 沒有端口相關(guān)的日志 <- 端口沒檢測到連接# 5. 查 USB2 PHY 狀態(tài)cat?/sys/firmware/devicetree/base/usb2-phy@1/otg-port/status# 輸出: disabled <- PHY 沒啟用！# 6. 查 Combphy 狀態(tài)（DRD1 的 USB3 PHY）cat?/sys/firmware/devicetree/base/phy@2b060000/status# 輸出: disabled <- USB3 PHY 也沒啟用

根因：DRD1的PHY在DTS中status = "disabled"。雖然DWC3本身是host模式，但PHY沒初始化，總線上的信號傳不到控制器。

修復：在board DTS中啟用PHY節(jié)點：

&u2phy1_otg {  phy-supply = <&vcc5v0_host>;  status ="okay";};&combphy1_psu {  status ="okay";};

案例四：USB3掉到USB2，SuperSpeed不工作

現(xiàn)象：U盤插DRD0，current_speed=high-speed，沒有SuperSpeed。

排查：

# 1. 查 link_statecat/sys/kernel/debug/usb/23000000.usb/link_state# 輸出: On <- 鏈路是通的# 2. 查 USBDP PHY 的 U3 端口狀態(tài)cat?/sys/firmware/devicetree/base/phy@2b010000/u3-port/status# 輸出: disabled <- USB3 PHY 端口沒啟用# 3. 查最大速度配置cat?/sys/firmware/devicetree/base/usb@23000000/maximum-speed# 輸出: high-speed <- DTS 里限制了最高速度

根因：DTS中maximum-speed = "high-speed"限制了DWC3只跑USB 2.0，或者USBDP PHY的u3-port沒啟用。

修復：DTS中去掉maximum-speed限制，并啟用usbdp_phy_u3。

案例五：USB Gadget數(shù)據(jù)傳輸中斷

現(xiàn)象：UVC Gadget工作一段時間后，PC端畫面卡住。

排查：

# 1. 查 UDC 狀態(tài)cat/sys/class/udc/23000000.usb/state# 輸出: configured <- 枚舉正常# 2. 查 link_statecat?/sys/kernel/debug/usb/23000000.usb/link_state# 輸出: Sleep <- USB 進入 suspend！# 3. 查 DWC3 traceecho?1 > /sys/kernel/debug/tracing/events/dwc3/enablecat/sys/kernel/debug/tracing/trace_pipe | grep -i"suspend|link"# dwc3_event: event (...): USB link state change -> Sleep

根因：USB總線空閑時自動suspend，但UVC應用沒有正確wake up。這通常是因為snps,dis-enblslpm_quirk沒有配置。

修復：DTS中添加snps,dis-enblslpm_quirk;禁用LPM（Link Power Management）。

十、排查決策樹

下次USB出問題，按這張圖走：

十一、命令速查表

目標	命令	正常輸出
DRD0模式	cat /sys/kernel/debug/usb/23000000.usb/mode	otg/host/device
DRD0鏈路狀態(tài)	cat /sys/kernel/debug/usb/23000000.usb/link_state	On/Sleep/Recovery
DRD0寄存器	cat /sys/kernel/debug/usb/23000000.usb/regdump | head	GSNPSID/GCTL/DCFG/DSTS值
DRD1模式	cat /sys/kernel/debug/usb/23400000.usb/mode	host
UDC狀態(tài)	cat /sys/class/udc/23000000.usb/state	configured
UDC速度	cat /sys/class/udc/23000000.usb/current_speed	high-speed/SuperSpeed
強制Host	echo host > /sys/kernel/debug/usb/23000000.usb/mode	切換成功
強制Device	echo device > /sys/kernel/debug/usb/23000000.usb/mode	切換成功
切換OTG	echo otg > /sys/kernel/debug/usb/23000000.usb/mode	切換成功
Gadget配置	ls /sys/kernel/config/usb_gadget/rockchip/	UDC/configs/functions
XHCI入口	ls /sys/kernel/debug/usb/xhci/	xhci-hcd.0.auto
USB設備樹	cat /sys/kernel/debug/usb/devices	T: Bus=01 Lev=00...
TCPM日志	cat /sys/kernel/debug/usb/tcpm-2-004e/log | tail	state change ...
DWC3 trace	echo 1 > /sys/kernel/debug/tracing/events/dwc3/enable	開啟trace
Gadget trace	echo 1 > /sys/kernel/debug/tracing/events/gadget/enable	開啟trace
XHCI trace	echo 1 > /sys/kernel/debug/tracing/events/xhci-hcd/enable	開啟trace

DWC3調(diào)試的精髓就一句話：先看mode，再看link_state，最后看trace。三步走完，問題基本能定位到寄存器級別。

審核編輯 黃宇