USB - Qualcomm Dragonwing Documentation

Universal serial bus (USB) is an industry standard that allows data exchange and delivery of power between various types of electronics. It can run at different speeds such as low speed at 1.5 Mbps, full speed at 12 Mbps, high speed at 480 Mbps, SuperSpeed at 5 Gbps, and SuperSpeed Plus at 10 Gbps. Synopsys DesignWare® Core SuperSpeed USB 3.x powers the USB on the Qualcomm SoC and is connected to two PHYs, USB2 PHY through UTMI and USB3 PHY through PIPE interfaces. These PHYs are wired to the physical Type-C port and facilitate communication to the external world. The following are the key hardware components of the USB.

USB controllers
- The primary controller is a Synopsys DesignWare Core SuperSpeed USB 3.x controller (Gen1/Gen2).
  - Two instances of Qualcomm multipurpose PHY (QMP) for USB SuperSpeed and DisplayPort.
  - Synopsys PHY for high-speed USB.
- The secondary controller is a Synopsys DesignWare Core high-speed USB 2.0 controller.
  - Synopsys PHY for high-speed USB
- The tertiary controller is a Synopsys DesignWare Core high-speed USB 2.0 controller.
  - Synopsys PHY for high-speed USB.
- Dragonwing IQ-9075 has three USB controllers (primary USB 3.2, secondary USB 3.2, tertiary USB 2.0)
Synopsys DesignWare core SuperSpeed USB 3.x controller features
- Synopsys DesignWare Core SuperSpeed USB 3.x controller is a USB SuperSpeed-compliant controller, which can be configured in one of the following ways:
  - Peripheral-only configuration
  - Host-only configuration
  - Dual-role configuration
- Supports all transfer types (control, bulk, interrupt, and isochronous)
- Supports SuperSpeed bulk streams
- Compliant with the eXtensible host controller interface (xHCI) specification
- Host mode supports SuperSpeed (5 Gbps), high-speed (480 Mbps), full-speed (12 Mbps), and low-speed (1.5 Mbps) operations.
- Device mode supports SuperSpeed (5 Gbps), high-speed (480 Mbps), and full-speed (12 Mbps) operations, and up to 16 bidirectional endpoints (including the control pipe ep0).
- Link power management
USB PHY access method
- Register-level interface through AHB2PHY for performing PHY-related operations.
USB Type-C
- Supports USB Type-C and power delivery using the PM7325B PD controller.
- Fully compliant with the USB Type-C 3.0 power delivery specifications.
- Supports the PM7325B software driver updates according to the UCSI framework after the delivery controller determines the Type‑C orientation, role, and mode of the connected link partner.
- Used only for the primary USB controller.

Clocks

The following tables list the clocks and operating frequencies required for the USB controller, and the high speed and SuperSpeed PHYs to function. Table : USB controller clocks

Clock name	Operating frequency	Description
`gcc_usb30_prim_master_clk “core_clk”`	200 MHz SuperSpeed 66 MHz high speed	Asynchronous to the bus clock; clock rates defined within the device tree node
`gcc_cfg_noc_usb3_prim_axi_clk “iface_clk”`	200 MHz SuperSpeed 66 MHz high speed	Auxiliary bus controller unit clock.
`gcc_aggre_usb3_prim_axi_clk “bus_aggr_clk”`	200 MHz SuperSpeed 66 MHz high speed	Clock that feeds into the `aggregator2` module, which controls data flow from the USB AXI to the NoC
`gcc_usb30_prim_mock_utmi_clk “utmi_clk”`	19.2 MHz	The internal controller `ref_clk` used for generating the ITP counter when the USB transceiver macrocell interface (UTMI)/UTMI+ Low Pin interface (ULPI) is suspended
`gcc_usb30_prim_sleep_clk “sleep_clk”`	32 kHz	Sleep clock
`gcc_usb3_sec_clkref_clk_en “xo”`	19.2 MHz	External reference clock source to the HS-PHY (PMIC)
`rpmh_cxo_clk “ref_clk_src”`	19.2 MHz	Reference clock source to the HS-PHY
`gcc_usb_phy_cfg_ahb2phy_clk “cfg_ahb_clk”`	100 MHz	Clock required for the AHB2PHY block (frequency based off PNoC frequency).

Table : High-speed PHY clocks

Clock name	Operating Frequency	Description
`rpmh_cxo_clk “ref_clk_src”`	19.2 MHz	Reference clock source to the HS-PHY
`gcc_usb_phy_cfg_ahb2phy_clk “cfg_ahb_clk”`	100 MHz	Clock required for the AHB2PHY block (frequency based off PNoC frequency)

Table : SuperSpeed PHY clocks

Clock name	Operating Frequency	Description
`gcc_usb3_prim_phy_aux_clk "aux_clk”`	19.2 MHz	PHY interface to PCI express (PIPE) auxiliary clock for power states
`gcc_usb3_prim_phy_pipe_clk “pipe_clk”`	125 MHz	Input source for the PIPE, which allows for data transfers between PHY and controller
`rpmh_cxo_clk "ref_clk_src"`	19.2 MHz	Parent clock for `ref_clk`
`gcc_usb3_prim_clkref_clk "ref_clk"`	19.2 MHz	Reference clock source to the SS-PHY
`gcc_usb3_prim_phy_com_aux_clk "com_aux_clk"`	19.2 MHz	–

Voltage rails

The following table lists the required voltage rails for the HighSpeed and SuperSpeed PHYs. Table : USB voltage rails

Voltage rails	Voltage levels (MAX/NOM/MIN)	Device mode
VREG L1C	1.8	1.7	Primary and secondary HS-PHY	1.8 V regulator used by both HS-PHYs in the system
VREG L2B	3.3	3.05	Primary and secondary HS-PHY	3.3 V regulator used by both HS-PHYs in the system
VREG L1B	0.912	0.912	SS-PHY	SS-PHY VDD core
VREG L10C	0.880	0.880	Primary and secondary HS‑PHY, and SS‑PHY	HS-PHY/SS‑PHY VDD core

Dragonwing IQ-9075 USB voltage rails

HS PHY: L7A (0.88 V), L6C (1.8 V), L9A (3.3 V)
SS PHY: L1C, L7A

Interrupts

The following table lists the various interrupts used by the USB controller to notify events. Table : USB controller interrupts

Interrupt name	QCS6490 /QCS5430 interrupts	Dragonwing IQ-9075 interrupts	Dragonwing IQ-8275 interrupts	Dragonwing IQ-615 interrupts	Interrupt events PDC wake-up kernel handling	Description
`dp_hs_phy_irq`	14	PDC14	PDC8	PDC10	PDC14	PDC10	9	10	D+ changes	–	Only used when the system is in VDD min/XO shutdown
`dm_hs_phy_irq`	15	PDC15	PDC7	PDC9	PDC15	PDC9	8	11	D-changes	–	Only used when the system is in VDD min/XO shutdown
`ss_phy_irq`	17	PDC12	PDC13	–	PDC12	–	6	–	LFPS detection	–	Only used when the system is in VDD min/XO shutdown
`pwr_event_irq`	130	287	352	444	131	444	130	663	–	USB PHY power state changes Exit/enter P3/L2	Used as the main controller wake-up handle when the system isn’t in power collapse
`core irq`	133	292	349	442	292	442	133	664	–	Bus events Suspend Resume Reset Controller event completion Transfer completion Command completion	Main USB interrupt that handles all USB controller events

Interconnect

The following table lists the various interconnects used by the USB controller. Table : USB interconnects

Interconnect name	Controller	Target	Interconnect path bandwidths in MBps
USB-DDR	`MASTER_USB3_0` Dragonwing IQ-9075 `MASTER_USB3_1` `MASTER_USB2` Dragonwing IQ-8275, Dragonwing IQ-615 `MASTER_USB2`	`SLAVE_EBI1`	USB_MEMORY_AVG_HS_BW MBps_to_icc(240) USB_MEMORY_PEAK_HS_BW MBps_to_icc(700) USB_MEMORY_AVG_SS_BW MBps_to_icc(1000) USB_MEMORY_PEAK_SS_BW MBps_to_icc(2500)
APPS-USB	`MASTER_APPSS_PROC`	`SLAVE_USB3_0` Dragonwing IQ-9075 `SLAVE_USB3_1` `SLAVE_USB2` Dragonwing IQ-8275, Dragonwing IQ-615 `SLAVE_USB2`	APPS_USB_AVG_BW 0 APPS_USB_PEAK_BW MBps_to_icc(40)

USB controller reset using clock control

The following table lists the reset methods used for the USB controller and PHY. Table : USB clock reset methods

Clock name	Reset control	Description
`GCC_USB3_DP_PHY_PRIM_BCR "global_phy_reset"`	SS-PHY	Resets the SS-PHY control and status registers
`GCC_USB3_PHY_PRIM_BCR "phy_reset"`	SS-PHY	Resets the SS-PHY
`GCC_QUSB2PHY_PRIM_BCR "phy_reset"`	HS-PHY	Resets the HS-PHY
`GCC_USB30_PRIM_BCR "core_reset"`	USB controller	Clock controller output to reset the USB controller

USB controller software reset using register

The following table lists the register options to reset the USB controller. Table : USB controller resets

USB controller register	USB register bit field	Reset control	Description
DWC3_DCTL	CSFTRST [Bit 30]	USB controller	Resets the USB controller device stack.
DWC3_GCTL	CORESOFTRESET [Bit 11]	-	Global reset for the DWC3 controller

Dragonwing IQ-9075 controller reset registers

HS: GCC_USB2_PHY_PRIM_BCR
SS: GCC_USB3_PHY_PRIM_BCR/ GCC_USB3PHY_PHY_PRIM_BCR
GCC_USB3_PHY_TERT_BCR
USB30_PRIM_GDSC
USB30_SEC_GDSC
USB20_PRIM_GDSC

Dragonwing IQ-615 secondary USB controller reset registers

GCC_USB20_SEC_BCR
GCC_QUSB2PHY_SEC_BCR
GCC_USB2_PHY_SEC_BCR

USB controller and SoC integration

The intellectual property and PHYs of the USB controller are integrated into the SoC as shown in the following figure. Figure : USB controller PHYs and SoC integrationUSB 3.xcontrollerSoCType-C connectorAHB 2PHYDisplay port controllerSS0_1DPPHY (QMP)SS0_0DPPHY (QMP)EUDHS0PHY(SNPS)PipeUTMISSHS The Synopsys DesignWare Core SuperSpeed USB 3.0 intellectual property controls only the core functionality and not the device specifications, such as clocks, interconnects, regulators, and GDSCs. The Synopsys DesignWare Core intellectual property is embedded inside a Qscratch wrapper (intellectual property and software driver), which takes up the responsibility of managing the required resources (clocks, interconnects, interrupts, GDSC, and regulators) during the probe, suspends, or resume state. Both these drivers coexist to ensure the USB functionality. For information about the USB Qscratch wrapper driver, see https://github.com/torvalds/linux/blob/master/drivers/usb/dwc3/dwc3-qcom.c. For information about the controller core driver, see https://github.com/torvalds/linux/blob/master/drivers/usb/dwc3/core.c.

xHCI support

The xHCI specification describes the register-level host controller interface for USB 2.0 and later. The USB controller is compliant with xHCI specifications, and in host mode it supports SuperSpeed (5 Gbps), high-speed (480 Mbps), full-speed (12 Mbps), and low-speed (1.5 Mbps) operations. Linux standard xHCI drivers are used to operate the USB controller in host mode.

USB Type-C connector system software interface (UCSI)

NoteDragonwing IQ-9075 and Dragonwing IQ-8275 don’t support USB Type-C feature.

The USB Type-C connector system software interface is available in the Linux kernel as a library. It defines a set of registers and data structures, which are used to interface with the USB Type-C connectors on a system. The USB Type-C connectors on the platform are referred to as the platform policy manager (PPM) and the system software component is referred to as the OS policy manager (OPM).
Qualcomm reference design uses the UCSI Glink driver to handle the communication between the OPM on the application processor and the PPM, which is the charger firmware running on the remote subsystem (aDSP) using PMIC GLINK.
The USB Type-C DisplayPort alternate mode adds the capabilities of supporting additional cable details, such as DPAM version and signaling of cable. The Qualcomm reference design supports DisplayPort using Type-C and concurrent support of USB SuperSpeed and DisplayPort with a maximum of two lanes for DisplayPort (two lanes for USB SuperSpeed and two lanes for DisplayPort).
The USB Type-C power delivery is supported by the PM7325B PD controller, fully compliant with the USB PD 3.0 specification. Using the UCSI interface, USB data-role swap and power-role swap are supported. NoteDragonwing IQ-9075 and Dragonwing IQ-8275 don’t support data and power role swapping through Type-C connectors.
Following are the references of the drivers involved:

USB features

Qualcomm chip hardware SoCs allow working in the dual-role device (DRD) mode. DRD enables both device and host roles. The device dynamically detects the role to move to and programs the controller accordingly. The autosuspend capability is supported to shut down the USB controller when the cable is removed. Function interfaces, such as video, audio, tethering, file transfer, media transfer, and charging are supported. Table : USB features: Linux

Feature	Description
USB_DWC3 controller	Synopsys DesignWare Core is supported by default in the Linux kernel.
USB_DWC3_QCOM	`Qscratch` wrapper using the Synopsys DesignWare Core for the USB functionality.
Runtime power management (RPM)	Linux supports RPM with the software driver file `dwc3-qcom`, for low-power mode operations.
Low-power mode (LPM)	LPM provides power-saving options from both HS/SS-PHY as well as the controller.
DRD	Dual-role device detection allows USB to work in both host and device mode.

Runtime power management

The Runtime power management feature can be enabled according to the your requirements. LPM support is added as part of https://lore.kernel.org/all/20231017131851.8299-1-quic_kriskura@quicinc.com/. NoteDragonwing IQ-9075 and Dragonwing IQ-8275 don’t support runtime power management for USB Type-A ports. By default, USB-suspend and resume in runtime are disabled. To enable these features, run the following command:

echo auto > /sys/bus/platform/devices/a600000.usb/power/control

The default autosuspend delay is set to 5 s. To change the delay, run the following sysfs command:

echo 2000 > /sys/bus/platform/devices/a600000.usb/power/autosuspend_delay_ms

During a role switch, the DWC3 controller enters the suspend state, toggles GDSC, and resets the controller to ensure successful host mode peripheral enumeration. While in host mode, for remote wake-up to work, wake-up, and autosuspend are enabled for the xHCI interface, USB root hubs, and the connected peripherals according to your requirements.

echo enabled > /sys/bus/platform/devices/xhci-hcd.X.auto/power/wakeup
cd /sys/bus/usb/devices/
echo enabled > usb1/power/wakeup
echo enabled > usb2/power/wakeup

NoteThe host controller driver (HCD) device generates the xhci-hcd.X.auto value, where X = 0, 1, 2. It indicates the number of devices connected to the USB. The connected devices are listed at /sys/bus/platform/devices/xhci-hcd.X.auto/usb1/<node number>. The<node number> value depends on the number of devices connected to the USB port. To enable the remote wake up for an LS optical mouse, run the following commands:

cd /sys/bus/usb/devices/usb1/1-1/
echo auto > power/control
echo enabled > power/wakeup

To check the runtime status, run the following command:

cat /sys/bus/platform/devices/a600000.usb/power/runtime_status

To avoid suspending in the composition switch, remove the active UDC to rebind the composition by running the following command:

echo on > /sys/bus/platform/devices/a600000.usb/power/control
echo auto > /sys/bus/platform/devices/a600000.usb/power/control

Software features

The following USB features are supported in software. Table : USB software features

Feature	Description
Peripheral ADB	ADB functionality is integrated over functionFS (FFS)
Peripheral mass storage	Generic Mass_storage functionality
Peripheral diag	Diag functionality is integrated over FFS
Peripheral RNDIS	Standard RNDIS protocol according to Linux kernel
Peripheral network control modem (NCM)	Standard NCM protocol according to Linux kernel
Host USB 3.0 driver (xHCI)	Both USB controllers support the xHCI architecture
Host high-speed USB	High-speed USB detection in host mode
Host HID/MS/hub driver	Class driver detection in host mode
Host video driver	UVC verified on limited webcam models
Host link power management	USB host mode LPM implementation
Peripheral USB link power management	USB device mode LPM implementation
DRD	Dual-role device support is possible (host/device mode support)
USB Type-C	Supported by PM7325B; supports current charging, CC logic, and SuperSpeed USB switch selection, all performed in the embedded controller
USB Type-C display port	Supports SuperSpeed USB + DisplayPort operating concurrently (2 DisplayPort lanes)
USB PD 2.0/3.0 charging	PD support depends on the PM7325B solution used. Fully compliant with PD 3.0
USB 3.1 Gen1	The USB controller supports USB 3.x Gen1 (5 Gbps).

USB architecture

The Qualcomm USB software architecture is loosely made up of two components, one is based on pure upstream, and the other is a sandbox where some of the pending feature-related changes are present. The pure upstream is directly picked from the latest stable kernel long-term support (LTS) 6.6.2. The architecture uses a Yocto (release 4.0) recipe for creating the binaries. Figure : USB software architecture/dev/ffs-xxx//dev/ffs-xxx//dev/ffs-xxx//sys/kernel/config/usb_gadget/…/sys/bus/usb/…Function driverFunction driverGadget frameworkconfigfs, UDC coreDevice controller driverClassdriverClassdriverUSB coreHost controller driverdwc3-qcomDWC3 core driversFemto phy driverQMP phy driverUCSIPMIC GLINKPM7325BaDSP corecharger firmwareVBUS, CC, D+,D-HSSS/sys/class/typec/port0/…Dual-role class driverType-C role swapdiag-routerport-bridgeadbd.serviceUSB peripheral mode configurationRuntime power management controlUser-space servicesVFSKernel-spaceType-C connector The sandbox is implemented with the following Qualcomm-specific features.

USB_DWC3_QCOM: The primary glue driver is responsible for the USB functionality on both host and device modes, depending on what’s connected. The device tree entry for the glue driver consists of resources, such as clocks, power rails, and interrupts. This feature uses the DWC3 core driver as a library, which controls the actual functionality of the DWC3 controller. For more details, see https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/dwc3/dwc3-qcom.c?h=v6.6.2.
Synopsys femto PHY: Qualcomm Synopsys femto PHY is the high-speed USB PHY responsible for controlling D+/D- lines, and facilitates data transfers along with charger detection. For more details, see https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/phy/qualcomm/phy-qcom-snps-femto-v2.c?h=v6.6.2.
QMP DisplayPort combo PHY: Qualcomm multipurpose PHY (QMP) display port combo PHY is designed for generic usage. A sample use case for USB would be the SuperSpeed and SuperSpeed-plus functionality as part of which the Rx+/Rx- and Tx+/Tx- can be used for data transfer. The PHY supports the display alternate mode when the display can claim a pair of lanes for the mirroring functionality while USB works in SuperSpeed. For more details, see https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/phy/qualcomm/phy-qcom-qmp-combo.c?h=v6.6.2.

USB interfaces

USB supports multiple interfaces to transfer audio, video, debug information, and tethering. Each of the following USB interface communication protocol is different and has its own protocols in addition to the standard USB protocol.

Android debug bridge (ADB)
- The USB ADB is a debug interface, providing access to the system through the USB connection. For more information about ADB, see https://developer.android.com/tools/adb.
- The filenames are the virtual eps names of the dev node. For more information about f_fs.c, see https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/gadget/function/f_fs.c?h=v6.6.2.
- User space service: The user space daemon adbd.service operates ADB and is responsible for establishing the connection between the underlying kernel driver and the host PC.
Diagnostics (diag)
- Diag is a diagnostics framework used for collecting log data from various subsystems, and debugging. The diag data is transmitted through USB to the host PC.
- Kernel driver: Diag uses f_fs.c to expose the /dev/ffs-diag node, which is operated by a user space service for various operations. The dev node has the following three files:
  - ep0: control operations
  - ep1: read operations
  - ep2: write operations These filenames are the virtual eps names of the dev node. For more information about f_fs.c, see https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/gadget/function/f_fs.c?h=v6.6.2.
Mass storage
- A generic interface driver with mass storage driver is available for the device to act as a generic storage device.
- Kernel driver: The mass_storage functionality is regulated by the f_mass_storage.c driver. This driver exposes dev node[revisit], which is controlled by the host PC. For more information about mass storage, see https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/gadget/function/f_mass_storage.c?h=v6.6.2.
Remote network driver interface specification (RNDIS)
- RNDIS is a specification developed by Microsoft for network devices on dynamic plug and play I/O buses such as USB.
- Kernel driver: It uses a f_rndis driver, which is present in the upstream Linux kernel and directly communicates with the network interfaces or stack.
Network control model (NCM)
- NCM is a protocol designed to offer advanced features and capabilities compared to RNDIS.
- It’s commonly found in applications where USB devices must handle demanding networking tasks.
USB audio class 2 (UAC2)
- UAC2 is a standard governing the communication between USB audio devices and computers.
- UAC2 supports higher audio data transfer rates, resulting in improved audio quality and reduced latency.
USB video class (UVC)
- UVC is a standard that defines how video streaming devices, such as webcams, should communicate with computers using USB.
- UVC facilitates the plug-and-play functionality for video devices.

USB tools

A few commonly used USB tools are listed in the following table. Table : USB tool and download details

USB tools	Download link
Platform tools (adb/fastboot)	https://developer.android.com/tools/releases/platform-tools
USB video class (UVC)	`LibUVC` https://github.com/libuvc/libuvc https://libuvc.github.io/libuvc/
UVC gadget	https://github.com/wlhe/uvc-gadget
UVC streamer	https://github.com/bsapundzhiev/uvc-streamer
UVC Video4Linux	`v4l2-utils`: https://linuxtv.org/downloads/v4l-dvb-apis/driver-api/v4l2-core.html

Configure USB boot loader

The device tree parameters for tuning the high-speed and SuperSpeed USB signal quality in the boot loader can be modified using the Qualcomm DeviceTree editor (QDTE) tool. QDTE tool is used to configure the device tree binary blob by editing the xbl_config.elf file, as shown in the following figure. For more information about how to configure the device tree blobs, see the QDTE section. The device tree file path at the Linux host machine is /boot_images/boot/Settings/Soc/<Chipset>/Core/WiredConnectivity/USB/usb.dtsi. Figure : Device tree layout The following table lists the properties for tuning the HS-USB PHY and SS USB PHY signal quality. Table : USB configuration properties

Property name	Property description	Data type	Possible values and value range	Device behavior
`path=/soc/usb0/hs_phy_cfg`	Tunes the USB signal quality for the primary USB controller HS-PHY.	UINT32-array	This property is an array of address, value pairs <`addr`, `val`> `addr` is 4 bytes in length. It can have 1 of the 4 values, range: `[0x88E306C, 0x88E3070, 0x88E3074, 0x88E3078]` `val` is of 1 byte in length, range: `0x00` to `0xFF`	Improved USB signal quality for the primary USB HS-PHY.
`path=/soc/usb0/ss_phy_cfg`	Improves signal quality for primary USB controller SS-PHY.	UINT32-array	This property is an array of address, value pairs <`addr`, `val`> `addr` is 4 bytes in length. Range: `[0x088E8000, 0x088EB000]` `val` is of 1 byte in length, range: `0x00` to `0xFF`	Improved signal quality for the primary USB SS-PHY.
`path=/soc/usb1/hs_phy_cfg`	Improves the USB signal quality for the secondary USB controller HS-PHY.	UINT32-array	This property is an array of address, value pairs <`addr`, `val`> `addr` is 4 bytes in length. It can have 1 of the 4 values, range: `[0x88E406C,0x88E4070, 0x88E4074, 0x88E4078]` `val` is of 1 byte in length, range: `0x00` to `0xFF`	Improved signal quality for secondary USB HS-PHY.
`Path = /sw/usb_config/fastboot_core_num`	Select the USB core number for Fastboot (primary=0/secondary=1)	UINT32	0 or 1	The Fastboot device is enumerated at either USB core0 or core1 according to the selected property.

Configure USB camera

The Qualcomm Linux devices provide driver support for USB web cameras that adhere to the USB video class (UVC) standard. The uvcvideo driver of the Linux kernel supports cameras. For more information about the uvcvideo driver, see 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 the character device nodes such as /dev/videoX. In the user space, applications can manage USB cameras using the v4l2src GStreamer plug-in, which comes bundled with the Qualcomm Intelligent Multimedia SDK (IM SDK). Alternatively, programs such as Yavta (yet another V4L2 test application) directly interact with the V4L2 (Video4Linux2) interface to test and control camera devices. The current release doesn’t include the Yavta program by default. To obtain and cross-compile Yavta on the host device, do the following:

The cross-compilation environment can be established using any of the following methods.
- Method 1: To set up the cross-compilation environment, run the following command.
  sudo apt install gcc-aarch64-linux-gnu
- Method 2: To set up the cross-compilation environment, run the following commands:
  1. Download the cross-compiler.
    wget https://releases.linaro.org/archive/14.07/components/toolchain/binaries/gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux.tar.xz
  2. Extract the cross-compiler.
    tar -xf gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux.tar.xz
  3. Set up the environment for cross-compilation by running the following command.
    export PATH=$PATH:`pwd`/gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux/bin

Clone the Yavta repository and change the directory.

git clone https://github.com/fastr/yavta.git
cd yavta

Cross-compile the tool.

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

To push Yavta to the Qualcomm Linux hardware SoCs, do the following:
1. Open the SSH shell in permissive mode or use the ADB shell. For more information about how to run SSH, see the Use SSH section.
2. Mount the file system.
  mount -o remount,rw /usr
3. Transfer files using SCP or similar tools. For example, scp yavta root@10.92.162.185:/usr/bin
4. Assign permission to execute in Yavta.
  chmod 0777 /usr/bin/yavta

Prerequisite: Obtain image format and size

To configure the USB camera either through Yavta or GStreamer, the following steps are mandatory.

To know the enumeration details, plug in the USB camera and run the following command.

lsusb

The following output is displayed.

Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 03f0:0959 HP, Inc w200
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Identify the USB camera video node created as /dev/videoX from the serial console.
ls /sys/bus/usb/devices/1-1/1-1:1.0/video4linux/
NoteThe 1-1/1-1:1.0 value varies according to the USB device connected. The following output is displayed.
video4 video5

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

yavta /dev/video*X* --enum-formats

where X value is based on the node. For example:

yavta /dev/video4 --enum-formats

The following output is displayed.

Device /dev/video*X* opened: w200: w200 (usb-xhci-hcd.2.auto-1).
- Available formats:
	Format 0: MJPG (47504a4d)
	Type: Video capture (1)
	Name: Motion-JPEG
	Frame size: 1280x720 (1/30, 1/25, 1/20, 1/15, 1/10, 1/5)
	Frame size: 800x600 (1/30)
	Frame size: 640x480 (1/30)
	Frame size: 320x240 (1/30)
	Format 1: YUYV (56595559)
	Type: Video capture (1)
	Name: YUYV 4:2:2
	Frame size: 1280x720 (1/10)
	Frame size: 800x600 (1/15)
	Frame size: 640x480 (1/30)
	Frame size: 320x240 (1/30)

Select the required image format and size from step 3.

Configure USB camera using Yavta

Prerequisite: Ensure that Yavta is cross-compiled, and the output format, size are identified.

To select MJPEG format of 1280x720 output size and 30 fps, capture 10 frames under /tmp/ with filename testmjpeg-00000*.bin, run the following command.

cd /usr/bin

yavta -f MJPEG -s 1280x720 -t 1/30 -c10 -F/tmp/testmjpeg /dev/video*X*

The following output is displayed.

Device /dev/video*X* opened: w200: w200 (usb-xhci-hcd.2.auto-1).
Video format set: width: 1280 height: 720 buffer size: 1843789
Video format: MJPG (47504a4d) 1280x720
Current frame rate: 1/30
Setting frame rate to: 1/30
Frame rate set: 1/30
8 buffers requested.
length: 1843789 offset: 0
Buffer 0 mapped at address 0x7fabd5d000.
length: 1843789 offset: 1847296
Buffer 1 mapped at address 0x7fabb9a000.
length: 1843789 offset: 3694592
Buffer 2 mapped at address 0x7fab9d7000.
length: 1843789 offset: 5541888
Buffer 3 mapped at address 0x7fab814000.
length: 1843789 offset: 7389184
Buffer 4 mapped at address 0x7fab651000.
length: 1843789 offset: 9236480
Buffer 5 mapped at address 0x7fab48e000.
length: 1843789 offset: 11083776
Buffer 6 mapped at address 0x7fab2cb000.
length: 1843789 offset: 12931072
Buffer 7 mapped at address 0x7fab108000.
0 (0) [-] 0 57672 bytes 2459.697791 315967245.973463
1 (1) [-] 1 40816 bytes 2459.730553 315967246.005839
2 (2) [-] 2 40472 bytes 2459.763517 315967246.039485
3 (3) [-] 3 41272 bytes 2459.797002 315967246.073073
4 (4) [-] 4 42232 bytes 2459.830192 315967246.105592
5 (5) [-] 5 46024 bytes 2459.863253 315967246.139142
6 (6) [-] 6 47440 bytes 2459.896755 315967246.172384
7 (7) [-] 7 48840 bytes 2459.930006 315967246.205114
8 (0) [-] 8 50248 bytes 2459.963235 315967246.238308
9 (1) [-] 9 53136 bytes 2459.996526 315967246.272690
Captured 9 frames in 0.300183 seconds (29.981711 fps, 1559555.337911 B/s).
8 buffers released.

To select YUV format of 1280x960 output size, 30 fps, capture 10 frames under /tmp/, the generated filename is testyuv-00000*.bin, run the following command.

yavta -f YUYV -s 1280x720 -t 1/30 -c10 -F/tmp/testyuv /dev/video*X*

NoteEnable the Permissive mode using command #setenforce 0. The following output is displayed.

Device /dev/video*X* opened: w200: w200 (usb-xhci-hcd.2.auto-1).
Video format set: width: 1280 height: 720 buffer size: 1843200
Video format: YUYV (56595559) 1280x720
Current frame rate: 1/10
Setting frame rate to: 1/10
Frame rate set: 1/10
8 buffers requested.
length: 1843200 offset: 0
Buffer 0 mapped at address 0x7f9853e000.
length: 1843200 offset: 1843200
Buffer 1 mapped at address 0x7f9837c000.
length: 1843200 offset: 3686400
Buffer 2 mapped at address 0x7f981ba000.
length: 1843200 offset: 5529600
Buffer 3 mapped at address 0x7f97ff8000.
length: 1843200 offset: 7372800
Buffer 4 mapped at address 0x7f97e36000.
length: 1843200 offset: 9216000
Buffer 5 mapped at address 0x7f97c74000.
length: 1843200 offset: 11059200
Buffer 6 mapped at address 0x7f97ab2000.
length: 1843200 offset: 12902400
Buffer 7 mapped at address 0x7f978f0000.
0 (3) [-] 3 1843200 bytes 2536.837027 315967323.172707
1 (4) [-] 4 1843200 bytes 2536.937122 315967323.273059
2 (6) [-] 6 1843200 bytes 2537.136830 315967323.472473
3 (7) [-] 7 1843200 bytes 2537.237183 315967323.572533
4 (2) [-] 17 1843200 bytes 2538.237266 315967324.571848
5 (2) [-] 24 1843200 bytes 2538.936539 315967325.271919
6 (3) [-] 25 1843200 bytes 2539.036550 315967325.372403
Warning: bytes used 0 != image size 1843200
7 (7) [E] 28 0 bytes 2539.336529 3159  325.609436
Warning: bytes used 0 != image size 1843200
8 (0) [E] 22 0 bytes 2538.737975 315967325.610149
Warning: bytes used 0 != image size 1843200
9 (1) [E] 23 0 bytes 2538.837814 315967325.610622
Captured 9 frames in 2.438312 seconds (3.691078 fps, 5291529.549951 B/s).
8 buffers released.

Configure USB camera using GStreamer in Qualcomm IM SDK

Qualcomm IM SDK uses GStreamer, an open-source multimedia framework to expose easy APIs and plugins in both the multimedia and machine learning domains. For information about installing the Qualcomm IM SDK, see the Getting Started section. The Qualcomm IM SDK includes the v4l2src plug-in, which allows input from USB cameras with a selected format. The waylandsink plug-in is responsible for rendering the video output on a Wayland display. NotePrerequisites:

Ensure that Yavta is cross-compiled, and the output format and size are identified.
To download or update the firmware, see Download PCIe to USB controller firmware.

To set the environment variables for the Wayland display, run the following command in the serial console.
export XDG_RUNTIME_DIR=/dev/socket/weston && export WAYLAND_DISPLAY=wayland-1

Use GStreamer commands to stream video from the camera to the UI. Ensure that you set the appropriate device ID (/dev/videoX) and select the correct format based on the USB camera detection. NoteIn GStreamer, the YUYV color format is referred to as YUY2. Hence, you must specify the YUYV format while setting up a pipeline and use YUY2 in the caps filter.

For 720p, run the following command:

gst-launch-1.0 -e v4l2src io-mode=dmabuf-import device="/dev/video0" ! video/x-raw,format=YUY2,width=1280,height=720,framerate=10/1 ! waylandsink fullscreen=true

The following output is displayed.

Y2,width=1280,height=720,framerate=10/1 ! waylandsink fullscreen=true
Setting pipeline to PAUSED ...
I/Adreno-UNKNOWN (1985,1985): <ReadGpuID:357>: Reading chip ID through GSL
GBM_INFO::msmgbm_mapper(262)::gbm mapper instantiated
gbm_create_device(224): Info: backend name is: msm_drm
Pipeline is live and does not need PREROLL ...
Pipeline is PREROLLED ...
Setting pipeline to PLAYING ...
New clock: GstSystemClock
gbm_create_device(224): Info: backend name is: msm_drm
GBM_ERR::msmgbm_bo_create(870)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for data fd errono: 22 (Invalid argument) drm fd: 24 data fd: 26
 GBM_ERR::msmgbm_bo_create(923)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for metadata fd errono: 22 (Invalid argument) drm fd: 24 metadata fd: 27
GBM_ERR::msmgbm_bo_create(870)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for data fd errono: 22 (Invalid argument) drm fd: 24 data fd: 29
GBM_ERR::msmgbm_bo_create(923)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for metadata fd errono: 22 (Invalid argument) drm fd: 24 metadata fd: 30
GBM_ERR::msmgbm_bo_create(870)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for data fd errono: 22 (Invalid argument) drm fd: 24 data fd: 32
GBM_ERR::msmgbm_bo_create(923)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for metadata fd errono: 22 (Invalid argument) drm fd: 24 metadata fd: 33
GBM_ERR::msmgbm_bo_create(870)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for data fd errono: 22 (Invalid argument) drm fd: 24 data fd: 35
GBM_ERR::msmgbm_bo_create(923)::DRM_IOCTL_PRIME_FD_TO_HANDLE failed for metadata fd errono: 22 (Invalid argument) drm fd: 24 metadata fd: 36
Redistribute latency...
0:00:47.7 / 99:99:99.

For 1080p, run the following command:

gst-launch-1.0 -e v4l2src io-mode=dmabuf-import device="/dev/video0" ! video/x-raw,format=YUY2,width=1920,height=1080,framerate=5/1 ! waylandsink fullscreen=true

Customize USB device

This section describes the requirements for various configurations and customizations in the USB software.

Example shell script for a USB composition with diag and ADB interfaces

cd /sys/kernel/config/usb_gadget/adb
echo on > /sys/bus/platform/devices/a600000.usb/power/control
echo "" > UDC
mkdir functions/ffs.diag
echo "QCOM" > strings/0x409/manufacturer
echo 0x05c6 > idVendor
echo 0x901d > idProduct
echo "Diag_ADB" > configs/c.1/strings/0x409/configuration

if [ ! -d /dev/ffs-diag ]; then
mkdir -p /dev/ffs-diag
fi
if [ ! -e /dev/ffs-diag/ep0 ]; then
mount -o uid=2000,gid=2000 -t functionfs diag /dev/ffs-diag
fi

/usr/bin/diag-router &

cd configs/c.1
rm -r ffs.usb0
ln -s ../../functions/ffs.diag f1
ln -s ../../functions/ffs.usb0 f2
cd ../../ udcname=`ls -1 /sys/class/udc | head -n 1`
echo $udcname > UDC
echo auto > /sys/bus/platform/devices/a600000.usb/power/control

Change USB composition through QUSB service

usb.service starts the QUSB service at /usr/bin/qusb to provide users the flexibility to configure the USB gadgets. It completely removes the hassle of manually executing commands to initialize USB from configfs. Prerequisite: Enable SELinux by running the following command.

setenforce 0

Example:

qusb [bind] [unbind] [showpid] [help]
                     [setpid [-p] <PID>] [persist <PID>]

Enable and configure UVC use case

The USB video device class (also USB video class or UVC) is a USB device class that describes devices capable of streaming video, such as webcams, digital camcorders, transcoders, analog video converters, and still-image cameras. The latest revision of the USB video class specification is v1.5. The USB implementers forum describes both the basic protocol and the different payload formats in v1.5. NoteDragonwing IQ-9075 and Dragonwing IQ-8275 don’t support the UVC use case. The tools and procedures to test the UVC are as follows:

UVC gadget (device side): It’s a sample application to test the f_uvc functional driver. It opens the video node created by uvc_gadget and sends MJPEG frames at a specified frame rate. This application is cross-compiled for the DUT. NoteEnsure that the packages and tools required for cross-compiling a 64‑bit Arm® technology compiler are installed on the host machine.

The cross-compilation environment can be established using any of the following options.
- Option A: Run the following command.
  sudo apt install gcc-aarch64-linux-gnu
- Option B: To set up the cross-compilation environment, run the following commands:
  1. Download the cross-compiler.
    wget https://releases.linaro.org/archive/14.07/components/toolchain/binaries/gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux.tar.xz
  2. Extract the cross-compiler.
    tar -xf gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux.tar.xz
  3. Set up the environment for cross-compilation by running the following command.
    export PATH=$PATH:`pwd`/gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux/bin

To build the UVC gadget tool, do the following.

Clone the uvc-gadget repository.

git clone https://github.com/wlhe/uvc-gadget.git
cd uvc-gadget

Modify Makefile for a static build.

git diff
diff --git a/Makefile b/Makefile
index ccf5a34..5be54cc 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@ CROSS_COMPILE   ?=
 ARCH           ?= x86
 KERNEL_DIR     ?= /usr/src/linux
-CC             := $(CROSS_COMPILE)gcc
+CC             := $(CROSS_COMPILE)gcc -static
 KERNEL_INCLUDE := -I$(KERNEL_DIR)/include -I$(KERNEL_DIR)/arch/$(ARCH)/include
 CFLAGS         := -W -Wall -g $(KERNEL_INCLUDE)
 LDFLAGS                := -g

Cross-compile for arm64 to generate the uvc‑gadget executable.
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

UVC viewer (host side): To receive the UVC data, open any USB webcam application on the computer.
1. To validate, push the UVC gadget application and sample image files to the device, do the following:
  1. Open the SSH shell in permissive mode or use the ADB shell. For more information about how to run SSH, see the Use SSH section.
  2. Mount the file system.
    mount -o remount,rw /usr
  3. Transfer files using SCP or similar tools. For example, scp uvc-gadget root@10.92.175.138:/usr/bin
  4. Assign permission to execute.
    chmod 0777 /usr/bin/uvc-gadget
2. Change to any UVC composition (90DF or 90CB). For example,
  qusb setpid 90CB

USB is enumerated in UVC composition only when a user space video application is open. For the USB enumeration to occur, start the uvc_gadget application through a console (serial console or SSH shell or use the ADB shell).

YUYV
1. Push the image-720.yuv image file to /root or /etc.
  scp image-720.yuv root@10.92.175.138:/root
2. Verify the image-720.yuv image with the uvc-gadget tool.
  uvc-gadget -u /dev/videoX -i /root/image-720.yuv -s 2 -m 2 -n 32 -t 10 -f 0
  - Where X indicates the new video node created after the composition switch
  - Where -f is format with the following values:
    - 0 = V4L2_PIX_FMT_YUYV
    - 1 = V4L2_PIX_FMT_MJPEG
MJPEG
1. Push the image-720.jpg image file to /root or /etc.
  scp image-720.jpg root@10.92.175.138:/root
2. Verify the image-720.jpg image with the uvc-gadget tool.
  uvc-gadget -u /dev/videoX -i /root/image-720.jpg -s 2 -m 2 -n 32 -t 10 -f 1
  - Where X indicates the new video node created after the composition switch
  - Where -f is <format> with the following values:
    - 0 = V4L2_PIX_FMT_YUYV
    - 1 = V4L2_PIX_FMT_MJPEG

For information about usage, run the following command.

./uvc-gadget -h

The following output is displayed.

Usage: uvc-gadget [options]
Available options are
-b             Use bulk mode
-d             Do not use any real V4L2 capture device
-f <format>    Select frame format
        0 = V4L2_PIX_FMT_YUYV
        1 = V4L2_PIX_FMT_MJPEG
-h             Print this help screen and exit
-i image       MJPEG image
-m             Streaming mult for ISOC (b/w 0 and 2)
-n             Number of Video buffers (b/w 2 and 32)
-o <IO method> Select UVC IO method:
        0 = MMAP
        1 = USER_PTR
-r <resolution> Select frame resolution:
        0 = 360p, VGA (640x360)
        1 = 720p, WXGA (1280x720)
-s <speed>     Select USB bus speed (b/w 0 and 2)
        0 = Full Speed (FS)
        1 = High Speed (HS)
        2 = Super Speed (SS)
-t             Streaming burst (b/w 0 and 15)
-u device      UVC Video Output device
-v device      V4L2 Video Capture device

UAC use cases

USB audio uses isochronous, interrupt, and control transfers. All audio data is transferred using isochronous transfers. The interrupt transfers are used to relay information regarding the availability of audio clocks and control transfers are used to set volume, request sample rates. NoteDragonwing IQ-9075 and Dragonwing IQ-8275 don’t support the UAC use case. To verify, select a USB composition with a UAC function.

qusb setpid 90CA

To capture or play back, use tinyutils applications such as tinyplay/tinycap available in the rootfs. The application opens the PCM nodes created in /dev/snd/ when the UAC driver binds are successful. The following are a few sample commands.

List the sound card on the Linux host machine.

arecord -L 
aplay -f S16_LE -r 44100 -c 2 -D front:CARD=qcs6490rb3gen2v,DEV=0 441k_16bit_5min_m1dB.wav

Play back the audio file.

To play the audio from device to host, push the file.wav file with the matching audio configuration. The following is an example of a sample configuration.

cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/p_chmask

Output:

cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/c_chmask

Output:

cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/p_srate

Output:

cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/c_srate

Output:

cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/p_ssize

Output:

cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/c_ssize

Output:

NoteTo modify the audio configuration, adjust the preceding parameters before establishing the USB composition to 90CA.

Run the following command on the SSH shell or use the ADB shell.
tinyplay
The following output is displayed.
Usage: tinyplay file.wav [-D card] [-d device] [-p period_size] [-n n_periods]
Run the following command on a Linux host machine with an application such as arecord to capture the audio.
arecord -f S16_LE -r 44100 -c 2 -D front:CARD=qcs6490rb3gen2v,DEV=0 test1.wav

Record an audio file.

Run the following command on a Linux host machine with an application such as aplay to play the audio.
aplay -f S16_LE -r 44100 -c 2 -D front:CARD=qcs6490rb3gen2v,DEV=0 441k_16bit_5min_m1dB.wav

Run the following command on the SSH shell of the device or use the ADB shell.

tinycap

The following output is displayed.

Usage: tinycap file.wav [-D card] [-d device] [-c channels] [-r rate] [-b bits] [-a 	bits_packed] [-p period_size] [-n n_periods] [-T capture time]

Data role swapping in USB power delivery

Data role swap (DR_SWAP) is the exchange of DFP (host) and UFP (device) roles between port partners using a USB Type-C connector. Power role swap (PR_SWAP) exchanges the source and sink roles between the port partners. NoteDragonwing IQ-9075 and Dragonwing IQ-8275 don’t support data and power role swapping using Type-C connectors.

Data role

To swap data roles from host to device, run the following commands:

cat /sys/class/typec/port0/data_role

The following output is displayed.

[host] device

echo device > /sys/class/typec/port0/data_role
cat /sys/class/typec/port0/data_role

The following output is displayed.

host [device]

To swap data roles from device to host, run the following commands:

cat /sys/class/typec/port0/data_role

The following output is displayed.

host [device]

echo host > /sys/class/typec/port0/data_role
cat /sys/class/typec/port0/data_role

The following output is displayed.

[host] device

Power role

To swap power roles from sink to source, run the following commands:

cat /sys/class/typec/port0/power_role

The following output is displayed.

source [sink]

echo source > /sys/class/typec/port0/power_role
cat /sys/class/typec/port0/power_role

The following output is displayed.

[source] sink

To swap power role from source to sink, run the following commands:

cat /sys/class/typec/port0/power_role

The following output is displayed.

[source] sink

echo sink > /sys/class/typec/port0/power_role
cat /sys/class/typec/port0/power_role

The following output is displayed.

source [sink]

Customize with configfs

The configfs file system provides the converse of the sysfs functionality. A number of interfaces can configure Linux USB gadgets, with each interface representing a USB function. The qusb executable configures the configfs USB gadget using the following commands.

Create configfs and mount functionfs.
qusb init
Start adbd/diag services.
Bind configfs with the USB gadget application.
qusb bind
Stop or unbind the USB gadget application.
qusb unbind
Set diag and ADB composition.
qusb setpid 901D
List the available USB compositions.
qusb showpid
The USB compositions are as follows.
- A4A1 NCM
- 4EE7 ADB
- 900E DIAG
- 901C DIAG + UAC2
- 901D DIAG + ADB
- 9015 MASS_STORAGE + ADB
- 9024 RNDIS + ADB
- 902A RNDIS + MASS_STORAGE
- 902B RNDIS + ADB + MASS_STORAGE
- 902C RNDIS + DIAG
- 902D RNDIS + DIAG + ADB
- 902F RNDIS + DIAG + MASS_STORAGE
- 9060 DIAG + QDSS + ADB
- 908C NCM + ADB
- 90CA DIAG + UAC2 + ADB
- 90CB DIAG + UVC + ADB
- 90CC DIAG + UAC2 + UVC + ADB
- 90DF DIAG + UVC
- 90E0 DIAG + UAC2 + UVC
- F000 MASS_STORAGE
- F00E RNDIS

Verify USB device

The following table lists the various methods to verify the USB device and host modes. Table : USB device and host mode verification

USB mode	Feature	Description
USB device mode	ADB	By default, USB is enumerated in the ADB-only composition.
Diag	See Example shell script for a USB composition with diag and ADB interfaces and Change USB composition through QUSB service.
Mass storage	Change the USB composition (see Change USB composition through QUSB service) and select the mass_storage composition.
Composition switch	See Example shell script for a USB composition with diag and ADB interfaces and Change USB composition through QUSB service.
USB LPM with cable connects and disconnects	Disconnect USB manually so that the `dwc3-qcom` module changes to low-power mode.
Network control modem (NCM)	Change the USB composition (Change USB composition through QUSB service) and select the NCM composition.
USB host mode	Host human interface device (HID) class	Switch to host mode by connecting the HID class device directly to the device under test.
Host mass storage (MS) class	Switch to host mode by connecting the MS class device directly to the device under test.
Host hub class	Switch to host mode by connecting the hub class device directly to the device under test.
Host power management	Peripherals support the host-mode suspend (headsets) state when the `dwc3-qcom` module changes to low-power mode in host mode.
USB LPM with peripheral connect and disconnect	Peripherals support the host mode suspend (headsets) when the `dwc3-qcom` module changes to low-power mode in host mode.
USB L1 LPM with high speed	High-speed peripherals support host mode suspend (headsets) when the `dwc3-qcom` module changes to low-power mode in host mode.
USB camera	See Configure USB camera.

Debug USB issues

This section provides information on the various methods to obtain debugging logs. The debugging methods include regdumps, debug ftraces, configfs nodes. The logs provide visibility into the event and controller state details when debugging issues with low-power mode entry-exit, SMMU faults, unclocked accesses. NoteDragonwing IQ-9075 and Dragonwing IQ-8275 don’t support USB Type-C feature.

Trace USB

The debugfs tracing provides a deeper view into each transaction over the USB line. To view the list of traces, run the following command.

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

NoteEnsure that debugfs is mounted. If not mounted, run the following command to mount debugfs.

mount -t debugfs none /sys/kernel/debug

Following are the traces available for verifying data transfers in the xHCI/gadget stack/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 xHCI/host controller driver (HCD), run the following command.

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

Following are the traces available for verifying data transfers 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 of the USB video class (UVC) gadget driver, run the following command.

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

The following output is displayed.

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 following output is displayed.

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. NoteThe a600000.usb address varies depending the chipset.

Mode of operation.

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

Sample output:

device

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

Current link state.

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

Sample output.

Sleep

List 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

The regdump command provides the current state 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

View file system attributes for host mode using sysfs

To view the bus details, 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 list the contents of the current directory, run the following command.

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 details about the 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

USB examples

QCS6490: https://github.com/torvalds/linux/blob/master/arch/arm64/boot/dts/qcom/qcs6490-rb3gen2.dts For information about RPM changes in the USB driver and other examples, see https://patchwork.kernel.org/project/linux-usb/list/?series=793939&archive=both. For information about how to flatten a device tree, see https://lore.kernel.org/all/af60c05b-4a0f-51b8-486a-1fc601602515@quicinc.com/ and https://lore.kernel.org/all/20231016-dwc3-refactor-v1-0-ab4a84165470@quicinc.com/. \

​Clocks

​Voltage rails

​Interrupts

​Interconnect

​USB controller reset using clock control

​USB controller software reset using register

​USB controller and SoC integration

​xHCI support

​USB Type-C connector system software interface (UCSI)

​USB features

​Runtime power management

​Software features

​USB architecture

​USB interfaces

​USB tools

​Configure USB boot loader

​Configure USB camera

​Prerequisite: Obtain image format and size

​Configure USB camera using Yavta

​Configure USB camera using GStreamer in Qualcomm IM SDK

​Customize USB device

​Example shell script for a USB composition with diag and ADB interfaces

​Change USB composition through QUSB service

​Enable and configure UVC use case

​UAC use cases

​Data role swapping in USB power delivery

​Customize with configfs

​Verify USB device

​Debug USB issues

​Trace USB

​USB regdump

​View file system attributes for host mode using sysfs

​USB examples

Clocks

Voltage rails

Interrupts

Interconnect

USB controller reset using clock control

USB controller software reset using register

USB controller and SoC integration

xHCI support

USB Type-C connector system software interface (UCSI)

USB features

Runtime power management

Software features

USB architecture

USB interfaces

USB tools

Configure USB boot loader

Configure USB camera

Prerequisite: Obtain image format and size

Configure USB camera using Yavta

Configure USB camera using GStreamer in Qualcomm IM SDK

Customize USB device

Example shell script for a USB composition with diag and ADB interfaces

Change USB composition through QUSB service

Enable and configure UVC use case

UAC use cases

Data role swapping in USB power delivery

Customize with configfs

Verify USB device

Debug USB issues

Trace USB

USB regdump

View file system attributes for host mode using sysfs

USB examples