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 STM32MP25x lines 
[edit | edit source]
2.3. 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 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 STM32 OTG uses kernel community driver (kernel space), based on the USB framework.
- - Synopsys USB3 DRD Controller driver , on STM32MP25x 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 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 .
- - the Arm® Cortex®-M coprocessor for the STM32MP2 boards on STM32MP25x lines .
 Information
|
| On 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 ).
- STM32MP25x lines , USB controllers such as:
- - STM32 USBH internal peripheral using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY).
- - STM32 USB3DR using an on-chip high-speed UTMI+ PHY (STM32 USB2PHY) and PIPE interface for USB3 PHY (STM32 COMBOPHY).
- - STM32 UCPD 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:
|
2.4. 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 STM32MP25x lines , select:
Device Drivers ---> --- USB support <*> STM32 USB2 Host Glue support
To activate the STM32 OTG driver (on STM32MP1 series), 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 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 STM32MP25x lines ), select:
PHY Subsystem ---> -*- PHY Core <*> STMicroelectronics STM32 USB2 PHY Controller driver
To activate the STM32 COMBOPHY driver (on STM32MP25x lines ), 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. 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:
root@stm32mp2:~# 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. I2C 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 STM32MP25x lines , a glue driver is additionally used, and can be found in drivers/usb/host/usbh-stm32.c
- On STM32MP25x lines
- The driver used for STM32 OTG is under drivers/usb/dwc2/ , STM32MP1 series
- 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 STM32MP25x lines
7. References[edit | edit source]
- ↑ libusb: a cross-platform library to access USB devices
- ↑ usbutils: USB utilities for Linux, including lsusb
- ↑ libusbg: a C library encapsulating the kernel USB gadget-configfs userspace API functionality
- ↑ On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification
- ↑ 5.0 5.1 5.2 Introduction to USB Power Delivery with STM32
- ↑ Linux USB API: The Linux-USB Host Side API - The USB devices
- ↑ What are the sysfs structures for Linux USB?
- ↑ usbmon
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.