Template:ArticleMainWriter
Template:ReviewersList
Template:ArticleProposedVersion
Template:ArticleToBeReviewedByTW
SUMMARY
This article gives information about the Linux® USB framework.
It explains how to activate USB interface and, based on examples, how to access it from user space.
1. Framework purpose[edit source]
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 may be used on the host machine. In this case, various types of peripherals may be plugged in, such as:
- Mass storage (hard drive, USB stick...)
- HID (keyboard, mouse...)
- ...
Linux may be also be used on the peripheral side to act as a device, using gadget drivers. In this case, it can act as:
- USB mass storage (e.g. to export some partitions, filesystem)
- ethernet card
- serial interface
- ...
2. System overview[edit source]
2.1. Component description[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 utility 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 information interface available through user terminal. See How to monitor with sysfs below.
- - debugfs provides debug interface available through user terminal. See How to monitor with debugfs below.
- USB framework (Kernel space): composed of two parts, USB Host-Side and USB Gadget, relying on USB core with specific APIs to support USB host and devices controllers
- Host-Side provides API interface to class drivers and forwards the request from class drivers to host controller driver.
- Gadget involves a peripheral controller and the gadget driver using it.
- USB Controller drivers (Kernel space)
- USB Host controller drivers like STM32 USBH driver register USB Host controllers on USB Host-Side framework. STM32 USBH uses kernel community drivers (kernel space), based on USB framework.
- - Enhanced Host Controller Interface (EHCI) driver and Generic platform ehci driver
- - Open Host Controller Interface (OHCI) driver and Generic platform ohci driver
- USB OTG controller drivers like STM32 OTG driver register USB OTG controllers on USB Host-Side framework when they are used either in otg or host mode, and/or on USB Gadget framework when they are used either in otg or peripheral mode. STM32 OTG uses kernel community driver (kernel space), based on USB framework.
- USB controller drivers can rely on Generic PHY framework to manage physical layer for USB data transmission. PHY drivers like STM32 USBPHYC driver register PHY provider in Generic PHY framework.
- USB Hardware controllers (Hardware)
USB controllers like STM32 USBH internal peripheral and 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.
- USB devices (External USB devices)
- USB OTG specification[4] defines two roles for USB devices: A-Device and B-Device. STM32 OTG controller, depending on the USB connector used, 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 (e.g. a PC)
- - B-Device is a power consumer and acts as a USB Peripheral (e.g. a USB key).
2.2. API description[edit source]
See USB kernel documentation for more API function descriptions.
|
Coming soon |
3. Configuration[edit source]
3.1. Kernel configuration[edit source]
USB support, STM32 USBH driver and STM32 OTG driver are activated by default in ST deliveries. Nevertheless, if specific configuration is needed, this section indicates how USB can be activated/deactivated in the kernel.
Activate USB support (CONFIG_USB=y) in kernel configuration with Linux Menuconfig tool : Menuconfig or how to configure kernel then select:
Device Drivers ---> [*] USB support --->
Then activate USB Controllers drivers.
To activate 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
To activate STM32 OTG driver, select:
Device Drivers --->
--- USB support
<*> Support for Host-side USB
<*> USB Gadget Support --->
<*> DesignWare USB2 DRD Core Support
DWC2 Mode Selection (Dual Role mode) --->
Then to activate STM32 USBPHYC driver, select:
PHY Subsystem --->
-*- PHY Core
<*> STMicroelectronics STM32 USB HS PHY Controller driver
3.2. Device tree configuration[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
4. How to use framework[edit source]
4.1. How to list usb devices[edit source]
lsusb displays information about USB busses and devices attached.
In the example above, we have an onboard hub, a USB mouse and USB keyboard 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, driver used, 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 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 USB keyboard showing 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:
...
4.2. How to mount a USB key (mass-storage)[edit source]
mkdir /usb mount /dev/sdxx /usb
4.3. How to configure USB Gadget through configfs[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.
|
|
Coming soon |
5. How to trace and debug the framework[edit source]
5.1. How to monitor[edit source]
5.1.1. How to monitor with debugfs[edit source]
Please refer to The USB devices chapter[5] 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 source]
5.1.2.1. USB busses monitoring with sysfs[edit source]
Please refer to What are the sysfs structures for Linux USB?[6].
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 devices are named by the scheme:
- bus-port.port.port... (1-1, 2-1, or 2-1.4 in the example above)
The interfaces are indicated by suffixes having this form:
- :config.interface (1-1:1.0, 2-1:1.0, 2-1.4:1.0 in the example above)
Each interface gets its own entry in sysfs and can have its own driver.
5.1.2.2. USB Gadget monitoring with sysfs[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 files.
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 source]
5.2.1. How to trace with usbmon[edit source]
usbmon [7] collects traces of the input/output on the USB bus.
It relies on a kernel part and on a user part, and reports requests made by USB device drivers to Host controller drivers.
Activate USBMON support (CONFIG_USB_MON=y) in kernel configuration with Linux Menuconfig tool : Menuconfig or how to configure kernel.
Then you should have a usbmon entry in debugfs, with 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 will stream trace data.
To gather debug data, either use the master file 0u (to capture data from all devices) or find out the bus on which your device is connected and then use the corresponding bus file. For example, if the device is on bus 1:
cat /sys/kernel/debug/usb/usbmon>1u > bus1data.log
To end capture, just (CTRL-C) to kill the command. Then you can analyze the log with vUSBAnalyzer graphical tool on your Linux host.
5.2.2. How to trace using protocol analyzer[edit source]
A USB protocol analyzer is a USB traffic sniffer that decodes USB descriptors and displays bus states and packets sent. Refer to you USB protocol analyzer user manual.
5.3. How to debug[edit source]
5.3.1. Activating USB framework debug messages[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.
5.3.2. EHCI/OHCI drivers debugfs entry[edit source]
EHCI/OHCI drivers exports 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 source]
To get verbose messages from the DWC2 driver, used by STM32 OTG, activate "Enable Debugging Messages" in the Linux kernel via 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 is 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 DWC2 driver (CONFIG_USB_DWC2_DEBUG) compiles all the files located in Linux kernel drivers/usb/dwc2/ folder with DEBUG flag.
DWC2 driver exports also a debugfs entry with useful information:
ls /sys/kernel/debug/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. Can be "host", "peripheral" or "otg". The value is set through 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 overall state of the hardware controller and some general information about each of the endpoints available.
- testmode shows/sets usb test mode ("test_j", "test_k", "test_se0_nak", "test_packet", "test_force_enable").
6. Source code location[edit source]
The source file are located inside the Linux kernel.
- The USB framework is in drivers/usb/
- The drivers used for STM32 USBH are in 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
- The driver used for STM32 OTG is in drivers/usb/dwc2/
7. References[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
- ↑ Linux USB API: The Linux-USB Host Side API - The USB devices
- ↑ What are the sysfs structures for Linux USB?
- ↑ usbmon