USB overview

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP21x lines, STM32MP23x lines, STM32MP25x lines

This article gives information about the Linux^® USB framework.
It explains how to activate the USB interface and, based on examples, how to access it from user space.

1. Framework purpose[edit | edit source]

The USB (universal serial bus) Linux^® framework supports many types of:

host controllers and peripheral devices.
gadget drivers and classes to be used within a peripheral.

Linux can be used on the host machine. In this case various types of peripherals can be plugged in, such as:

Mass storage (hard drive, USB stick...)
HID (keyboard, mouse...)

Linux can also be used as a device on the peripheral side, using gadget drivers. In this case, it can act as:

a USB mass storage (for example, to export some partitions, file system)
an Ethernet card
a serial interface
...

2. System overview[edit | edit source]

2.1. On STM32MP1 series[edit | edit source]

2.2. On STM32MP21x lines [edit | edit source]

STM32MP21 USB Implementation architecture

2.3. On STM32MP23x lines [edit | edit source]

2.4. On STM32MP25x lines [edit | edit source]

2.5. Component description[edit | edit source]

USB userland (user space)
- Host-side userland
- libusb^[1] is a userland library that provides access to USB devices.

- usbutils^[2] is a set of USB utilities for collecting information about the USB devices that are connected to the USB host. Note that usbutils depends on libusb.

- One of the well-known utilities is lsusb, used to display information about USB buses and the devices connected to them.
- Gadget userland
- libusbg^[3] is a userland library that provides routines for creating and parsing USB gadget devices using the configfs API.

- Gadget configfs provides configuration interface available through user terminal, used to configure USB gadget.
- Common userland
- sysfs provides an information interface available through the user terminal. See How to monitor with sysfs below.

- debugfs provides a debugging interface available through the user terminal. See How to monitor with debugfs below.

USB framework (kernel space): composed of two parts, USB host-side and USB gadget, which rely on the USB core with specific APIs to support USB host and devices controllers.
- Host-side provides the API interface to class drivers and forwards the request from class drivers to host controller driver.
- Gadget requires a peripheral controller and the gadget driver to use it.

USB controller drivers (kernel space)
- USB host controller drivers such as STM32 USBH USB host controllers in the USB host-side framework. STM32 USBH uses kernel community drivers (kernel space), based on the USB framework.
- Enhanced Host Controller Interface (EHCI) driver and Generic platform ehci driver

- Open Host Controller Interface (OHCI) driver and Generic platform ohci driver

- STM32 USBH glue driver applicable for STM32MP21x lines , STM32MP23x lines and STM32MP25x lines
- USB dual role controller drivers such as STM32 OTG and STM32 USB3DR, are used in the USB host-side framework or in the USB gadget framework respectively when they are in otg or host mode, and/or when in otg or peripheral mode.
- Synopsys HS OTG Controller driver , on STM32MP1 series and STM32MP21x lines STM32 OTG uses kernel community driver (kernel space), based on the USB framework.

- Synopsys USB3 DRD Controller driver , on STM32MP25x lines and STM32MP23x lines STM32 USB3DR uses kernel community driver (kernel space) and STM32 USB3DR glue driver .
- USB controller drivers can rely on the Generic PHY framework to manage the physical layer for USB data transmissions. STM32 USBPHYC, STM32 USB2PHY, or STM32 COMBOPHY PHY providers have PHY drivers in the Generic PHY framework:
- STM32 USBPHYC driver , on STM32MP1 series

- STM32 USB2PHY driver on STM32MP21x lines and STM32MP23x lines

- STM32 USB2PHY driver and STM32 COMBOPHY driver on STM32MP25x lines
- USB Type-C^® and USB Power Delivery driver such as STM32 UCSI driver to manage UCSI controller running a X-CUBE-UCSI Firmware Package on:
- an external STM32G0 for the STM32MP135F-DK board on STM32MP13x lines .

- an external STM32G0 for the STM32MP2 boards on STM32MP21x lines .

- the Arm^® Cortex^®-M coprocessor for the STM32MP2 boards on STM32MP23x lines and STM32MP25x lines .

Information

On STM32MP23x lines and STM32MP25x lines , the UCSI the USBPD_DRP_UCSI STMM32Cube application must be loaded on the Arm^® Cortex^®-M coprocessor using the Linux remoteproc framework

USB hardware controllers (hardware)
- STM32MP1 series, USB controllers such as:
- STM32 USBH internal peripheral, using an on-chip high-speed UTMI+ PHY (STM32 USBPHYC internal peripheral).

- STM32 OTG internal peripheral, using an on-chip high-speed UTMI+ PHY (STM32 USBPHYC internal peripheral) or on-chip full-speed PHY for STM32 OTG internal peripheral (on STM32MP15x lines ).
- STM32MP21x lines , USB controllers such as:
- STM32 USBH internal peripheral using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY internal peripheral).

- STM32 OTG internal peripheral, using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY internal peripheral).
- STM32MP23x lines , USB controllers such as:
- STM32 USBH internal peripheral using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY internal peripheral).

- STM32 USB3DR internal peripheral using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY internal peripheral).

- STM32 UCPD internal peripheral Type-C^® USB Power Delivery interface (UCPD) with built-in analog PHY.
- STM32MP25x lines , USB controllers such as:
- STM32 USBH internal peripheral using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY internal peripheral).

- STM32 USB3DR internal peripheral using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY internal peripheral) and PIPE interface for USB3 PHY (STM32 COMBOPHY).

- STM32 UCPD internal peripheral Type-C^® USB Power Delivery interface (UCPD) with built-in analog PHY.

USB devices (external USB devices)
- USB OTG specification^[4] defines two roles for USB devices: A-device and B-device. STM32 OTG controller or STM32 USB3DR controller, depending on the used USB connector, can accept both A-device and B-device, while STM32 USBH Host controller only manages B-Device:
- A-device is a power supplier acting as a USB host (for example, a PC).

- B-device is a power consumer and acts as a USB peripheral (for example, a USB key).

Information

USB Type-C^® devices can act as:

Fixed power source and host, for example, A role.
Fixed power sink and peripheral, for exmaple, B role.
Dual role power and dual role data, thanks to USB Power Delivery protocol^[5].

2.6. API description[edit | edit source]

See USB kernel documentation for more details on API functions.

3. Configuration[edit | edit source]

3.1. Kernel configuration[edit | edit source]

USB support, STM32 USBH driver, STM32 OTG driver and STM32 USB3DR driver are activated by default in ST deliveries. Nevertheless, if a specific configuration is required, this section indicates how the USB framework can be activated/deactivated in the kernel.

Activate USB support (CONFIG_USB=y) in the kernel configuration with the Linux Menuconfig tool: Menuconfig or how to configure kernel then select:

Device Drivers  --->
 [*] USB support  --->

Then activate the USB controllers drivers.

To activate the STM32 USBH driver, select:

Device Drivers  --->
   --- USB support
   <*>   Support for Host-side USB
   <*>   EHCI HCD (USB 2.0) support
   <*>     Generic EHCI driver for a platform device
   <*>   OHCI HCD (USB 1.1) support
   <*>     Generic OHCI driver for a platform device

In addition, on STM32MP23x lines and STM32MP25x lines , select:

Device Drivers  --->
   --- USB support
   <*>   STM32 USB2 Host Glue support

To activate the STM32 OTG driver on STM32MP1 series and STM32MP21x lines , select:

Device Drivers  --->
   --- USB support
   <*>   Support for Host-side USB
   <*>   USB Gadget Support  --->
   <*>   DesignWare USB2 DRD Core Support
           DWC2 Mode Selection (Dual Role mode)  --->

To activate the STM32 USBPHYC driver on STM32MP1 series, select:

PHY Subsystem  --->
  -*- PHY Core
  <*> STMicroelectronics STM32 USB HS PHY Controller driver

To activate the STM32 USB3DR driver on STM32MP23x lines and STM32MP25x lines , select:

Device Drivers  --->
   --- USB support
   <*>   USB Gadget Support  --->
   <*>   DesignWare USB3 DRD Core Support
           DWC3 Mode Selection (Dual Role mode)  --->
           <*>     STM32 DWC3 support

To activate the STM32 USB2PHY driver on STM32MP21x lines , on STM32MP23x lines and on STM32MP25x lines , select:

PHY Subsystem  --->
  -*- PHY Core
  <*> STMicroelectronics STM32 USB2 PHY Controller driver

To activate the STM32 COMBOPHY driver on STM32MP25x lines only, select:

PHY Subsystem  --->
  -*- PHY Core
  <*> STMicroelectronics ComboPHY driver for STM32 MP25

3.2. Device tree configuration[edit | edit source]

3.2.1. STM32MP1 series[edit | edit source]

Detailed DT configurations for STM32 USB internal peripherals:

For STM32 USBH host controller: USBH device tree configuration
For STM32 OTG controller: OTG device tree configuration
For STM32 USBPHYC PHY: USBPHYC device tree configuration

3.2.2. STM32MP21x lines [edit | edit source]

Detailed DT configurations for STM32 USB internal peripherals:

For STM32 USBH host controller: USBH device tree configuration
For STM32 OTG controller: OTG device tree configuration
For STM32 USB2PHY PHY: USB2PHY device tree configuration

3.2.3. STM32MP23x lines [edit | edit source]

Detailed DT configurations for STM32 USB internal peripherals:

For STM32 USBH host controller: USBH device tree configuration
For STM32 USB3DR controller: USB3DR device tree configuration
For STM32 USB2PHY PHY: USB2PHY device tree configuration

3.2.4. STM32MP25x lines [edit | edit source]

Detailed DT configurations for STM32 USB internal peripherals:

For STM32 USBH host controller: USBH device tree configuration
For STM32 USB3DR controller: USB3DR device tree configuration
For STM32 USB2PHY PHY: USB2PHY device tree configuration
For STM32 COMBOPHY PHY: COMBOPHY device tree configuration

4. How to use the framework[edit | edit source]

4.1. How to list USB devices[edit | edit source]

lsusb displays information about the attached USB buses and devices.
In the example below, on STM32MP1 series, there is an onboard hub. A USB mouse and a USB keyboard are plugged into the hub.

lsusb /* root hubs correspond to STM32 USB controllers (USBH,  OTG) */
Bus 002 Device 005: ID 413c:2003 Dell Computer Corp. Keyboard
Bus 002 Device 004: ID 046d:c016 Logitech, Inc. Optical Wheel Mouse
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

lsusb -t /* lsusb -t shows the USB class, the driver used and the number of ports and speed of each USB devices */
/:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=ehci-platform/2p, 480M
    |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M
        |__ Port 1: Dev 5, If 0, Class=Human Interface Device, Driver=usbhid, 1.5M
        |__ Port 3: Dev 4, If 0, Class=Human Interface Device, Driver=usbhid, 1.5M
/:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=dwc2/1p, 480M

To limit lsusb to the USB keyboard:

lsusb -s 002:005 /* lsusb -s [Bus]:[Device] */
Bus 002 Device 005: ID 413c:2003 Dell Computer Corp. Keyboard
lsusb -d 413c:2003 /* lsusb -d [ID] */
Bus 002 Device 005: ID 413c:2003 Dell Computer Corp. Keyboard

To limit lsusb to the USB keyboard and display its descriptors:

lsusb -D /dev/bus/usb/002/005 /* lsusb -D /dev/bus/usb/[Bus]/[Device] */
Device: ID 413c:2003 Dell Computer Corp. Keyboard
Device Descriptor:
 ...

The example below shows a super speed mass storage device plugged on STM32MP25x lines , into the USB3DR port:

lsusb
Bus 004 Device 002: ID 0781:5581 SanDisk Corp. Ultra
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

lsusb -t
/:  Bus 04.Port 1: Dev 1, Class=root_hub, Driver=xhci-hcd/1p, 5000M
    |__ Port 1: Dev 2, If 0, Class=Mass Storage, Driver=usb-storage, 5000M
/:  Bus 03.Port 1: Dev 1, Class=root_hub, Driver=xhci-hcd/1p, 480M
/:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=ehci-platform/1p, 480M
/:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=ohci-platform/1p, 12M

4.2. How to mount a USB key (mass-storage)[edit | edit source]

mkdir /usb
mount /dev/sdxx /usb

4.3. How to configure USB gadget through configfs[edit | edit source]

See USB Gadget configfs documentation for an introduction to USB gadget configfs structure and how to use it to configure Linux USB gadget.

Here is an example to configure the USB gadget through configfs to use the OTG as a USB Ethernet gadget with "CDC NCM" (network control model). See: stm32_usbotg_eth_config.sh .

/sbin/stm32_usbotg_eth_config.sh 
Usage: /sbin/stm32_usbotg_eth_config.sh (stop | start | restart)

This script is activated by default in the OpenSTLinux distributions, thanks to udev rule: 97-ustotg.rules .

cat /etc/udev/rules.d/97-ustotg.rules 
ACTION=="add", SUBSYSTEM=="udc", RUN+="/sbin/stm32_usbotg_eth_config.sh start"
ACTION=="remove", SUBSYSTEM=="udc", RUN+="/sbin/stm32_usbotg_eth_config.sh stop"

4.4. How to use typec from sysfs[edit | edit source]

See USB kernel documentation for more details on the USB Type-C^® connector class. To check and configure Type-C^® connector, "port0" corresponding to the MPU board can be used:

cd /sys/class/typec
ls
port0     # Only port0 is shown: nothing is plugged into the connector

After plugging the board, to either a host or a peripheral, "port0-partner" can be found:

ls /sys/class/typec
port0  port0-partner     # Type-C is plugged

The board roles can be found by reading from port0 entries:

cat /sys/class/typec/port0/data_role
[host] device     # The board is in host mode
cat /sys/class/typec/port0/power_role 
[source] sink     # The board is supplying the bus

To determine if the device plugged into the connector supports the USB Power Delivery protocol^[5], use:

cat /sys/class/typec/port0-partner/supports_usb_power_delivery
no     # example with a legacy USB stick

4.5. How to perform USB data role swap or power role swap from sysfs[edit | edit source]

Information

When plugging two DRP/DRD (dual role power, dual role data) devices together, data role swap or power role swap can be achieved from sysfs.

Below example uses two STM32MP135F-DK boards plugged together through a Type-C^® cable:

cat /sys/class/typec/port0-partner/supports_usb_power_delivery
yes
cd /sys/class/typec/port0
cat data_role 
[host] device
cat power_role 
[source] sink

Initial conditions when plugging the two boards cannot be determined in advance. Here, the board acts as host (source).
Thanks to the USB Power Delivery protocol^[5], roles can be swapped independently:

echo device > data_role
cat data_role
host [device]
cat power_role 
[source] sink

Similarly, power roles can be swapped by using:

echo sink > power_role

The board now acts as a device and sinks current from the partner. To come back to the initial sate:

echo host > data_role
echo source > power_role

5. How to trace and debug the framework[edit | edit source]

5.1. How to monitor[edit | edit source]

5.1.1. How to monitor with debugfs[edit | edit source]

Refer to the USB devices chapter^[6] to decode the output.

cat /sys/kernel/debug/usb/devices

T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=480  MxCh= 1
B:  Alloc=  0/800 us ( 0%), #Int=  0, #Iso=  0
D:  Ver= 2.00 Cls=09(hub  ) Sub=00 Prot=01 MxPS=64 #Cfgs=  1
P:  Vendor=1d6b ProdID=0002 Rev= 4.14
S:  Manufacturer=Linux 4.14.0 dwc2_hsotg
S:  Product=DWC OTG Controller
S:  SerialNumber=49000000.usb-otg
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#=  4 Spd=480  MxCh= 0
D:  Ver= 2.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=64 #Cfgs=  1
P:  Vendor=05e3 ProdID=0723 Rev=94.54
S:  Manufacturer=Generic 
S:  Product=USB Storage
C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=500mA
I:* If#= 0 Alt= 0 #EPs= 2 Cls=08(stor.) Sub=06 Prot=50 Driver=usb-storage
E:  Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E:  Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms

T:  Bus=02 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=480  MxCh= 2
B:  Alloc=  0/800 us ( 0%), #Int=  2, #Iso=  0
D:  Ver= 2.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS=64 #Cfgs=  1
P:  Vendor=1d6b ProdID=0002 Rev= 4.14
S:  Manufacturer=Linux 4.14.0 ehci_hcd
S:  Product=EHCI Host Controller
S:  SerialNumber=5800d000.usbh-ehci
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=02 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=480  MxCh= 4
D:  Ver= 2.00 Cls=09(hub  ) Sub=00 Prot=02 MxPS=64 #Cfgs=  1
P:  Vendor=0424 ProdID=2514 Rev= b.b3
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=  2mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=01 Driver=hub
E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=256ms
I:* If#= 0 Alt= 1 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=02 Driver=hub
E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=256ms

T:  Bus=02 Lev=02 Prnt=02 Port=03 Cnt=01 Dev#=  5 Spd=1.5  MxCh= 0
D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=413c ProdID=2003 Rev= 1.00
S:  Manufacturer=Dell
S:  Product=Dell USB Keyboard
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 70mA
I:* If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=01 Driver=usbhid
E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=24ms

5.1.2. How to monitor with sysfs[edit | edit source]

5.1.2.1. USB buses monitoring with sysfs[edit | edit source]

Refer to What are the sysfs structures for Linux USB?^[7].

ls /sys/bus/usb/devices/
1-0:1.0  1-1  1-1:1.0  2-0:1.0  2-1  2-1.4  2-1.4:1.0  2-1:1.0  usb1  usb2

The names that begin with usb refer to USB controllers.

The device naming scheme is the following:

bus-port.port.port... (1-1, 2-1, or 2-1.4 in the example above)

The interfaces are indicated by suffixes in the following form:

:config.interface (1-1:1.0, 2-1:1.0, 2-1.4:1.0 in the example above)

Each interface corresponds to an entry in sysfs and can have its own driver.

5.1.2.2. USB gadget monitoring with sysfs[edit | edit source]

Once the USB gadget is configured, USB device controller sysfs is populated. See Documentation/ABI/stable/sysfs-class-udc for a description of each file.

ls /sys/class/udc/49000000.usb-otg/
a_alt_hnp_support  device           is_selfpowered  srp
a_hnp_support      function         maximum_speed   state
b_hnp_enable       is_a_peripheral  power           subsystem
current_speed      is_otg           soft_connect    uevent

5.2. How to trace[edit | edit source]

5.2.1. How to trace with usbmon[edit | edit source]

usbmon ^[8] collects traces of the input/output on the USB bus.
It relies on a kernel part and on a user part, and reports the requests made by USB device drivers to the host controller drivers.
Activate USBMON support (CONFIG_USB_MON=y) in the kernel configuration with the Linux Menuconfig tool: Menuconfig or how to configure kernel.
An usbmon entry is created in debugfs. It includes several files.
The file names consist of a number (the USB bus - 0 relates to all buses) and a letter (s, u, or t). The s file contains a generic event overview. The t (deprecated) and u files stream trace data.
To gather debug data, either use the master file 0u (to capture data from all devices) or find out the bus to which your device is connected and use the corresponding bus file. For example, if the device is connected to bus 1:

cat /sys/kernel/debug/usb/usbmon>1u > bus1data.log

To stop the capture, just type (CTRL+C) to kill the command. You can then analyze the log with the vUSBAnalyzer graphical tool on your Linux host.

5.2.2. How to trace using a protocol analyzer[edit | edit source]

A USB protocol analyzer is a USB traffic sniffer that decodes USB descriptors and displays bus states and packets sent. Refer to the USB protocol analyzer user manual.

5.2.3. How to trace UCSI with ftrace[edit | edit source]

The UCSI framework proposes some trace points that can be traced by the Linux^® kernel Ftrace tool. I²C layer can also be traced, as it is used to communicate with the UCSI controller.

echo 1 > /sys/kernel/debug/tracing/events/ucsi/enable # Tracing UCSI Events
echo 1 > /sys/kernel/debug/tracing/events/i2c/enable  # Tracing I2C Events
echo 1 > /sys/kernel/debug/tracing/tracing_on

Once ftrace has been enabled, any event on the Type-C connector can be traced (plug, unplug, or power event).

cat /sys/kernel/debug/tracing/trace
...
  irq/61-0-0053-410     [000] .....   292.223643: i2c_write: i2c-0 #0 a=053 f=0000 l=1 [04]
  irq/61-0-0053-410     [000] .....   292.223652: i2c_read: i2c-0 #1 a=053 f=0001 l=4
  irq/61-0-0053-410     [000] .....   292.223890: i2c_reply: i2c-0 #1 a=053 f=0001 l=4 [02-00-00-20]
  irq/61-0-0053-410     [000] .....   292.223896: i2c_result: i2c-0 n=2 ret=2
...
    kworker/0:0-6       [000] .....   292.225223: ucsi_connector_change: port0 status: change=5004, opmode=4, connected=1, sourcing=0, partner_flags=1, partner_type=1, request_data_obj=00000000, BC status=0
...

5.3. How to debug[edit | edit source]

5.3.1. Activating USB framework debug messages[edit | edit source]

A detailed dynamic trace is available in How to use the kernel dynamic debug.

 echo "file usb* +p" > /sys/kernel/debug/dynamic_debug/control

This command enables all the traces related to the USB core and drivers at runtime.
A finer selection can be made by choosing only the files to trace.

Information

Reminder: loglevel needs to be increased to 8 either by using boot arguments or by sending the dmesg -n 8 command from the console.

5.3.2. EHCI/OHCI driver debugfs entry[edit | edit source]

EHCI/OHCI drivers export a debugfs entry when CONFIG_DYNAMIC_DEBUG is enabled.

ls /sys/kernel/debug/usb/ohci/5800c000.usbh-ohci/
async  periodic  registers
ls /sys/kernel/debug/usb/ehci/5800d000.usbh-ehci/
async  bandwidth  periodic  registers

async dumps a snapshot of the async schedule.
bandwith dumps the bandwidth allocation.
periodic dumps a snapshot of the periodic schedule.
registers dumps the USB controller registers.

5.3.3. DWC2 driver debug messages and debugfs entry[edit | edit source]

To get the verbose messages from the DWC2 driver used by STM32 OTG, activate "enable debugging messages" in the Linux kernel via the menuconfig Menuconfig or how to configure kernel.

Device Drivers  --->
   [*] USB support
   <*>   Support for Host-side USB
   <*>   USB Gadget Support  --->
   <*>   DesignWare USB2 DRD Core Support
   [*]     Enable Debugging Messages
   [*]       Enable Verbose Debugging Messages
   [ ]     Enable Missed SOF Tracking
   [*]     Enable Debugging Messages For Periodic Transfers

This can be done manually in your kernel .config file:

CONFIG_USB_SUPPORT=y
CONFIG_USB_DWC2=y
CONFIG_USB_DWC2_DEBUG=y
CONFIG_USB_DWC2_VERBOSE=y
CONFIG_USB_DWC2_DEBUG_PERIODIC=y

The debug support for the DWC2 driver (CONFIG_USB_DWC2_DEBUG) compiles all the files located in the Linux kernel drivers/usb/dwc2/ folder with the DEBUG flag.

Information

Reminder: loglevel needs to be increased to 8 by using either boot arguments or the dmesg -n 8 command through the console.

The DWC2 driver also exports a debugfs entry that contain useful information:

ls /sys/kernel/debug/usb/49000000.usb-otg/
dr_mode  ep0  ep1in  ep1out  ep2in  ep2out  ep3in  ep3out  ep4in  ep4out  ep5in  ep5out  ep6in  ep6out  ep7in  ep7out  ep8in  ep8out  fifo  hw_params  params  regdump state  testmode

dr_mode indicates the working mode of the USB controller. It can be "host", "peripheral" or "otg". The value is set through a device tree property.
ep* files show the state of the given endpoint.
fifo shows the FIFO information for the overall FIFO and all the periodic transmission FIFOs.
hw_params shows the parameters read from USB controller registers.
params shows the parameters used by the driver.
regdump dumps all the USB controller registers.
state shows the overall state of the hardware controller and some general information on the available endpoints.
testmode shows/sets usb test mode ("test_j", "test_k", "test_se0_nak", "test_packet", "test_force_enable").

5.3.4. DWC3 driver debugfs entry[edit | edit source]

The DWC3 driver provides some debugfs entries that contains useful information:

ls /sys/kernel/debug/usb/48300000.usb/  # when in host mode
link_state  lsp_dump  mode  regdump  testmode

link_state file shows the state of the link, when the controller is in device mode (it is not available otherwise).
lsp_dump dumps internal LSP registers.
mode indicates the working mode of the USB controller (device or host).
regdump dumps all the USB controller registers.
testmode shows/sets usb test mode ("test_j", "test_k", "test_se0_nak", "test_packet", "test_force_enable", "no test").

ls /sys/kernel/debug/usb/48300000.usb/  # when in device mode
ep0in   ep10in   ep11in   ep1in   ep2in   ep3in   ep4in   ep5in   ep6in   ep7in   ep8in   ep9in   link_state  mode     testmode
ep0out  ep10out  ep11out  ep1out  ep2out  ep3out  ep4out  ep5out  ep6out  ep7out  ep8out  ep9out  lsp_dump    regdump

ep* files show the state of the given endpoint.

5.3.5. xHCI driver debugfs entry[edit | edit source]

The xHCI driver exports a debugfs entry when CONFIG_DEBUG_FS is enabled. The xHCI driver is used when the DWC3 driver is in host mode.

cd /sys/kernel/debug/usb/xhci/xhci-hcd.*
ls
command-ring  devices  event-ring  ports  reg-cap  reg-ext-legsup:00  reg-ext-protocol:00  reg-ext-protocol:01  reg-op  reg-runtime

These entries allow to inspect the command ring, the event ring, and the doorbell array.

6. Source code location[edit | edit source]

The source files are located inside the Linux kernel.

The USB framework is under drivers/usb/
The drivers used for STM32 USBH are under drivers/usb/host/ehci-platform.c , drivers/usb/host/ehci-hcd.c and drivers/usb/host/ohci-platform.c , drivers/usb/host/ohci-hcd.c
- On STM32MP21x lines , STM32MP23x lines and STM32MP25x lines a glue driver is additionally used, and can be found in drivers/usb/host/usbh-stm32.c
The driver used for STM32 OTG is under drivers/usb/dwc2/ , STM32MP1 series and STM32MP21x lines
The driver used for STM32 USB3DR is under drivers/usb/dwc3/ , STM32MP25x lines
The UCSI driver used in Linux to control USB Type-C^® and USB Power Delivery is under drivers/usb/typec/ucsi/ucsi_stm32g0.c
The UCSI firmware used either in the coprocessor or in an external STM32G0, can be found:
- X-CUBE-UCSI Firmware Package

- USBPD_DRP_UCSI application , on STM32MP23x lines and STM32MP25x lines

7. References[edit | edit source]

[libusb-1] usb: a cross-platform library to access USB devices

[usbutils-2] usbutils: USB utilities for Linux, including lsusb

[libusbg-3] usbg: a C library encapsulating the kernel USB gadget-configfs userspace API functionality

[otg_specification-4] On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification

[usbpdintro-5] 5.0 ^5.1 ^5.2 Introduction to USB Power Delivery with STM32

[6] Linux USB API: The Linux-USB Host Side API - The USB devices

[7] What are the sysfs structures for Linux USB?

[8] usbmon

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]