> ## Documentation Index > Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt > Use this file to discover all available pages before exploring further. # USB 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”` | | Asynchronous to the bus clock; clock rates defined within the device tree node | | `gcc_cfg_noc_usb3_prim_axi_clk “iface_clk”` | | Auxiliary bus controller unit clock. | | `gcc_aggre_usb3_prim_axi_clk “bus_aggr_clk”` | | 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** | **Description** | | | | :---------------: | :------------------------------: | :-------------: | :-------------: | ---------------------------------------- | -------------------------------------------------- | | VREG L1C | 1.8 | 1.7 | 0 | Primary and secondary HS-PHY | 1.8 V regulator used by both HS-PHYs in the system | | VREG L2B | 3.3 | 3.05 | 0 | Primary and secondary HS-PHY | 3.3 V regulator used by both HS-PHYs in the system | | VREG L1B | 0.912 | 0.912 | 0 | SS-PHY | SS-PHY VDD core | | VREG L10C | 0.880 | 0.880 | 0 | 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 | – | | 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 | | `SLAVE_EBI1` | | | APPS-USB | `MASTER_APPSS_PROC` | | | ### **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 integration***USB 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](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](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)** **Note**Dragonwing 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. **Note**Dragonwing 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: * [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/typec/ucsi/ucsi.c?h=v6.6.2](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/typec/ucsi/ucsi.c?h=v6.6.2) * [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/typec/ucsi/ucsi\_glink.c?h=v6.6.2](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/typec/ucsi/ucsi_glink.c?h=v6.6.2) * [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/typec/ucsi/displayport.c?h=v6.6.2](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/typec/ucsi/displayport.c?h=v6.6.2) * [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](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) * [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/dwc3/dwc3-qcom.c?h=v6.6.2](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/usb/dwc3/dwc3-qcom.c?h=v6.6.2) * [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/soc/qcom/pmic\_glink.c?h=v6.6.2](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/soc/qcom/pmic_glink.c?h=v6.6.2) * [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/soc/qcom/pmic\_glink\_altmode.c?h=v6.6.2](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/soc/qcom/pmic_glink_altmode.c?h=v6.6.2) ## **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/](https://lore.kernel.org/all/20231017131851.8299-1-quic_kriskura@quicinc.com/). **Note**Dragonwing 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: ```text theme={null} 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: ```text theme={null} 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. ```text theme={null} 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 ``` **Note**The 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/\*. The`` 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: ```text theme={null} 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: ```text theme={null} 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: ```text theme={null} 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](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](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](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](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](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](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](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](https://developer.android.com/tools/releases/platform-tools) | | USB video class (UVC) | `LibUVC` | | UVC gadget | [https://github.com/wlhe/uvc-gadget](https://github.com/wlhe/uvc-gadget) | | UVC streamer | [https://github.com/bsapundzhiev/uvc-streamer](https://github.com/bsapundzhiev/uvc-streamer) | | UVC Video4Linux | `v4l2-utils`: [https://linuxtv.org/downloads/v4l-dvb-apis/driver-api/v4l2-core.html](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](https://docs.qualcomm.com/bundle/publicresource/topics/80-80021-4/tools.html#qdte) section. The device tree file path at the Linux host machine is */boot\_images/boot/Settings/Soc/\/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](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: 1. 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. ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} export PATH=$PATH:`pwd`/gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux/bin ``` 2. Clone the Yavta repository and change the directory. ```text theme={null} git clone https://github.com/fastr/yavta.git cd yavta ``` 3. Cross-compile the tool. ```text theme={null} make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- ``` 4. 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](https://docs.qualcomm.com/bundle/publicresource/topics/80-80021-254/how_to.html) section. 2. Mount the file system. ```text theme={null} 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. ```text theme={null} 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. 1. To know the enumeration details, plug in the USB camera and run the following command. ```text theme={null} lsusb ``` The following output is displayed. ```text theme={null} 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 ``` 2. Identify the USB camera video node created as */dev/videoX* from the serial console. ```text theme={null} ls /sys/bus/usb/devices/1-1/1-1:1.0/video4linux/ ``` **Note**The `1-1/1-1:1.0` value varies according to the USB device connected. The following output is displayed. ```text theme={null} video4 video5 ``` 3. To view the supported output formats and sizes using Yavta, run the following command: ```text theme={null} yavta /dev/video*X* --enum-formats ``` where `X` value is based on the node. For example: ```text theme={null} yavta /dev/video4 --enum-formats ``` The following output is displayed. ```text theme={null} 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) ``` 4. 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. ```text theme={null} cd /usr/bin ``` ```text theme={null} yavta -f MJPEG -s 1280x720 -t 1/30 -c10 -F/tmp/testmjpeg /dev/video*X* ``` The following output is displayed. ```text theme={null} 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. ```text theme={null} yavta -f YUYV -s 1280x720 -t 1/30 -c10 -F/tmp/testyuv /dev/video*X* ``` **Note**Enable the Permissive mode using command `#setenforce 0`. The following output is displayed. ```text theme={null} 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](https://gstreamer.freedesktop.org/), 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](https://docs.qualcomm.com/bundle/publicresource/topics/80-80021-51/install-sdk.html) 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](https://docs.qualcomm.com/doc/80-80021-8/topic/pcie.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#pcie-software-support-for-usb__section_j5l_2jx_4bc). 1. To set the environment variables for the Wayland display, run the following command in the serial console. ```text theme={null} export XDG_RUNTIME_DIR=/dev/socket/weston && export WAYLAND_DISPLAY=wayland-1 ``` 2. 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. **Note**In 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: ```text theme={null} 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. ```text theme={null} Y2,width=1280,height=720,framerate=10/1 ! waylandsink fullscreen=true Setting pipeline to PAUSED ... I/Adreno-UNKNOWN (1985,1985): : 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: ```text theme={null} 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** ```text theme={null} 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. ```text theme={null} setenforce 0 ``` Example: ```text theme={null} qusb [bind] [unbind] [showpid] [help] [setpid [-p] ] [persist ] ``` ### **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. **Note**Dragonwing 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. **Note**Ensure that the packages and tools required for cross-compiling a 64‑bit Arm® technology compiler are installed on the host machine. 1. The cross-compilation environment can be established using any of the following options. * Option **A**: Run the following command. ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} export PATH=$PATH:`pwd`/gcc-linaro-aarch64-linux-gnu-4.9-2014.07_linux/bin ``` 2. To build the UVC gadget tool, do the following. 1. Clone the `uvc-gadget` repository. ```text theme={null} git clone https://github.com/wlhe/uvc-gadget.git cd uvc-gadget ``` 2. Modify `Makefile` for a static build. ```text theme={null} 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 ``` 3. Cross-compile for `arm64` to generate the `uvc‑gadget` executable. ```text theme={null} 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](https://docs.qualcomm.com/bundle/publicresource/topics/80-80021-254/how_to.html) section. 2. Mount the file system. ```text theme={null} 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. ```text theme={null} chmod 0777 /usr/bin/uvc-gadget ``` 2. Change to any UVC composition (90DF or 90CB). For example, ```text theme={null} 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`. ```text theme={null} scp image-720.yuv root@10.92.175.138:/root ``` 2. Verify the `image-720.yuv` image with the `uvc-gadget` tool. ```text theme={null} 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`. ```text theme={null} scp image-720.jpg root@10.92.175.138:/root ``` 2. Verify the `image-720.jpg` image with the `uvc-gadget` tool. ```text theme={null} 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 \ with the following values: * `0` = V4L2\_PIX\_FMT\_YUYV * `1` = V4L2\_PIX\_FMT\_MJPEG * For information about usage, run the following command. ```text theme={null} ./uvc-gadget -h ``` The following output is displayed. ```text theme={null} Usage: uvc-gadget [options] Available options are -b Use bulk mode -d Do not use any real V4L2 capture device -f 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 Select UVC IO method: 0 = MMAP 1 = USER_PTR -r Select frame resolution: 0 = 360p, VGA (640x360) 1 = 720p, WXGA (1280x720) -s 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. **Note**Dragonwing IQ-9075 and Dragonwing IQ-8275 don't support the UAC use case. To verify, select a USB composition with a UAC function. ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/p_chmask ``` Output: ```text theme={null} 3 ``` ```text theme={null} cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/c_chmask ``` Output: ```text theme={null} 3 ``` ```text theme={null} cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/p_srate ``` Output: ```text theme={null} 48000 ``` ```text theme={null} cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/c_srate ``` Output: ```text theme={null} 64000 ``` ```text theme={null} cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/p_ssize ``` Output: ```text theme={null} 2 ``` ```text theme={null} cat /sys/kernel/config/usb_gadget/adb/functions/uac2.0/c_ssize ``` Output: ```text theme={null} 2 ``` **Note**To 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. ```text theme={null} tinyplay ``` The following output is displayed. ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} tinycap ``` The following output is displayed. ```text theme={null} 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. **Note**Dragonwing 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: ```text theme={null} cat /sys/class/typec/port0/data_role ``` The following output is displayed. ```text theme={null} [host] device ``` ```text theme={null} echo device > /sys/class/typec/port0/data_role cat /sys/class/typec/port0/data_role ``` The following output is displayed. ```text theme={null} host [device] ``` * To swap data roles from device to host, run the following commands: ```text theme={null} cat /sys/class/typec/port0/data_role ``` The following output is displayed. ```text theme={null} host [device] ``` ```text theme={null} echo host > /sys/class/typec/port0/data_role cat /sys/class/typec/port0/data_role ``` The following output is displayed. ```text theme={null} [host] device ``` * Power role * To swap power roles from sink to source, run the following commands: ```text theme={null} cat /sys/class/typec/port0/power_role ``` The following output is displayed. ```text theme={null} source [sink] ``` ```text theme={null} echo source > /sys/class/typec/port0/power_role cat /sys/class/typec/port0/power_role ``` The following output is displayed. ```text theme={null} [source] sink ``` * To swap power role from source to sink, run the following commands: ```text theme={null} cat /sys/class/typec/port0/power_role ``` The following output is displayed. ```text theme={null} [source] sink ``` ```text theme={null} echo sink > /sys/class/typec/port0/power_role cat /sys/class/typec/port0/power_role ``` The following output is displayed. ```text theme={null} 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. 1. Create `configfs` and mount `functionfs`. ```text theme={null} qusb init ``` 2. Start `adbd/diag` services. 3. Bind `configfs` with the USB gadget application. ```text theme={null} qusb bind ``` 4. Stop or unbind the USB gadget application. ```text theme={null} qusb unbind ``` 5. Set diag and ADB composition. ```text theme={null} qusb setpid 901D ``` 6. List the available USB compositions. ```text theme={null} 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](https://docs.qualcomm.com/doc/80-80021-8/topic/usb.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#usb-customization__section_y3t_dhl_j1c) and [Change USB composition through QUSB service](https://docs.qualcomm.com/doc/80-80021-8/topic/usb.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#usb-customization__section_nqf_ghl_j1c). | | | Mass storage | Change the USB composition (see [Change USB composition through QUSB service](https://docs.qualcomm.com/doc/80-80021-8/topic/usb.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#usb-customization__section_nqf_ghl_j1c)) and select the mass\_storage composition. | | | Composition switch | See [Example shell script for a USB composition with diag and ADB interfaces](https://docs.qualcomm.com/doc/80-80021-8/topic/usb.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#usb-customization__section_y3t_dhl_j1c) and [Change USB composition through QUSB service](https://docs.qualcomm.com/doc/80-80021-8/topic/usb.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#usb-customization__section_nqf_ghl_j1c). | | | 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](https://docs.qualcomm.com/doc/80-80021-8/topic/usb.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#usb-customization__section_nqf_ghl_j1c)) 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](https://docs.qualcomm.com/doc/80-80021-8/topic/usb.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#usb-camera-configuration). | | ## **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. **Note**Dragonwing 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. ```text theme={null} ls /sys/kernel/debug/tracing/events/dwc3 ``` **Note**Ensure that `debugfs` is mounted. If not mounted, run the following command to mount `debugfs`. ```text theme={null} 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). ```text theme={null} 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. ```text theme={null} ls /sys/kernel/debug/tracing/events/xhci-hcd ``` Following are the traces available for verifying data transfers in the xHCI/HCD. ```text theme={null} 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. ```text theme={null} ls /sys/kernel/debug/tracing/events/gadget ``` The following output is displayed. ```text theme={null} 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. ```text theme={null} ls /sys/kernel/debug/tracing/events/ucsi ``` The following output is displayed. ```text theme={null} 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. **Note**The `a600000.usb` address varies depending the chipset. * Mode of operation. ```text theme={null} cat /sys/kernel/debug/usb/a600000.usb/mode ``` Sample output: ```text theme={null} device ``` * State and transfer ring buffer (TRB) queues to all endpoints in device mode. * Current link state. ```text theme={null} cat /sys/kernel/debug/usb/a600000.usb/link_state ``` Sample output. ```text theme={null} Sleep ``` * List processor (LSP) dump. ```text theme={null} cat /sys/kernel/debug/usb/a600000.usb/lsp_dump ``` Sample output: ```text theme={null} 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 ``` ```text theme={null} ls /sys/kernel/debug/usb/a600000.usb ``` Sample output: ```text theme={null} 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 ```text theme={null} cd /sys/kernel/debug/usb/a600000.usb cat regdump ``` Sample output: ```text theme={null} 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. ```text theme={null} lsusb ``` Sample output: ```text theme={null} 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. ```text theme={null} cd /sys/bus/usb/devices/ ls ``` Sample output: ```text theme={null} 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. ```text theme={null} cat /sys/kernel/debug/usb/devices ``` Sample output: ```text theme={null} 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](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](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/](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/](https://lore.kernel.org/all/20231016-dwc3-refactor-v1-0-ab4a84165470@quicinc.com/). \\