usb-info.rst 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. How USB works with driver model
  3. ===============================
  4. Introduction
  5. ------------
  6. Driver model USB support makes use of existing features but changes how
  7. drivers are found. This document provides some information intended to help
  8. understand how things work with USB in U-Boot when driver model is enabled.
  9. Enabling driver model for USB
  10. -----------------------------
  11. A new CONFIG_DM_USB option is provided to enable driver model for USB. This
  12. causes the USB uclass to be included, and drops the equivalent code in
  13. usb.c. In particular the usb_init() function is then implemented by the
  14. uclass.
  15. Support for EHCI and XHCI
  16. -------------------------
  17. So far OHCI is not supported. Both EHCI and XHCI drivers should be declared
  18. as drivers in the USB uclass. For example:
  19. .. code-block:: c
  20. static const struct udevice_id ehci_usb_ids[] = {
  21. { .compatible = "nvidia,tegra20-ehci", .data = USB_CTLR_T20 },
  22. { .compatible = "nvidia,tegra30-ehci", .data = USB_CTLR_T30 },
  23. { .compatible = "nvidia,tegra114-ehci", .data = USB_CTLR_T114 },
  24. { }
  25. };
  26. U_BOOT_DRIVER(usb_ehci) = {
  27. .name = "ehci_tegra",
  28. .id = UCLASS_USB,
  29. .of_match = ehci_usb_ids,
  30. .ofdata_to_platdata = ehci_usb_ofdata_to_platdata,
  31. .probe = tegra_ehci_usb_probe,
  32. .remove = tegra_ehci_usb_remove,
  33. .ops = &ehci_usb_ops,
  34. .platdata_auto_alloc_size = sizeof(struct usb_platdata),
  35. .priv_auto_alloc_size = sizeof(struct fdt_usb),
  36. .flags = DM_FLAG_ALLOC_PRIV_DMA,
  37. };
  38. Here ehci_usb_ids is used to list the controllers that the driver supports.
  39. Each has its own data value. Controllers must be in the UCLASS_USB uclass.
  40. The ofdata_to_platdata() method allows the controller driver to grab any
  41. necessary settings from the device tree.
  42. The ops here are ehci_usb_ops. All EHCI drivers will use these same ops in
  43. most cases, since they are all EHCI-compatible. For EHCI there are also some
  44. special operations that can be overridden when calling ehci_register().
  45. The driver can use priv_auto_alloc_size to set the size of its private data.
  46. This can hold run-time information needed by the driver for operation. It
  47. exists when the device is probed (not when it is bound) and is removed when
  48. the driver is removed.
  49. Note that usb_platdata is currently only used to deal with setting up a bus
  50. in USB device mode (OTG operation). It can be omitted if that is not
  51. supported.
  52. The driver's probe() method should do the basic controller init and then
  53. call ehci_register() to register itself as an EHCI device. It should call
  54. ehci_deregister() in the remove() method. Registering a new EHCI device
  55. does not by itself cause the bus to be scanned.
  56. The old ehci_hcd_init() function is no-longer used. Nor is it necessary to
  57. set up the USB controllers from board init code. When 'usb start' is used,
  58. each controller will be probed and its bus scanned.
  59. XHCI works in a similar way.
  60. Data structures
  61. ---------------
  62. The following primary data structures are in use:
  63. - struct usb_device:
  64. This holds information about a device on the bus. All devices have
  65. this structure, even the root hub. The controller itself does not
  66. have this structure. You can access it for a device 'dev' with
  67. dev_get_parent_priv(dev). It matches the old structure except that the
  68. parent and child information is not present (since driver model
  69. handles that). Once the device is set up, you can find the device
  70. descriptor and current configuration descriptor in this structure.
  71. - struct usb_platdata:
  72. This holds platform data for a controller. So far this is only used
  73. as a work-around for controllers which can act as USB devices in OTG
  74. mode, since the gadget framework does not use driver model.
  75. - struct usb_dev_platdata:
  76. This holds platform data for a device. You can access it for a
  77. device 'dev' with dev_get_parent_platdata(dev). It holds the device
  78. address and speed - anything that can be determined before the device
  79. driver is actually set up. When probing the bus this structure is
  80. used to provide essential information to the device driver.
  81. - struct usb_bus_priv:
  82. This is private information for each controller, maintained by the
  83. controller uclass. It is mostly used to keep track of the next
  84. device address to use.
  85. Of these, only struct usb_device was used prior to driver model.
  86. USB buses
  87. ---------
  88. Given a controller, you know the bus - it is the one attached to the
  89. controller. Each controller handles exactly one bus. Every controller has a
  90. root hub attached to it. This hub, which is itself a USB device, can provide
  91. one or more 'ports' to which additional devices can be attached. It is
  92. possible to power up a hub and find out which of its ports have devices
  93. attached.
  94. Devices are given addresses starting at 1. The root hub is always address 1,
  95. and from there the devices are numbered in sequence. The USB uclass takes
  96. care of this numbering automatically during enumeration.
  97. USB devices are enumerated by finding a device on a particular hub, and
  98. setting its address to the next available address. The USB bus stretches out
  99. in a tree structure, potentially with multiple hubs each with several ports
  100. and perhaps other hubs. Some hubs will have their own power since otherwise
  101. the 5V 500mA power supplied by the controller will not be sufficient to run
  102. very many devices.
  103. Enumeration in U-Boot takes a long time since devices are probed one at a
  104. time, and each is given sufficient time to wake up and announce itself. The
  105. timeouts are set for the slowest device.
  106. Up to 127 devices can be on each bus. USB has four bus speeds: low
  107. (1.5Mbps), full (12Mbps), high (480Mbps) which is only available with USB2
  108. and newer (EHCI), and super (5Gbps) which is only available with USB3 and
  109. newer (XHCI). If you connect a super-speed device to a high-speed hub, you
  110. will only get high-speed.
  111. USB operations
  112. --------------
  113. As before driver model, messages can be sent using submit_bulk_msg() and the
  114. like. These are now implemented by the USB uclass and route through the
  115. controller drivers. Note that messages are not sent to the driver of the
  116. device itself - i.e. they don't pass down the stack to the controller.
  117. U-Boot simply finds the controller to which the device is attached, and sends
  118. the message there with an appropriate 'pipe' value so it can be addressed
  119. properly. Having said that, the USB device which should receive the message
  120. is passed in to the driver methods, for use by sandbox. This design decision
  121. is open for review and the code impact of changing it is small since the
  122. methods are typically implemented by the EHCI and XHCI stacks.
  123. Controller drivers (in UCLASS_USB) themselves provide methods for sending
  124. each message type. For XHCI an additional alloc_device() method is provided
  125. since XHCI needs to allocate a device context before it can even read the
  126. device's descriptor.
  127. These methods use a 'pipe' which is a collection of bit fields used to
  128. describe the type of message, direction of transfer and the intended
  129. recipient (device number).
  130. USB Devices
  131. -----------
  132. USB devices are found using a simple algorithm which works through the
  133. available hubs in a depth-first search. Devices can be in any uclass, but
  134. are attached to a parent hub (or controller in the case of the root hub) and
  135. so have parent data attached to them (this is struct usb_device).
  136. By the time the device's probe() method is called, it is enumerated and is
  137. ready to talk to the host.
  138. The enumeration process needs to work out which driver to attach to each USB
  139. device. It does this by examining the device class, interface class, vendor
  140. ID, product ID, etc. See struct usb_driver_entry for how drivers are matched
  141. with USB devices - you can use the USB_DEVICE() macro to declare a USB
  142. driver. For example, usb_storage.c defines a USB_DEVICE() to handle storage
  143. devices, and it will be used for all USB devices which match.
  144. Technical details on enumeration flow
  145. -------------------------------------
  146. It is useful to understand precisely how a USB bus is enumerating to avoid
  147. confusion when dealing with USB devices.
  148. Device initialisation happens roughly like this:
  149. - At some point the 'usb start' command is run
  150. - This calls usb_init() which works through each controller in turn
  151. - The controller is probed(). This does no enumeration.
  152. - Then usb_scan_bus() is called. This calls usb_scan_device() to scan the
  153. (only) device that is attached to the controller - a root hub
  154. - usb_scan_device() sets up a fake struct usb_device and calls
  155. usb_setup_device(), passing the port number to be scanned, in this case
  156. port 0
  157. - usb_setup_device() first calls usb_prepare_device() to set the device
  158. address, then usb_select_config() to select the first configuration
  159. - at this point the device is enumerated but we do not have a real struct
  160. udevice for it. But we do have the descriptor in struct usb_device so we can
  161. use this to figure out what driver to use
  162. - back in usb_scan_device(), we call usb_find_child() to try to find an
  163. existing device which matches the one we just found on the bus. This can
  164. happen if the device is mentioned in the device tree, or if we previously
  165. scanned the bus and so the device was created before
  166. - if usb_find_child() does not find an existing device, we call
  167. usb_find_and_bind_driver() which tries to bind one
  168. - usb_find_and_bind_driver() searches all available USB drivers (declared
  169. with USB_DEVICE()). If it finds a match it binds that driver to create a
  170. new device.
  171. - If it does not, it binds a generic driver. A generic driver is good enough
  172. to allow access to the device (sending it packets, etc.) but all
  173. functionality will need to be implemented outside the driver model.
  174. - in any case, when usb_find_child() and/or usb_find_and_bind_driver() are
  175. done, we have a device with the correct uclass. At this point we want to
  176. probe the device
  177. - first we store basic information about the new device (address, port,
  178. speed) in its parent platform data. We cannot store it its private data
  179. since that will not exist until the device is probed.
  180. - then we call device_probe() which probes the device
  181. - the first probe step is actually the USB controller's (or USB hubs's)
  182. child_pre_probe() method. This gets called before anything else and is
  183. intended to set up a child device ready to be used with its parent bus. For
  184. USB this calls usb_child_pre_probe() which grabs the information that was
  185. stored in the parent platform data and stores it in the parent private data
  186. (which is struct usb_device, a real one this time). It then calls
  187. usb_select_config() again to make sure that everything about the device is
  188. set up
  189. - note that we have called usb_select_config() twice. This is inefficient
  190. but the alternative is to store additional information in the platform data.
  191. The time taken is minimal and this way is simpler
  192. - at this point the device is set up and ready for use so far as the USB
  193. subsystem is concerned
  194. - the device's probe() method is then called. It can send messages and do
  195. whatever else it wants to make the device work.
  196. Note that the first device is always a root hub, and this must be scanned to
  197. find any devices. The above steps will have created a hub (UCLASS_USB_HUB),
  198. given it address 1 and set the configuration.
  199. For hubs, the hub uclass has a post_probe() method. This means that after
  200. any hub is probed, the uclass gets to do some processing. In this case
  201. usb_hub_post_probe() is called, and the following steps take place:
  202. - usb_hub_post_probe() calls usb_hub_scan() to scan the hub, which in turn
  203. calls usb_hub_configure()
  204. - hub power is enabled
  205. - we loop through each port on the hub, performing the same steps for each
  206. - first, check if there is a device present. This happens in
  207. usb_hub_port_connect_change(). If so, then usb_scan_device() is called to
  208. scan the device, passing the appropriate port number.
  209. - you will recognise usb_scan_device() from the steps above. It sets up the
  210. device ready for use. If it is a hub, it will scan that hub before it
  211. continues here (recursively, depth-first)
  212. - once all hub ports are scanned in this way, the hub is ready for use and
  213. all of its downstream devices also
  214. - additional controllers are scanned in the same way
  215. The above method has some nice properties:
  216. - the bus enumeration happens by virtue of driver model's natural device flow
  217. - most logic is in the USB controller and hub uclasses; the actual device
  218. drivers do not need to know they are on a USB bus, at least so far as
  219. enumeration goes
  220. - hub scanning happens automatically after a hub is probed
  221. Hubs
  222. ----
  223. USB hubs are scanned as in the section above. While hubs have their own
  224. uclass, they share some common elements with controllers:
  225. - they both attach private data to their children (struct usb_device,
  226. accessible for a child with dev_get_parent_priv(child))
  227. - they both use usb_child_pre_probe() to set up their children as proper USB
  228. devices
  229. Example - Mass Storage
  230. ----------------------
  231. As an example of a USB device driver, see usb_storage.c. It uses its own
  232. uclass and declares itself as follows:
  233. .. code-block:: c
  234. U_BOOT_DRIVER(usb_mass_storage) = {
  235. .name = "usb_mass_storage",
  236. .id = UCLASS_MASS_STORAGE,
  237. .of_match = usb_mass_storage_ids,
  238. .probe = usb_mass_storage_probe,
  239. };
  240. static const struct usb_device_id mass_storage_id_table[] = {
  241. { .match_flags = USB_DEVICE_ID_MATCH_INT_CLASS,
  242. .bInterfaceClass = USB_CLASS_MASS_STORAGE},
  243. { } /* Terminating entry */
  244. };
  245. USB_DEVICE(usb_mass_storage, mass_storage_id_table);
  246. The USB_DEVICE() macro attaches the given table of matching information to
  247. the given driver. Note that the driver is declared in U_BOOT_DRIVER() as
  248. 'usb_mass_storage' and this must match the first parameter of USB_DEVICE.
  249. When usb_find_and_bind_driver() is called on a USB device with the
  250. bInterfaceClass value of USB_CLASS_MASS_STORAGE, it will automatically find
  251. this driver and use it.
  252. Counter-example: USB Ethernet
  253. -----------------------------
  254. As an example of the old way of doing things, see usb_ether.c. When the bus
  255. is scanned, all Ethernet devices will be created as generic USB devices (in
  256. uclass UCLASS_USB_DEV_GENERIC). Then, when the scan is completed,
  257. usb_host_eth_scan() will be called. This looks through all the devices on
  258. each bus and manually figures out which are Ethernet devices in the ways of
  259. yore.
  260. In fact, usb_ether should be moved to driver model. Each USB Ethernet driver
  261. (e.g drivers/usb/eth/asix.c) should include a USB_DEVICE() declaration, so
  262. that it will be found as part of normal USB enumeration. Then, instead of a
  263. generic USB driver, a real (driver-model-aware) driver will be used. Since
  264. Ethernet now supports driver model, this should be fairly easy to achieve,
  265. and then usb_ether.c and the usb_host_eth_scan() will melt away.
  266. Sandbox
  267. -------
  268. All driver model uclasses must have tests and USB is no exception. To
  269. achieve this, a sandbox USB controller is provided. This can make use of
  270. emulation drivers which pretend to be USB devices. Emulations are provided
  271. for a hub and a flash stick. These are enough to create a pretend USB bus
  272. (defined by the sandbox device tree sandbox.dts) which can be scanned and
  273. used.
  274. Tests in test/dm/usb.c make use of this feature. It allows much of the USB
  275. stack to be tested without real hardware being needed.
  276. Here is an example device tree fragment:
  277. .. code-block:: none
  278. usb@1 {
  279. compatible = "sandbox,usb";
  280. hub {
  281. compatible = "usb-hub";
  282. usb,device-class = <USB_CLASS_HUB>;
  283. hub-emul {
  284. compatible = "sandbox,usb-hub";
  285. #address-cells = <1>;
  286. #size-cells = <0>;
  287. flash-stick {
  288. reg = <0>;
  289. compatible = "sandbox,usb-flash";
  290. sandbox,filepath = "flash.bin";
  291. };
  292. };
  293. };
  294. };
  295. This defines a single controller, containing a root hub (which is required).
  296. The hub is emulated by a hub emulator, and the emulated hub has a single
  297. flash stick to emulate on one of its ports.
  298. When 'usb start' is used, the following 'dm tree' output will be available::
  299. usb [ + ] `-- usb@1
  300. usb_hub [ + ] `-- hub
  301. usb_emul [ + ] |-- hub-emul
  302. usb_emul [ + ] | `-- flash-stick
  303. usb_mass_st [ + ] `-- usb_mass_storage
  304. This may look confusing. Most of it mirrors the device tree, but the
  305. 'usb_mass_storage' device is not in the device tree. This is created by
  306. usb_find_and_bind_driver() based on the USB_DRIVER in usb_storage.c. While
  307. 'flash-stick' is the emulation device, 'usb_mass_storage' is the real U-Boot
  308. USB device driver that talks to it.
  309. Future work
  310. -----------
  311. It is pretty uncommon to have a large USB bus with lots of hubs on an
  312. embedded system. In fact anything other than a root hub is uncommon. Still
  313. it would be possible to speed up enumeration in two ways:
  314. - breadth-first search would allow devices to be reset and probed in
  315. parallel to some extent
  316. - enumeration could be lazy, in the sense that we could enumerate just the
  317. root hub at first, then only progress to the next 'level' when a device is
  318. used that we cannot find. This could be made easier if the devices were
  319. statically declared in the device tree (which is acceptable for production
  320. boards where the same, known, things are on each bus).
  321. But in common cases the current algorithm is sufficient.
  322. Other things that need doing:
  323. - Convert usb_ether to use driver model as described above
  324. - Test that keyboards work (and convert to driver model)
  325. - Move the USB gadget framework to driver model
  326. - Implement OHCI in driver model
  327. - Implement USB PHYs in driver model
  328. - Work out a clever way to provide lazy init for USB devices
  329. .. Simon Glass <sjg@chromium.org>
  330. .. 23-Mar-15