Commit 5fd2733e5a821acf0358f51d436b61209deac9a5
1 parent
e00cb2232b
Exists in
v2017.01-smarct4x
and in
35 other branches
dm: usb: Add a README for driver model
Add some documentation describing how USB is implemented with USB. This might make things easier for people to understand. Signed-off-by: Simon Glass <sjg@chromium.org>
Showing 1 changed file with 415 additions and 0 deletions Inline Diff
doc/driver-model/usb-info.txt
File was created | 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 | ||
416 |