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.
IQ9 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)
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
IQ9 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
``shell sudo apt install yavta `` ### Prerequisite: Obtain the image format and size
To configure the USB camera using Yavta or GStreamer, perform the following steps. 1. To understand the enumeration details, connect the USB camera and run the following command. ``shell 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 ``
2. Before and after connecting the USB camera, run the following command in the IQ9 terminal. The difference between the two results can be used to identify the video node of the USB camera. ``shell ls /dev/video ` Sample output: ` root@IQ9:/sys/bus/pci# ls /dev/video /dev/video0 /dev/video1 /dev/video32 /dev/video33 root@IQ9:/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*.
3. To use Yavta to view the supported output formats and sizes, run the following command: ``shell 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@IQ9:~$ 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 ``` 4. 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:
``shell 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
``shell 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. ```shell 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)
```shell
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:
```shell
device
```
* State and transfer ring buffer (TRB) queues to all endpoints in device mode.
* Current link status.
```shell
cat /sys/kernel/debug/usb/a600000.usb/link_state
```
Sample output:
```shell
Sleep
```
* Display processor (LSP) dump
```shell
cat /sys/kernel/debug/usb/a600000.usb/lsp_dump
```
Sample output:
```shell
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