USB
通用串行总线 (USB) 是一种行业标准,允许在各种类型的电子设备之间进行数据交换和供电。该标准支持多种运行速度,例如 1.5 Mbps 低速、12 Mbps 全速、480 Mbps 高速以及 5 Gbps 超高速和 10 Gbps 超高速 Plus。
魔方派 3 拥有 4 个 USB 口:
-
两个 USB 3.0 A 口,只能作为主机模式使用,如下图 7。
-
一个 USB 2.0 A 口,可以作为主机或设备模式使用,如下图 6。
-
一个 USB 3.1 Gen 1 C 口,可以作为主机或设备模式(常用于 ADB),以及 DP 显示使用,如下图 5。
在 Ubuntu 24.04 V1.0.0 版本中暂不支持 DP 功能。该功能支持将在未来的版本中提供。

USB 接口功能验证
- USB 摄像头
魔方派 3 设备为符合 USB 视频类(UVC)标准的 USB 网络摄像头提供驱动程序支持。Linux 内核的 uvcvideo 驱动程序支持摄像头。有关 uvcvideo 驱动程序的更多信息,请参阅 https://www.kernel.org/doc/html/v4.19/media/v4l-drivers/uvcvideo.html
uvcvideo 驱动程序将这类摄像头作为 V4L2 视频设备(可通过字符设备节点(如 /dev/videoX)进行访问)公开。
在用户空间中,应用程序可以使用 v4l2src GStreamer 插件管理 USB 摄像头,该插件与 Qualcomm 智能多媒体 SDK (QIM SDK) 捆绑在一起。此外,Yavta(另一个 V4L2 测试应用程序)等程序可以直接与 V4L2(Video4Linux2)接口交互,对摄像头设备进行测试和控制。
安装 Yavta
sudo apt install yavta
前提条件:获取图像格式大小
要通过 Yavta 或 GStreamer 配置 USB 摄像头,必须执行以下步骤。
- 要了解枚举详细信息,应连接 USB 摄像头并运行以下命令。
lsusb
随即显示以下输出。
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 1bcf:0215 Sunplus Innovation Technology Inc. 4K AutoFocus Webcam
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 002 Device 002: ID 0b95:1790 ASIX Electronics Corp. AX88179 Gigabit Ethernet
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
- USB 摄像头插入前后,在魔方派 3 的终端,执行如下命令,根据两次结果的差异可以确定 USB 摄像头视频节点。
ls /dev/video*
示例输出:
root@rubikpi:/sys/bus/pci# ls /dev/video*
/dev/video0 /dev/video1 /dev/video32 /dev/video33
root@rubikpi:/sys/bus/pci# ls /dev/video*
/dev/video0 /dev/video1 /dev/video2 /dev/video3 /dev/video32 /dev/video33
如上所示,USB 摄像头的节点为 video2 和 video3。
- 要使用 Yavta 查看支持的输出格式和大小,应运行以下命令:
yavta /dev/video2 --enum-formats
随即显示以下输出。
Device /dev/video3 opened.
Device `4K AutoFocus Webcam: 4K AutoFoc' on `usb-0000:01:00.0-1' (driver 'uvcvideo') supports meta-d.
- Available formats:
Format 0: UVCH (48435655)
Type: Meta-data capture (13)
Name: UVC Payload Header Metadata
Meta-data format: UVCH (48435655) buffer size 10240
ubuntu@rubikpi:~$ yavta /dev/video2 --enum-formats
Device /dev/video2 opened.
Device `4K AutoFocus Webcam: 4K AutoFoc' on `usb-0000:01:00.0-1' (driver 'uvcvideo') supports video,.
- Available formats:
Format 0: MJPEG (47504a4d)
Type: Video capture (1)
Name: Motion-JPEG
Frame size: 1920x1080 (1/30, 1/30)
Frame size: 1280x720 (1/30)
Frame size: 1600x900 (1/30)
Frame size: 2304x1296 (1/30)
Frame size: 2560x1440 (1/30)
Frame size: 2688x1512 (1/30)
Frame size: 3840x2160 (1/25)
Frame size: 640x360 (1/30)
Frame size: 800x450 (1/30)
Frame size: 848x480 (1/30)
Frame size: 960x540 (1/30)
Frame size: 1024x576 (1/30)
Frame size: 640x480 (1/30)
Frame size: 800x600 (1/30)
Frame size: 960x720 (1/30)
Frame size: 1024x768 (1/30)
Frame size: 1280x960 (1/30)
Frame size: 1600x1200 (1/30)
Frame size: 2048x1536 (1/30)
Frame size: 2592x1944 (1/30)
Frame size: 1920x1080 (1/30, 1/30)
Format 1: YUYV (56595559)
Type: Video capture (1)
Name: YUYV 4:2:2
Frame size: 1920x1080 (1/5, 1/5)
Frame size: 1280x720 (1/10)
Frame size: 1600x900 (1/5)
Frame size: 640x360 (1/30)
Frame size: 800x450 (1/20)
Frame size: 848x480 (1/20)
Frame size: 960x540 (1/20)
Frame size: 1024x576 (1/15)
Frame size: 640x480 (1/30)
Frame size: 800x600 (1/20)
Frame size: 960x720 (1/15)
Frame size: 1024x768 (1/10)
Frame size: 1280x960 (2/15)
Frame size: 1600x1200 (1/5)
Frame size: 1920x1080 (1/5, 1/5)
Video format: MJPEG (47504a4d) 1920x1080 (stride 0) field none buffer size 4147200
- 从第 3 步的显示结果中选择所需的图像格式和大小。
使用 Yavta 配置 USB 摄像头
前提条件:USB 摄像头输出格式和大小已确定。
请运行以下命令,以便选择 1920x1080 输出尺寸和 30 fps 的 MJPEG 格式,在 /tmp/ 下采集 10 帧,文件名为 testmjpeg-00000*.bin。
yavta -f MJPEG -s 1920x1080 -t 1/30 -c10 -F/tmp/testmjpeg /dev/video2
随即显示以下输出。
Device /dev/video2 opened.
Device `4K AutoFocus Webcam: 4K AutoFoc' on `usb-0000:01:00.0-1' (driver 'uvcvideo') supports video, capture, without mplanes.
Video format set: MJPEG (47504a4d) 1920x1080 (stride 0) field none buffer size 4147200
Video format: MJPEG (47504a4d) 1920x1080 (stride 0) field none buffer size 4147200
Current frame rate: 1/30
Setting frame rate to: 1/30
Frame rate set: 1/30
8 buffers requested.
length: 4147200 offset: 0 timestamp type/source: mono/SoE
Buffer 0/0 mapped at address 0xffffa5e5b000.
length: 4147200 offset: 32768 timestamp type/source: mono/SoE
Buffer 1/0 mapped at address 0xffffa5a66000.
length: 4147200 offset: 65536 timestamp type/source: mono/SoE
Buffer 2/0 mapped at address 0xffffa5671000.
length: 4147200 offset: 98304 timestamp type/source: mono/SoE
Buffer 3/0 mapped at address 0xffffa527c000.
length: 4147200 offset: 131072 timestamp type/source: mono/SoE
Buffer 4/0 mapped at address 0xffffa4e87000.
length: 4147200 offset: 163840 timestamp type/source: mono/SoE
Buffer 5/0 mapped at address 0xffffa4a92000.
length: 4147200 offset: 196608 timestamp type/source: mono/SoE
Buffer 6/0 mapped at address 0xffffa469d000.
length: 4147200 offset: 229376 timestamp type/source: mono/SoE
Buffer 7/0 mapped at address 0xffffa42a8000.
0 (0) [-] none 0 115283 B 53.095060 53.647782 244.260 fps ts mono/SoE
1 (1) [-] none 1 115277 B 53.647091 53.679768 1.811 fps ts mono/SoE
2 (2) [-] none 2 115376 B 53.683085 53.715810 27.782 fps ts mono/SoE
3 (3) [-] none 3 115545 B 53.715105 53.747738 31.230 fps ts mono/SoE
4 (4) [-] none 4 117998 B 53.747096 53.783769 31.259 fps ts mono/SoE
5 (5) [-] none 5 117962 B 53.783089 53.815715 27.783 fps ts mono/SoE
6 (6) [-] none 6 118127 B 53.815088 53.847740 31.251 fps ts mono/SoE
7 (7) [-] none 7 118027 B 53.847099 53.883764 31.239 fps ts mono/SoE
8 (0) [-] none 8 119080 B 53.883084 53.915721 27.789 fps ts mono/SoE
9 (1) [-] none 9 119399 B 53.915093 53.947736 31.241 fps ts mono/SoE
Captured 10 frames in 0.856770 seconds (11.671741 fps, 1368014.420968 B/s).
8 buffers released.
请运行以下命令,以便选择 1280x720 输出尺寸、15 fps 的 YUV 格式,在 /tmp/ 下采集 10 帧,生成的文件名为 testyuv-00000*.bin。
yavta -f YUYV -s 1280x720 -t 1/15 -c10 -F/tmp/testyuv /dev/video2
随即显示以下输出。
Device /dev/video2 opened.
Device `4K AutoFocus Webcam: 4K AutoFoc' on `usb-0000:01:00.0-1' (driver 'uvcvideo') supports video,.
Video format set: YUYV (56595559) 1280x720 (stride 2560) field none buffer size 1843200
Video format: YUYV (56595559) 1280x720 (stride 2560) field none buffer size 1843200
Current frame rate: 1/10
Setting frame rate to: 1/15
Frame rate set: 1/10
8 buffers requested.
length: 1843200 offset: 0 timestamp type/source: mono/SoE
Buffer 0/0 mapped at address 0xffff966ce000.
length: 1843200 offset: 32768 timestamp type/source: mono/SoE
Buffer 1/0 mapped at address 0xffff9650c000.
length: 1843200 offset: 65536 timestamp type/source: mono/SoE
Buffer 2/0 mapped at address 0xffff9634a000.
length: 1843200 offset: 98304 timestamp type/source: mono/SoE
Buffer 3/0 mapped at address 0xffff96188000.
length: 1843200 offset: 131072 timestamp type/source: mono/SoE
Buffer 4/0 mapped at address 0xffff95fc6000.
length: 1843200 offset: 163840 timestamp type/source: mono/SoE
Buffer 5/0 mapped at address 0xffff95e04000.
length: 1843200 offset: 196608 timestamp type/source: mono/SoE
Buffer 6/0 mapped at address 0xffff95c42000.
length: 1843200 offset: 229376 timestamp type/source: mono/SoE
Buffer 7/0 mapped at address 0xffff95a80000.
0 (0) [-] none 0 1843200 B 364.737849 364.966754 2.174 fps ts mono/SoE
1 (1) [-] none 1 1843200 B 364.966042 365.066785 4.382 fps ts mono/SoE
2 (2) [-] none 2 1843200 B 365.066087 365.166812 9.996 fps ts mono/SoE
3 (3) [-] none 3 1843200 B 365.166149 365.266862 9.994 fps ts mono/SoE
4 (4) [-] none 4 1843200 B 365.266205 365.366929 9.994 fps ts mono/SoE
5 (5) [-] none 5 1843200 B 365.366266 365.466985 9.994 fps ts mono/SoE
6 (6) [-] none 6 1843200 B 365.466326 365.567108 9.994 fps ts mono/SoE
7 (7) [-] none 7 1843200 B 365.566381 365.667099 9.995 fps ts mono/SoE
8 (0) [-] none 8 1843200 B 365.666440 365.767150 9.994 fps ts mono/SoE
9 (1) [-] none 9 1843200 B 365.766496 365.867212 9.994 fps ts mono/SoE
Captured 10 frames in 1.589346 seconds (6.291895 fps, 11597220.863435 B/s).
8 buffers released.
USB 调试
本节提供有关获取调试日志的各种方法的信息。调试方式有 regdumps 、调试 ftraces 、 configfs 节点等。在调试与进入/退出低功耗模式、SMMU 故障、无时钟访问相关的问题时,可通过上述日志查看事件和控制器状态的详细信息。
以下命令需要 root 权限。 执行以下命令来获取 root 权限:
sudo su
如需退出 root 权限模式,只需输入exit 命令。
-
USB 2.0 Type-A 设备路径: /sys/devices/platform/soc@0/8c00000.usb/xhci-hcd.1.auto/usb3/
-
USB 3.0 Type-A 设备路径:
-
/sys/devices/platform/soc@0/1c00000.pci/pci0000:00/0000:00:00.0/0000:01:00.0/usb1
-
/sys/devices/platform/soc@0/1c00000.pci/pci0000:00/0000:00:00.0/0000:01:00.0/usb2
-
-
USB 3.1 Type-C 设备路径:/sys/devices/platform/soc@0/a600000.usb
USB 跟踪
使用 debugfs 跟踪可以更加深入地了解 USB 线上发生的每一个事务。如需查看跟踪列表,可运行以下命令。
执行命令前,确保已挂载
debugfs。如果尚未挂载,可运行以下命令:
sudo mount -t debugfs none /sys/kernel/debug
ls /sys/kernel/debug/tracing/events/dwc3
以下是可用于验证 xHCI/gadget 协议栈/USB Type-C 连接器系统软件接口 (UCSI) 中的数据传输的跟踪。
dwc3_alloc_request dwc3_event dwc3_gadget_generic_cmd enable
dwc3_complete_trb dwc3_free_request dwc3_gadget_giveback filter
dwc3_ctrl_req dwc3_gadget_ep_cmd dwc3_prepare_trb
dwc3_ep_dequeue dwc3_gadget_ep_disable dwc3_readl
dwc3_ep_queue dwc3_gadget_ep_enable dwc3_writel
要列出 xHCI/主机控制器驱动程序 (HCD) 中的跟踪数据,请运行以下命令。
ls /sys/kernel/debug/tracing/events/xhci-hcd
以下是可用于验证 xHCI/HCD 中数据传输的跟踪。
enable xhci_handle_cmd_config_ep
filter xhci_handle_cmd_disable_slot
xhci_add_endpoint xhci_handle_cmd_reset_dev
xhci_address_ctrl_ctx xhci_handle_cmd_reset_ep
xhci_address_ctx xhci_handle_cmd_set_deq
xhci_alloc_dev xhci_handle_cmd_set_deq_ep
xhci_alloc_virt_device xhci_handle_cmd_stop_ep
xhci_configure_endpoint xhci_handle_command
xhci_configure_endpoint_ctrl_ctx xhci_handle_event
xhci_dbc_alloc_request xhci_handle_port_status
xhci_dbc_free_request xhci_handle_transfer
xhci_dbc_gadget_ep_queue xhci_hub_status_data
xhci_dbc_giveback_request xhci_inc_deq
xhci_dbc_handle_event xhci_inc_enq
xhci_dbc_handle_transfer xhci_queue_trb
xhci_dbc_queue_request xhci_ring_alloc
xhci_dbg_address xhci_ring_ep_doorbell
xhci_dbg_cancel_urb xhci_ring_expansion
xhci_dbg_context_change xhci_ring_free
xhci_dbg_init xhci_ring_host_doorbell
xhci_dbg_quirks xhci_setup_addressable_virt_device
xhci_dbg_reset_ep xhci_setup_device
xhci_dbg_ring_expansion xhci_setup_device_slot
xhci_discover_or_reset_device xhci_stop_device
xhci_free_dev xhci_urb_dequeue
xhci_free_virt_device xhci_urb_enqueue
xhci_get_port_status xhci_urb_giveback
xhci_handle_cmd_addr_dev
请运行以下命令,以便列出 USB 视频类 (UVC) gadget 驱动程序的可用事件。
ls /sys/kernel/debug/tracing/events/gadget
随即显示以下输出。
enable usb_gadget_activate
filter usb_gadget_clear_selfpowered
usb_ep_alloc_request usb_gadget_connect
usb_ep_clear_halt usb_gadget_deactivate
usb_ep_dequeue usb_gadget_disconnect
usb_ep_disable usb_gadget_frame_number
usb_ep_enable usb_gadget_giveback_request
usb_ep_fifo_flush usb_gadget_set_remote_wakeup
usb_ep_fifo_status usb_gadget_set_selfpowered
usb_ep_free_request usb_gadget_vbus_connect
usb_ep_queue usb_gadget_vbus_disconnect
usb_ep_set_halt usb_gadget_vbus_draw
usb_ep_set_maxpacket_limit usb_gadget_wakeup
usb_ep_set_wedge
如需列出 UCSI 驱动程序中的可用事件,可运行以下命令。
ls /sys/kernel/debug/tracing/events/ucsi
随即显示以下输出。
enable ucsi_connector_change ucsi_register_port ucsi_run_command
filter ucsi_register_altmode ucsi_reset_ppm
USB 寄存器打印
USB debugfs 提供以下信息,下面以 Type-C 接口为例。
-
工作模式(Type-C 接口)
cat /sys/kernel/debug/usb/a600000.usb/mode备注USB 2.0 Type-A 的工作模式
cat /sys/kernel/debug/usb/8c00000.usb/mode示例输出:
device -
设备模式下所有端点的状态和传输环形缓冲区 (TRB) 队列。
-
当前链路状态。
cat /sys/kernel/debug/usb/a600000.usb/link_state示例输出
Sleep -
列出处理器 (LSP) dump。
cat /sys/kernel/debug/usb/a600000.usb/lsp_dump示例输出:
GDBGLSP[0] = 0x40000000
GDBGLSP[1] = 0x00003a80
GDBGLSP[2] = 0x38200000
GDBGLSP[3] = 0x00802000
GDBGLSP[4] = 0x126f1000
GDBGLSP[5] = 0x3a800018
GDBGLSP[6] = 0x00000a80
GDBGLSP[7] = 0xfc03f14a
GDBGLSP[8] = 0x0b803fff
GDBGLSP[9] = 0x00000000
GDBGLSP[10] = 0x000000f8
GDBGLSP[11] = 0x000000f8
GDBGLSP[12] = 0x000000f8
GDBGLSP[13] = 0x000000f8
GDBGLSP[14] = 0x000000f8
GDBGLSP[15] = 0x000000f8
ls /sys/kernel/debug/usb/a600000.usb
示例输出:
ep0in ep11out ep14in ep1out ep4in ep6out ep9in regdump
ep0out ep12in ep14out ep2in ep4out ep7in ep9out testmode
ep10in ep12out ep15in ep2out ep5in ep7out link_state
ep10out ep13in ep15out ep3in ep5out ep8in lsp_dump
ep11in ep13out ep1in ep3out ep6in ep8out mode
regdump 命令提供以下寄存器的寄存器空间的当前状态:
-
设备模式的寄存器,例如 DCTL、DSTS 和 DCFG
-
全局寄存器,例如 GCTL 和 GSTS
cd /sys/kernel/debug/usb/a600000.usb
cat regdump
示例输出:
GSBUSCFG0 = 0x2222000e
GSBUSCFG1 = 0x00001700
GTXTHRCFG = 0x00000000
GRXTHRCFG = 0x00000000
GCTL = 0x00102000
GEVTEN = 0x00000000
GSTS = 0x7e800000
GUCTL1 = 0x810c1802
GSNPSID = 0x5533330a
GGPIO = 0x00000000
GUID = 0x00060500
GUCTL = 0x0d00c010
GBUSERRADDR0 = 0x00000000
GBUSERRADDR1 = 0x00000000
GPRTBIMAP0 = 0x00000000
GPRTBIMAP1 = 0x00000000
GHWPARAMS0 = 0x4020400a
GDBGFIFOSPACE = 0x00420000
GDBGLTSSM = 0x41090658
GDBGBMU = 0x20300000
GPRTBIMAP_HS0 = 0x00000000
GPRTBIMAP_HS1 = 0x00000000
GPRTBIMAP_FS0 = 0x00000000
GPRTBIMAP_FS1 = 0x00000000
GUCTL2 = 0x0198440d
VER_NUMBER = 0x00000000
VER_TYPE = 0x00000000
GUSB2PHYCFG(0) = 0x00002400
GUSB2I2CCTL(0) = 0x00000000
GUSB2PHYACC(0) = 0x00000000
GUSB3PIPECTL(0) = 0x030e0002
GTXFIFOSIZ(0) = 0x00000042
GRXFIFOSIZ(0) = 0x00000305
GEVNTADRLO(0) = 0xfffff000
GEVNTADRHI(0) = 0x0000000f
GEVNTSIZ(0) = 0x00001000
GEVNTCOUNT(0) = 0x00000000
GHWPARAMS8 = 0x000007ea
GUCTL3 = 0x00010000
GFLADJ = 0x8c80c8a0
DCFG = 0x00cc08b4
DCTL = 0x8cf00a00
DEVTEN = 0x00000257
DSTS = 0x008a5200
DGCMDPAR = 0x00000000
DGCMD = 0x00000000
DALEPENA = 0x0000000f
DEPCMDPAR2(0) = 0x00000000
DEPCMDPAR1(0) = 0xffffe000
DEPCMDPAR0(0) = 0x0000000f
DEPCMD(0) = 0x00000006
OCFG = 0x00000000
OCTL = 0x00000000
OEVT = 0x00000000
OEVTEN = 0x00000000
OSTS = 0x00000000
主机 sysfs 查询
要查看总线详细信息,请运行以下命令。
lsusb
示例输出:
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 03f0:134a HP, Inc Optical Mouse
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
请运行以下命令,以便列出当前目录的内容。
cd /sys/bus/usb/devices/
ls
示例输出:
1-0:1.0 1-1 1-1:1.0 2-0:1.0 usb1 usb2
要查看有关 USB 设备的详细信息,请运行以下命令。
cat /sys/kernel/debug/usb/devices
示例输出:
T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=480 MxCh= 1
B: Alloc= 0/800 us ( 0%), #Int= 0, #Iso= 0
D: Ver= 2.00 Cls=09(hub ) Sub=00 Prot=01 MxPS=64 #Cfgs= 1
P: Vendor=1d6b ProdID=0002 Rev= 6.05
S: Manufacturer=Linux 6.5.0-rc4 xhci-hcd
S: Product=xHCI Host Controller
S: SerialNumber=xhci-hcd.0.auto
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr= 0mA
I:* If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 4 Ivl=256ms
T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=1.5 MxCh= 0
D: Ver= 2.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=03f0 ProdID=134a Rev= 1.00
S: Manufacturer=PixArt
S: Product=HP USB Optical Mouse
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
I:* If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=usbhid
E: Ad=81(I) Atr=03(Int.) MxPS= 4 Ivl=10ms
T: Bus=02 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=5000 MxCh= 1
B: Alloc= 0/800 us ( 0%), #Int= 0, #Iso= 0
D: Ver= 3.00 Cls=09(hub ) Sub=00 Prot=03 MxPS= 9 #Cfgs= 1
P: Vendor=1d6b ProdID=0003 Rev= 6.05
S: Manufacturer=Linux 6.5.0-rc4 xhci-hcd
S: Product=xHCI Host Controller
S: SerialNumber=xhci-hcd.0.auto
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr= 0mA
I:* If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 4 Ivl=256ms