USB

The Universal Serial Bus (USB) is an industry standard that allows for data exchange and power supply between various types of electronic devices. It supports multiple operating speeds, such as 1.5 Mbps low speed, 12 Mbps full speed, 480 Mbps high speed, as well as 5 Gbps SuperSpeed and 10 Gbps SuperSpeed Plus.

RUBIK Pi 3 provides four USB ports:

2 x USB 3.0 Type-A, host mode only (No.7 in the following figure)
1 x USB 2.0 Type-A, host or device mode (No. 6 in the following figure)
1 x USB 3.1 Gen 1 Type-C, host or device mode (ADB), Type-C with DisplayPort v1.4 (No. 5 in the following figure)

note

The DP function is not supported in Ubuntu 24.04 V1.0.0. Support for this feature will be introduced in future versions.

Verify USB functions

USB camera

RUBIK Pi 3 device provides driver support for USB webcams that are compliant with the USB Video Class (UVC) standard. The uvcvideo driver in the Linux kernel supports these cameras. For more information on the uvcvideo driver, refer to https://www.kernel.org/doc/html/v4.19/media/v4l-drivers/uvcvideo.html.

The uvcvideo driver exposes these cameras as V4L2 video devices, which can be accessed through character device nodes (such as /dev/videoX).

In user space, applications can use the v4l2src GStreamer plugin to manage the USB cameras. The plugin is associated with the Qualcomm Intelligent Multimedia SDK (QIM SDK). Additionally, programs like Yavta (another V4L2 test application) can directly interact with the V4L2 (Video4Linux2) interface to test and control the camera devices.

Install Yavta

sudo apt install yavta

Prerequisite: Obtain the image format and size

To configure the USB camera using Yavta or GStreamer, perform the following steps.

To understand the enumeration details, connect the USB camera and run the following command.

lsusb

The output is as follows:

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

Before and after connecting the USB camera, run the following command in the RUBIK Pi 3 terminal. The difference between the two results can be used to identify the video node of the USB camera.

ls /dev/video*

Sample output:

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

As shown above, the video nodes for the USB camera are video2 and video3.

To use Yavta to view the supported output formats and sizes, run the following command:

yavta /dev/video2 --enum-formats

The output is as follows:

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

From the display results of step 3, select the desired image format and size.

Configure the USB camera using Yavta

Prerequisite: The USB camera's output format and size have been determined.

Run the following command to select the 1920x1080 output size and 30 fps MJPEG format, and capture 10 frames to /tmp/ with file names in the format testmjpeg-00000*.bin:

yavta -f MJPEG -s 1920x1080 -t 1/30 -c10 -F/tmp/testmjpeg /dev/video2

The output is as follows:

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.

Run the following command to select the 1280x720 output size, 15 fps YUV format, and capture 10 frames to /tmp/ with file names in the format testyuv-00000*.bin

yavta -f YUYV -s 1280x720 -t 1/15 -c10 -F/tmp/testyuv /dev/video2

The output is as follows:

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 debugging

This section provides the methods for obtaining debug logs. The debug methods include regdumps, debug ftraces, and configfs nodes. When debugging issues related to entering or exiting low-power modes, system memory management unit (SMMU), and unclocked accesses, you can check the event and controller status details through the logs obtained by using the above methods.

The following commands require the root privilege. To get the root privilege run the following command.

sudo su

In case if you want to exit from root privilege mode, simply type “exit” command.

USB 2.0 Type-A device path: /sys/devices/platform/soc@0/8c00000.usb/xhci-hcd.1.auto/usb3/
- USB 3.0 Type-A device path:
- /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 device path: /sys/devices/platform/soc@0/a600000.usb

USB tracing

Use debugfs to deeply trace each transaction over the USB line. To view the trace list, run the following command.

warning

Before running the command, ensure that debugfs has been mounted. If not mounted, run the following command to mount debugfs: sudo mount -t debugfs none /sys/kernel/debug

ls /sys/kernel/debug/tracing/events/dwc3

The following traces can be used to verify data transmission in the xHCI, gadget stack, or USB Type-C Connector System Software Interface (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

To list the traces in the xHCI/Host Controller Driver (HCD), run the following command:

ls /sys/kernel/debug/tracing/events/xhci-hcd

The following traces can be used to verify data transmission in the 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

To list the available events for the USB Video Class (UVC) gadget driver, run the following command:

ls /sys/kernel/debug/tracing/events/gadget

The output is as follows.

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

To list the available events in the UCSI driver, run the following command:

ls /sys/kernel/debug/tracing/events/ucsi

The output is as follows.

enable  ucsi_connector_change  ucsi_register_port  ucsi_run_command
filter  ucsi_register_altmode  ucsi_reset_ppm

USB regdump

The USB debugfs provides the following information (using the Type-C interface as an example).

Operating mode (Type-C interface)
```
cat /sys/kernel/debug/usb/a600000.usb/mode
```
note
Operating mode (USB 2.0 Type-A) - cat /sys/kernel/debug/usb/8c00000.usb/mode

Sample output:
```
device
```
State and transfer ring buffer (TRB) queues to all endpoints in device mode.

Current link status.

cat /sys/kernel/debug/usb/a600000.usb/link_state

Sample output:

Sleep

Display processor (LSP) dump

cat /sys/kernel/debug/usb/a600000.usb/lsp_dump

Sample output:

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

Sample output:

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

Run the regdump command to obtain the current status of the register space for the following registers:

Device mode registers, such as DCTL, DSTS, and DCFG
Global registers, such as GCTL and GSTS

cd /sys/kernel/debug/usb/a600000.usb
cat regdump

Sample output:

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

Host mode sysfs lookup

To view the bus detailed information, run the following command:

lsusb

Sample output:

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

To view the contents of the current directory, run the following commands:

cd /sys/bus/usb/devices/
ls

Sample output:

1-0:1.0  1-1  1-1:1.0  2-0:1.0  usb1  usb2

To view detailed information about USB devices, run the following command:

cat /sys/kernel/debug/usb/devices

Sample output:

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

Verify USB functions​

Prerequisite: Obtain the image format and size​

USB debugging​

USB tracing​

USB regdump​

Host mode sysfs lookup​

Verify USB functions

Prerequisite: Obtain the image format and size

USB debugging

USB tracing

USB regdump

Host mode sysfs lookup