]>
Commit | Line | Data |
---|---|---|
5fd2733e SG |
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_parentdata(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_parentdata(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@chromium.org> | |
415 | 23-Mar-15 |