查看“USB overview”的源代码

本文提供有关 Linux<sup>&reg;</sup> USB框架的信息<br/>
它举例说明了如何激活USB接口，以及如何从用户空间访问它。<br />
<br />

==Framework purpose==
USB（通用串行总线）Linux<sup>&reg;</sup>框架支持多种类型的：
* 主机控制器和外围设备
* 在外围设备中使用的小工具驱动程序和类

Linux可以在主机上使用。 在这种情况下，可以插入各种类型的外围设备，例如：
* 大容量存储（硬盘驱动器，USB记忆棒..）
* HID（键盘，鼠标..）

使用小工具驱动程序，Linux也可以用作外围设备。 在这种情况下，它可以充当：
* USB大容量存储（例如，导出某些分区，文件系统）
* 以太网卡
* 串口
* ...

==System overview==
{{
ImageMap|Image:USB system overview.png {{!}} frame {{!}} center{{!}} USB Implementation architecture
rect 343 437 470 487 [[#Component_description | USB controller driver]]
rect 538 437 665 487 [[#Component_description | USB controller driver]]
rect 343 512 470 555 [[OTG internal peripheral | OTG internal peripheral]]
rect 538 512 665 555 [[USBH internal peripheral | USBH internal peripheral]]
rect 538 575 665 619 [[USBPHYC internal peripheral | USBPHYC internal peripheral]]
poly 342 301 479 301 479 428 404 428 404 558 342 558 [[#Component_description | USB Gadget]]
poly 536 301 674 301 674 558 410 558 410 434 536 434 [[#Component_description | USB Host-Side]]
}}

===Component description===
* '''USB用户空间'''（'用户空间''）
** “Host-Side”用户区
*:- [https://libusb.info/ libusb]<ref name="libusb">[https://libusb.info/ libusb: a cross-platform library to access USB devices]</ref>是一个Userland库，可提供对USB设备的访问。
*:- [https://github.com/gregkh/usbutils usbutils]<ref name="usbutils">[https://github.com/gregkh/usbutils usbutils: USB utilities for Linux, including lsusb]</ref> 是一组USB实用程序，用于收集有关连接到USB主机的USB设备的信息。 注意'''usbutils'''取决于'''libusb'''。
*:- 众所周知的实用程序之一是'''lsusb'''，它用于显示有关USB总线及其连接的设备的信息。
** ''Gadget'' 用户群
*:- [https://github.com/libusbg libusbg]<ref name="libusbg">[https://github.com/libusbg libusbg: a C library encapsulating the kernel USB gadget-configfs userspace API functionality]</ref> 是一个Userland库，它提供了使用configfs API创建和解析USB小工具设备的例程。
*:- {{CodeSource|Linux kernel|Documentation/usb/gadget_configfs.txt|Gadget configfs}} 提供通过用户终端可用的配置界面，用于配置USB小工具。
** 公共用户区
*:- '''sysfs''提供了一个可通过用户终端使用的信息界面。 请参见[[#How_to_monitor_with_sysfs | How to monitor with sysfs]] below.
*:- '''debugfs'''提供了一个调试界面，可通过用户终端使用。 请参见 [[#How_to_monitor_with_debugfs | How to monitor with debugfs]] .

* '''USB framework''' (''内核空间''): 由两部分组成，即USB“主机侧”和USB“小配件”，它们依赖于具有特定 [[#API_description | APIs]] 以支持USB主机和设备控制器
** 主机端为类驱动程序提供API接口，并将请求从类驱动程序转发到主机控制器驱动程序。
** Gadget需要外围控制器和小工具驱动程序才能使用。

* '''USB controller drivers''' (''内核空间'')
** USB Host-Side框架中的“ USB Host控制器驱动程序”，例如 [[USBH internal peripheral|STM32 USBH]]USB Host控制器。 [[USBH internal peripheral|STM32 USBH]] 基于[[USB overview|USB framework]]使用内核社区驱动程序（内核空间）。
*:- {{CodeSource|Linux kernel|drivers/usb/host/ehci-hcd.c|Enhanced Host Controller Interface (EHCI) driver}}and {{CodeSource|Linux kernel|drivers/usb/host/ehci-platform.c|Generic platform ehci driver}}
*:- {{CodeSource|Linux kernel|drivers/usb/host/ohci-hcd.c|Open Host Controller Interface (OHCI) driver}}and {{CodeSource|Linux kernel|drivers/usb/host/ohci-platform.c|Generic platform ohci driver}}
** USB Host-Side框架中的[USB OTG控制器驱动程序，例如 [[OTG internal peripheral|STM32 OTG]] USB OTG控制器，如果在'''otg'''或'''host''中使用它们 ”和/或USB小工具框架中的“ otg”或“ peripheral”模式使用。[[OTG internal peripheral|STM32 OTG]]  基于[[USB overview|USB framework]]使用内核社区驱动程序（内核空间）
*:- {{CodeSource|Linux kernel|drivers/usb/dwc2/|DesignWare HS OTG Controller driver}}
** USB控制器驱动程序可以依靠 [[PHY overview|Generic PHY framework]] 管理USB数据传输的物理层。 [[USBPHYC internal peripheral|STM32 USBPHYC]] PHY提供程序是通用PHY框架中的“ PHY驱动程序”：
*:- {{CodeSource|Linux kernel|drivers/phy/st/phy-stm32-usbphyc.c|STM32 USBPHYC driver}}

* '''USB hardware controllers''' (''硬件'')
USB控制器，例如 [[USBH internal peripheral|STM32 USBH internal peripheral]]和 [[OTG internal peripheral|STM32 OTG internal peripheral]], 使用片上高速UTMI + PHY（[[USBPHYC internal peripheral|STM32 USBPHYC internal peripheral]])），或用于[[OTG internal peripheral|STM32 OTG internal peripheral]]的片上全速PHY。

* '''USB devices''' (''外部USB设备'')
** USB OTG规范<ref name="otg_specification">[http://www.usb.org/developers/onthego/USB_OTG_and_EH_2-0.pdf On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification]</ref>为USB设备定义了两个角色：A设备和B设备。 [[OTG internal peripheral|STM32 OTG controller]]取决于所使用的USB连接器，可以同时接受A设备和B设备，而 [[USBH internal peripheral|STM32 USBH Host controller]] 仅管理B设备 ：
*:- '''A-Device'''是一个充当'''USB主机'''的'''电源供应商'''（例如PC）
*:- '''B-device'''是'''耗电量'''，充当'''USB外设'''(例如，USB闪存盘)。

===API description===
有关API函数的更多详细信息，请参见[https://www.kernel.org/doc/html/latest/driver-api/usb/index.html USB kernel documentation] 。

==Configuration==

===Kernel configuration===
在ST交付中，默认情况下激活USB支持，[[USBH internal peripheral|STM32 USBH]] 驱动程序和[[OTG internal peripheral|STM32 OTG]] 驱动程序。 但是，如果需要特定的配置，则本节说明如何在内核中激活/停用USB框架。
使用Linux Menuconfig工具在内核配置中激活USB支持(CONFIG_USB=y)：[[Menuconfig or how to configure kernel]]
然后选择：
 Device Drivers  --->
  [*] USB support  --->
然后激活USB控制器驱动程序。

要激活 [[USBH internal peripheral|STM32 USBH]] 驱动程序，请选择：
 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
要激活 [[OTG internal peripheral|STM32 OTG]] 驱动程序，请选择：
 Device Drivers  --->
    --- USB support
    <*>   Support for Host-side USB
    <*>   USB Gadget Support  --->
    <*>   DesignWare USB2 DRD Core Support
            DWC2 Mode Selection (Dual Role mode)  --->
然后，要激活[[USBPHYC internal peripheral|STM32 USBPHYC]] 驱动程序，请选择：
 PHY Subsystem  --->
   -*- PHY Core
   <*> STMicroelectronics STM32 USB HS PHY Controller driver

===Device tree configuration===
STM32 USB内部外围设备的详细DT配置：
* 用于[[USBH internal peripheral|STM32 USBH]] 主机控制器： [[USBH_device_tree_configuration | USBH device tree configuration]]
* 用于[[OTG internal peripheral|STM32 OTG]] 控制器：[[OTG_device_tree_configuration | OTG device tree configuration]]
* 用于 [[USBPHYC internal peripheral|STM32 USBPHYC]] PHY: [[USBPHYC_device_tree_configuration | USBPHYC device tree configuration]]

==How to use the framework==
===How to list USB devices===
'''lsusb'''显示有关所连接的USB总线和设备的信息。 <br />
在上面的示例中，我们有一个板载集线器，一个USB鼠标和USB键盘插入了该集线器。<br />

 {{Board$}} '''lsusb'''							{{Highlight|/* '''root hubs''' correspond to STM32 USB controllers ([[USBH_internal_peripheral|USBH]], [[OTG_internal_peripheral| 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

 {{Board$}} '''lsusb -t''' 	 	 	 	 	 	{{Highlight|/* '''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

要将'''lsusb'''限制为USB键盘：
 {{Board$}} '''lsusb -s 002:005''' 	 				{{Highlight|/* '''lsusb -s [Bus]:[Device]''' */}}
 Bus 002 Device 005: ID 413c:2003 Dell Computer Corp. Keyboard
 {{Board$}} '''lsusb -d 413c:2003'''  	 			 	{{Highlight|/* '''lsusb -d [ID]''' */}}
 Bus 002 Device 005: ID 413c:2003 Dell Computer Corp. Keyboard

要将'''lsusb'''限制为USB键盘并显示其描述符：
 {{Board$}} '''lsusb -D /dev/bus/usb/002/005'''  	 		{{Highlight|/* '''lsusb -D /dev/bus/usb/[Bus]/[Device]''' */}}
 Device: ID 413c:2003 Dell Computer Corp. Keyboard
 Device Descriptor:
  ...

===How to mount a USB key (mass-storage)===
 {{Board$}} mkdir /usb
 {{Board$}} mount /dev/sdxx /usb

===How to configure USB Gadget through configfs===
请参阅[https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt USB gadget configfs documentation] ，以获取USB gadget configfs结构的介绍以及如何使用它来配置Linux USB Gadget。



以下是通过配置文件配置USB Gadget以将OTG用作具有远程NDIS(RNDIS)的USB以太网Gadget的示例。 见：
[https://github.com/STMicroelectronics/meta-st-openstlinux/blob/thud/recipes-bsp/tools/usbotg-gadget-config/stm32_usbotg_eth_config.sh stm32_usbotg_eth_config.sh].

==How to trace and debug the framework==

===How to monitor===
====How to monitor with debugfs====
请参考[https://www.kernel.org/doc/html/latest/driver-api/usb/usb.html#the-usb-devices the USB devices chapter]<ref>[https://www.kernel.org/doc/html/latest/driver-api/usb/usb.html#the-usb-devices  Linux USB API: The Linux-USB Host Side API - The USB devices]</ref> 对输出进行解码。
 {{Board$}} '''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

==== How to monitor with sysfs ====
===== USB buses monitoring with sysfs =====
请参考[http://www.linux-usb.org/FAQ.html#i6 What are the sysfs structures for Linux USB?]<ref>[http://www.linux-usb.org/FAQ.html#i6  What are the sysfs structures for Linux USB?]</ref>.
 {{Board$}} 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

以“''usb''''开头的名称是指USB控制器。

设备命名方案如下：
* bus-port{{Grey|.port}}{{Grey|.port...}} ('''1-1''', '''2-1''', or '''2-1.4''' in the example above)

这些接口由后缀表示，格式如下：
* :config.interface (1-1''':1.0''', 2-1''':1.0''', 2-1.4''':1.0''' in the example above)

每个接口对应于sysfs中的一个条目，并且可以具有自己的驱动程序。

===== USB Gadget monitoring with sysfs =====
配置USB小工具后，将填充USB设备控制器sysfs。 参见 {{CodeSource | Linux kernel | Documentation/ABI/stable/sysfs-class-udc}} for a description of each file.
 {{Board$}} 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

===How to trace===
==== How to trace with usbmon ====
usbmon <ref>{{CodeSource | Linux kernel | Documentation/usb/usbmon.txt | usbmon}}</ref> 收集USB总线上的输入/输出轨迹。<br/>
它依赖于内核部分和用户部分，并将USB设备驱动程序发出的请求报告给主机控制器驱动程序。<br />
使用Linux Menuconfig工具在[[Menuconfig or how to configure kernel]]内核配置中激活USBMON支持（CONFIG_USB_MON = y）。 <br />
在debugfs中创建了一个usbmon条目。 它包括几个文件。<br />
文件名由一个数字（USB总线-0表示所有总线）和一个字母（s，u或t）组成。 s文件包含通用事件概述。 t（不建议使用）和u文件将流跟踪数据。<br />
要收集调试数据，请使用主文件0u（以从所有设备捕获数据）或找出设备所连接的总线并使用相应的总线文件。 例如，如果设备连接到总线1：
 {{Board$}} cat /sys/kernel/debug/usb/usbmon>1u > bus1data.log
要停止捕获，只需键入（CTRL + C）即可终止命令。 然后，您可以使用Linux主机上的 [http://vusb-analyzer.sourceforge.net/ vUSBAnalyzer] 图形工具来分析日志

==== How to trace using a protocol analyzer ====

USB协议分析器是一种USB流量嗅探器，用于解码USB描述符并显示发送的总线状态和数据包。 请参阅您的USB协议分析器用户手册。

===How to debug===
====Activating USB framework debug messages====
A detailed dynamic trace is available in [[How to use the kernel dynamic debug]]<br/>
  {{Board$}} 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.<br/>
A finer selection can be made by choosing only the files to trace.<br/>
{{Info|Reminder: ''loglevel'' needs to be increased to 8 either by using boot arguments or by sending the ''dmesg -n 8'' command from the console}}

==== EHCI/OHCI driver debugfs entry ====
EHCI/OHCI drivers export a debugfs entry when CONFIG_DYNAMIC_DEBUG is enabled.
 {{Board$}} ls /sys/kernel/debug/usb/ohci/5800c000.usbh-ohci/
 async  periodic  registers
 {{Board$}} 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

==== DWC2 driver debug messages and debugfs entry====
To get the verbose messages from the DWC2 driver used by [[OTG_internal_peripheral| STM32 OTG]], activate "Enable Debugging Messages" in the Linux kernel via the menuconfig [[Menuconfig or how to configure kernel]].<br/>
 Device Drivers  --->
    [*] USB support
    {{Grey|<*>   Support for Host-side USB}}
    {{Grey|<*>   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 DWC2 driver (CONFIG_USB_DWC2_DEBUG) compiles all the files located in Linux kernel {{CodeSource | Linux kernel | drivers/usb/dwc2/}} folder with DEBUG flag.<br/>
{{Info|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 contains useful information:
 {{Board$}} 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. 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").

==Source code location==
The source files are located inside the Linux kernel.
* The '''USB framework''' is under {{CodeSource | Linux kernel | drivers/usb/}}
* The drivers used for [[USBH internal peripheral | STM32 USBH]] are under {{CodeSource | Linux kernel | drivers/usb/host/ehci-platform.c}}, {{CodeSource | Linux kernel | drivers/usb/host/ehci-hcd.c}} and {{CodeSource | Linux kernel | drivers/usb/host/ohci-platform.c}}, {{CodeSource | Linux kernel | drivers/usb/host/ohci-hcd.c}}
* The driver used for [[OTG internal peripheral | STM32 OTG]] is under {{CodeSource | Linux kernel | drivers/usb/dwc2/}}

==References==
<references />