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