]>
Commit | Line | Data |
---|---|---|
65c70539 SG |
1 | Driver Model |
2 | ============ | |
3 | ||
4 | This README contains high-level information about driver model, a unified | |
5 | way of declaring and accessing drivers in U-Boot. The original work was done | |
6 | by: | |
7 | ||
8 | Marek Vasut <marex@denx.de> | |
9 | Pavel Herrmann <morpheus.ibis@gmail.com> | |
10 | Viktor Křivák <viktor.krivak@gmail.com> | |
11 | Tomas Hlavacek <tmshlvck@gmail.com> | |
12 | ||
13 | This has been both simplified and extended into the current implementation | |
14 | by: | |
15 | ||
16 | Simon Glass <sjg@chromium.org> | |
17 | ||
18 | ||
19 | Terminology | |
20 | ----------- | |
21 | ||
22 | Uclass - a group of devices which operate in the same way. A uclass provides | |
34e4a2ec | 23 | a way of accessing individual devices within the group, but always |
65c70539 SG |
24 | using the same interface. For example a GPIO uclass provides |
25 | operations for get/set value. An I2C uclass may have 10 I2C ports, | |
26 | 4 with one driver, and 6 with another. | |
27 | ||
28 | Driver - some code which talks to a peripheral and presents a higher-level | |
29 | interface to it. | |
30 | ||
31 | Device - an instance of a driver, tied to a particular port or peripheral. | |
32 | ||
33 | ||
34 | How to try it | |
35 | ------------- | |
36 | ||
37 | Build U-Boot sandbox and run it: | |
38 | ||
39 | make sandbox_config | |
40 | make | |
41 | ./u-boot | |
42 | ||
43 | (type 'reset' to exit U-Boot) | |
44 | ||
45 | ||
46 | There is a uclass called 'demo'. This uclass handles | |
47 | saying hello, and reporting its status. There are two drivers in this | |
48 | uclass: | |
49 | ||
50 | - simple: Just prints a message for hello, doesn't implement status | |
51 | - shape: Prints shapes and reports number of characters printed as status | |
52 | ||
53 | The demo class is pretty simple, but not trivial. The intention is that it | |
54 | can be used for testing, so it will implement all driver model features and | |
55 | provide good code coverage of them. It does have multiple drivers, it | |
56 | handles parameter data and platdata (data which tells the driver how | |
57 | to operate on a particular platform) and it uses private driver data. | |
58 | ||
59 | To try it, see the example session below: | |
60 | ||
61 | =>demo hello 1 | |
62 | Hello '@' from 07981110: red 4 | |
63 | =>demo status 2 | |
64 | Status: 0 | |
65 | =>demo hello 2 | |
66 | g | |
67 | r@ | |
68 | e@@ | |
69 | e@@@ | |
70 | n@@@@ | |
71 | g@@@@@ | |
72 | =>demo status 2 | |
73 | Status: 21 | |
74 | =>demo hello 4 ^ | |
75 | y^^^ | |
76 | e^^^^^ | |
77 | l^^^^^^^ | |
78 | l^^^^^^^ | |
79 | o^^^^^ | |
80 | w^^^ | |
81 | =>demo status 4 | |
82 | Status: 36 | |
83 | => | |
84 | ||
85 | ||
86 | Running the tests | |
87 | ----------------- | |
88 | ||
89 | The intent with driver model is that the core portion has 100% test coverage | |
90 | in sandbox, and every uclass has its own test. As a move towards this, tests | |
91 | are provided in test/dm. To run them, try: | |
92 | ||
93 | ./test/dm/test-dm.sh | |
94 | ||
95 | You should see something like this: | |
96 | ||
97 | <...U-Boot banner...> | |
4324174d | 98 | Running 29 driver model tests |
65c70539 SG |
99 | Test: dm_test_autobind |
100 | Test: dm_test_autoprobe | |
1ca7e206 SG |
101 | Test: dm_test_bus_children |
102 | Device 'd-test': seq 3 is in use by 'b-test' | |
103 | Device 'c-test@0': seq 0 is in use by 'a-test' | |
104 | Device 'c-test@1': seq 1 is in use by 'd-test' | |
997c87bb | 105 | Test: dm_test_bus_children_funcs |
a8981d4f | 106 | Test: dm_test_bus_children_iterators |
e59f458d | 107 | Test: dm_test_bus_parent_data |
a327dee0 | 108 | Test: dm_test_bus_parent_ops |
65c70539 SG |
109 | Test: dm_test_children |
110 | Test: dm_test_fdt | |
5a66a8ff | 111 | Device 'd-test': seq 3 is in use by 'b-test' |
f4cdead2 | 112 | Test: dm_test_fdt_offset |
00606d7e | 113 | Test: dm_test_fdt_pre_reloc |
5a66a8ff SG |
114 | Test: dm_test_fdt_uclass_seq |
115 | Device 'd-test': seq 3 is in use by 'b-test' | |
116 | Device 'a-test': seq 0 is in use by 'd-test' | |
65c70539 | 117 | Test: dm_test_gpio |
4b8f11c2 SG |
118 | extra-gpios: get_value: error: gpio b5 not reserved |
119 | Test: dm_test_gpio_anon | |
4324174d SG |
120 | Test: dm_test_gpio_copy |
121 | Test: dm_test_gpio_leak | |
122 | extra-gpios: get_value: error: gpio b5 not reserved | |
d44f597b | 123 | Test: dm_test_gpio_requestf |
65c70539 | 124 | Test: dm_test_leak |
65c70539 SG |
125 | Test: dm_test_lifecycle |
126 | Test: dm_test_operations | |
127 | Test: dm_test_ordering | |
128 | Test: dm_test_platdata | |
00606d7e | 129 | Test: dm_test_pre_reloc |
65c70539 | 130 | Test: dm_test_remove |
4b8f11c2 SG |
131 | Test: dm_test_spi_find |
132 | Invalid chip select 0:0 (err=-19) | |
133 | SF: Failed to get idcodes | |
134 | Device 'name-emul': seq 0 is in use by 'name-emul' | |
135 | SF: Detected M25P16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB | |
136 | Test: dm_test_spi_flash | |
137 | 2097152 bytes written in 0 ms | |
138 | SF: Detected M25P16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB | |
139 | SPI flash test: | |
140 | 0 erase: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
141 | 1 check: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
142 | 2 write: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
143 | 3 read: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
144 | Test passed | |
145 | 0 erase: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
146 | 1 check: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
147 | 2 write: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
148 | 3 read: 0 ticks, 65536000 KiB/s 524288.000 Mbps | |
149 | Test: dm_test_spi_xfer | |
150 | SF: Detected M25P16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB | |
65c70539 | 151 | Test: dm_test_uclass |
c910e2e2 | 152 | Test: dm_test_uclass_before_ready |
65c70539 SG |
153 | Failures: 0 |
154 | ||
65c70539 SG |
155 | |
156 | What is going on? | |
157 | ----------------- | |
158 | ||
159 | Let's start at the top. The demo command is in common/cmd_demo.c. It does | |
34e4a2ec | 160 | the usual command processing and then: |
65c70539 | 161 | |
54c5d08a | 162 | struct udevice *demo_dev; |
65c70539 SG |
163 | |
164 | ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev); | |
165 | ||
166 | UCLASS_DEMO means the class of devices which implement 'demo'. Other | |
167 | classes might be MMC, or GPIO, hashing or serial. The idea is that the | |
168 | devices in the class all share a particular way of working. The class | |
169 | presents a unified view of all these devices to U-Boot. | |
170 | ||
171 | This function looks up a device for the demo uclass. Given a device | |
172 | number we can find the device because all devices have registered with | |
173 | the UCLASS_DEMO uclass. | |
174 | ||
175 | The device is automatically activated ready for use by uclass_get_device(). | |
176 | ||
177 | Now that we have the device we can do things like: | |
178 | ||
179 | return demo_hello(demo_dev, ch); | |
180 | ||
181 | This function is in the demo uclass. It takes care of calling the 'hello' | |
182 | method of the relevant driver. Bearing in mind that there are two drivers, | |
183 | this particular device may use one or other of them. | |
184 | ||
185 | The code for demo_hello() is in drivers/demo/demo-uclass.c: | |
186 | ||
54c5d08a | 187 | int demo_hello(struct udevice *dev, int ch) |
65c70539 SG |
188 | { |
189 | const struct demo_ops *ops = device_get_ops(dev); | |
190 | ||
191 | if (!ops->hello) | |
192 | return -ENOSYS; | |
193 | ||
194 | return ops->hello(dev, ch); | |
195 | } | |
196 | ||
197 | As you can see it just calls the relevant driver method. One of these is | |
198 | in drivers/demo/demo-simple.c: | |
199 | ||
54c5d08a | 200 | static int simple_hello(struct udevice *dev, int ch) |
65c70539 SG |
201 | { |
202 | const struct dm_demo_pdata *pdata = dev_get_platdata(dev); | |
203 | ||
204 | printf("Hello from %08x: %s %d\n", map_to_sysmem(dev), | |
205 | pdata->colour, pdata->sides); | |
206 | ||
207 | return 0; | |
208 | } | |
209 | ||
210 | ||
211 | So that is a trip from top (command execution) to bottom (driver action) | |
212 | but it leaves a lot of topics to address. | |
213 | ||
214 | ||
215 | Declaring Drivers | |
216 | ----------------- | |
217 | ||
218 | A driver declaration looks something like this (see | |
219 | drivers/demo/demo-shape.c): | |
220 | ||
221 | static const struct demo_ops shape_ops = { | |
222 | .hello = shape_hello, | |
223 | .status = shape_status, | |
224 | }; | |
225 | ||
226 | U_BOOT_DRIVER(demo_shape_drv) = { | |
227 | .name = "demo_shape_drv", | |
228 | .id = UCLASS_DEMO, | |
229 | .ops = &shape_ops, | |
230 | .priv_data_size = sizeof(struct shape_data), | |
231 | }; | |
232 | ||
233 | ||
234 | This driver has two methods (hello and status) and requires a bit of | |
235 | private data (accessible through dev_get_priv(dev) once the driver has | |
236 | been probed). It is a member of UCLASS_DEMO so will register itself | |
237 | there. | |
238 | ||
239 | In U_BOOT_DRIVER it is also possible to specify special methods for bind | |
240 | and unbind, and these are called at appropriate times. For many drivers | |
241 | it is hoped that only 'probe' and 'remove' will be needed. | |
242 | ||
243 | The U_BOOT_DRIVER macro creates a data structure accessible from C, | |
244 | so driver model can find the drivers that are available. | |
245 | ||
246 | The methods a device can provide are documented in the device.h header. | |
247 | Briefly, they are: | |
248 | ||
249 | bind - make the driver model aware of a device (bind it to its driver) | |
250 | unbind - make the driver model forget the device | |
251 | ofdata_to_platdata - convert device tree data to platdata - see later | |
252 | probe - make a device ready for use | |
253 | remove - remove a device so it cannot be used until probed again | |
254 | ||
255 | The sequence to get a device to work is bind, ofdata_to_platdata (if using | |
256 | device tree) and probe. | |
257 | ||
258 | ||
259 | Platform Data | |
260 | ------------- | |
261 | ||
22ec1363 SG |
262 | Platform data is like Linux platform data, if you are familiar with that. |
263 | It provides the board-specific information to start up a device. | |
264 | ||
265 | Why is this information not just stored in the device driver itself? The | |
266 | idea is that the device driver is generic, and can in principle operate on | |
267 | any board that has that type of device. For example, with modern | |
268 | highly-complex SoCs it is common for the IP to come from an IP vendor, and | |
269 | therefore (for example) the MMC controller may be the same on chips from | |
270 | different vendors. It makes no sense to write independent drivers for the | |
271 | MMC controller on each vendor's SoC, when they are all almost the same. | |
272 | Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same, | |
273 | but lie at different addresses in the address space. | |
274 | ||
275 | Using the UART example, we have a single driver and it is instantiated 6 | |
276 | times by supplying 6 lots of platform data. Each lot of platform data | |
277 | gives the driver name and a pointer to a structure containing information | |
278 | about this instance - e.g. the address of the register space. It may be that | |
279 | one of the UARTS supports RS-485 operation - this can be added as a flag in | |
280 | the platform data, which is set for this one port and clear for the rest. | |
281 | ||
282 | Think of your driver as a generic piece of code which knows how to talk to | |
283 | a device, but needs to know where it is, any variant/option information and | |
284 | so on. Platform data provides this link between the generic piece of code | |
285 | and the specific way it is bound on a particular board. | |
286 | ||
287 | Examples of platform data include: | |
288 | ||
289 | - The base address of the IP block's register space | |
290 | - Configuration options, like: | |
291 | - the SPI polarity and maximum speed for a SPI controller | |
292 | - the I2C speed to use for an I2C device | |
293 | - the number of GPIOs available in a GPIO device | |
294 | ||
295 | Where does the platform data come from? It is either held in a structure | |
296 | which is compiled into U-Boot, or it can be parsed from the Device Tree | |
297 | (see 'Device Tree' below). | |
298 | ||
299 | For an example of how it can be compiled in, see demo-pdata.c which | |
65c70539 SG |
300 | sets up a table of driver names and their associated platform data. |
301 | The data can be interpreted by the drivers however they like - it is | |
302 | basically a communication scheme between the board-specific code and | |
303 | the generic drivers, which are intended to work on any board. | |
304 | ||
34e4a2ec | 305 | Drivers can access their data via dev->info->platdata. Here is |
65c70539 SG |
306 | the declaration for the platform data, which would normally appear |
307 | in the board file. | |
308 | ||
309 | static const struct dm_demo_cdata red_square = { | |
310 | .colour = "red", | |
311 | .sides = 4. | |
312 | }; | |
313 | static const struct driver_info info[] = { | |
314 | { | |
315 | .name = "demo_shape_drv", | |
316 | .platdata = &red_square, | |
317 | }, | |
318 | }; | |
319 | ||
320 | demo1 = driver_bind(root, &info[0]); | |
321 | ||
322 | ||
323 | Device Tree | |
324 | ----------- | |
325 | ||
326 | While platdata is useful, a more flexible way of providing device data is | |
327 | by using device tree. With device tree we replace the above code with the | |
328 | following device tree fragment: | |
329 | ||
330 | red-square { | |
331 | compatible = "demo-shape"; | |
332 | colour = "red"; | |
333 | sides = <4>; | |
334 | }; | |
335 | ||
22ec1363 SG |
336 | This means that instead of having lots of U_BOOT_DEVICE() declarations in |
337 | the board file, we put these in the device tree. This approach allows a lot | |
338 | more generality, since the same board file can support many types of boards | |
339 | (e,g. with the same SoC) just by using different device trees. An added | |
340 | benefit is that the Linux device tree can be used, thus further simplifying | |
341 | the task of board-bring up either for U-Boot or Linux devs (whoever gets to | |
342 | the board first!). | |
65c70539 SG |
343 | |
344 | The easiest way to make this work it to add a few members to the driver: | |
345 | ||
346 | .platdata_auto_alloc_size = sizeof(struct dm_test_pdata), | |
347 | .ofdata_to_platdata = testfdt_ofdata_to_platdata, | |
65c70539 SG |
348 | |
349 | The 'auto_alloc' feature allowed space for the platdata to be allocated | |
22ec1363 SG |
350 | and zeroed before the driver's ofdata_to_platdata() method is called. The |
351 | ofdata_to_platdata() method, which the driver write supplies, should parse | |
352 | the device tree node for this device and place it in dev->platdata. Thus | |
353 | when the probe method is called later (to set up the device ready for use) | |
354 | the platform data will be present. | |
65c70539 SG |
355 | |
356 | Note that both methods are optional. If you provide an ofdata_to_platdata | |
22ec1363 SG |
357 | method then it will be called first (during activation). If you provide a |
358 | probe method it will be called next. See Driver Lifecycle below for more | |
359 | details. | |
65c70539 SG |
360 | |
361 | If you don't want to have the platdata automatically allocated then you | |
362 | can leave out platdata_auto_alloc_size. In this case you can use malloc | |
363 | in your ofdata_to_platdata (or probe) method to allocate the required memory, | |
364 | and you should free it in the remove method. | |
365 | ||
366 | ||
367 | Declaring Uclasses | |
368 | ------------------ | |
369 | ||
370 | The demo uclass is declared like this: | |
371 | ||
372 | U_BOOT_CLASS(demo) = { | |
373 | .id = UCLASS_DEMO, | |
374 | }; | |
375 | ||
376 | It is also possible to specify special methods for probe, etc. The uclass | |
377 | numbering comes from include/dm/uclass.h. To add a new uclass, add to the | |
378 | end of the enum there, then declare your uclass as above. | |
379 | ||
380 | ||
5a66a8ff SG |
381 | Device Sequence Numbers |
382 | ----------------------- | |
383 | ||
384 | U-Boot numbers devices from 0 in many situations, such as in the command | |
385 | line for I2C and SPI buses, and the device names for serial ports (serial0, | |
386 | serial1, ...). Driver model supports this numbering and permits devices | |
547cea19 SG |
387 | to be locating by their 'sequence'. This numbering unique identifies a |
388 | device in its uclass, so no two devices within a particular uclass can have | |
389 | the same sequence number. | |
5a66a8ff SG |
390 | |
391 | Sequence numbers start from 0 but gaps are permitted. For example, a board | |
392 | may have I2C buses 0, 1, 4, 5 but no 2 or 3. The choice of how devices are | |
393 | numbered is up to a particular board, and may be set by the SoC in some | |
394 | cases. While it might be tempting to automatically renumber the devices | |
395 | where there are gaps in the sequence, this can lead to confusion and is | |
396 | not the way that U-Boot works. | |
397 | ||
398 | Each device can request a sequence number. If none is required then the | |
399 | device will be automatically allocated the next available sequence number. | |
400 | ||
401 | To specify the sequence number in the device tree an alias is typically | |
402 | used. | |
403 | ||
404 | aliases { | |
405 | serial2 = "/serial@22230000"; | |
406 | }; | |
407 | ||
408 | This indicates that in the uclass called "serial", the named node | |
409 | ("/serial@22230000") will be given sequence number 2. Any command or driver | |
410 | which requests serial device 2 will obtain this device. | |
411 | ||
412 | Some devices represent buses where the devices on the bus are numbered or | |
413 | addressed. For example, SPI typically numbers its slaves from 0, and I2C | |
414 | uses a 7-bit address. In these cases the 'reg' property of the subnode is | |
415 | used, for example: | |
416 | ||
417 | { | |
418 | aliases { | |
419 | spi2 = "/spi@22300000"; | |
420 | }; | |
421 | ||
422 | spi@22300000 { | |
423 | #address-cells = <1>; | |
424 | #size-cells = <1>; | |
425 | spi-flash@0 { | |
426 | reg = <0>; | |
427 | ... | |
428 | } | |
429 | eeprom@1 { | |
430 | reg = <1>; | |
431 | }; | |
432 | }; | |
433 | ||
434 | In this case we have a SPI bus with two slaves at 0 and 1. The SPI bus | |
435 | itself is numbered 2. So we might access the SPI flash with: | |
436 | ||
437 | sf probe 2:0 | |
438 | ||
439 | and the eeprom with | |
440 | ||
441 | sspi 2:1 32 ef | |
442 | ||
443 | These commands simply need to look up the 2nd device in the SPI uclass to | |
444 | find the right SPI bus. Then, they look at the children of that bus for the | |
445 | right sequence number (0 or 1 in this case). | |
446 | ||
447 | Typically the alias method is used for top-level nodes and the 'reg' method | |
448 | is used only for buses. | |
449 | ||
450 | Device sequence numbers are resolved when a device is probed. Before then | |
451 | the sequence number is only a request which may or may not be honoured, | |
452 | depending on what other devices have been probed. However the numbering is | |
453 | entirely under the control of the board author so a conflict is generally | |
454 | an error. | |
455 | ||
456 | ||
a327dee0 SG |
457 | Bus Drivers |
458 | ----------- | |
459 | ||
460 | A common use of driver model is to implement a bus, a device which provides | |
461 | access to other devices. Example of buses include SPI and I2C. Typically | |
462 | the bus provides some sort of transport or translation that makes it | |
463 | possible to talk to the devices on the bus. | |
464 | ||
465 | Driver model provides a few useful features to help with implementing | |
466 | buses. Firstly, a bus can request that its children store some 'parent | |
467 | data' which can be used to keep track of child state. Secondly, the bus can | |
468 | define methods which are called when a child is probed or removed. This is | |
469 | similar to the methods the uclass driver provides. | |
470 | ||
471 | Here an explanation of how a bus fits with a uclass may be useful. Consider | |
472 | a USB bus with several devices attached to it, each from a different (made | |
473 | up) uclass: | |
474 | ||
475 | xhci_usb (UCLASS_USB) | |
476 | eth (UCLASS_ETHERNET) | |
477 | camera (UCLASS_CAMERA) | |
478 | flash (UCLASS_FLASH_STORAGE) | |
479 | ||
480 | Each of the devices is connected to a different address on the USB bus. | |
481 | The bus device wants to store this address and some other information such | |
482 | as the bus speed for each device. | |
483 | ||
484 | To achieve this, the bus device can use dev->parent_priv in each of its | |
485 | three children. This can be auto-allocated if the bus driver has a non-zero | |
486 | value for per_child_auto_alloc_size. If not, then the bus device can | |
487 | allocate the space itself before the child device is probed. | |
488 | ||
489 | Also the bus driver can define the child_pre_probe() and child_post_remove() | |
490 | methods to allow it to do some processing before the child is activated or | |
491 | after it is deactivated. | |
492 | ||
493 | Note that the information that controls this behaviour is in the bus's | |
494 | driver, not the child's. In fact it is possible that child has no knowledge | |
495 | that it is connected to a bus. The same child device may even be used on two | |
496 | different bus types. As an example. the 'flash' device shown above may also | |
497 | be connected on a SATA bus or standalone with no bus: | |
498 | ||
499 | xhci_usb (UCLASS_USB) | |
500 | flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus | |
501 | ||
502 | sata (UCLASS_SATA) | |
503 | flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by SATA bus | |
504 | ||
505 | flash (UCLASS_FLASH_STORAGE) - no parent data/methods (not on a bus) | |
506 | ||
507 | Above you can see that the driver for xhci_usb/sata controls the child's | |
508 | bus methods. In the third example the device is not on a bus, and therefore | |
509 | will not have these methods at all. Consider the case where the flash | |
510 | device defines child methods. These would be used for *its* children, and | |
511 | would be quite separate from the methods defined by the driver for the bus | |
512 | that the flash device is connetced to. The act of attaching a device to a | |
513 | parent device which is a bus, causes the device to start behaving like a | |
514 | bus device, regardless of its own views on the matter. | |
515 | ||
516 | The uclass for the device can also contain data private to that uclass. | |
517 | But note that each device on the bus may be a memeber of a different | |
518 | uclass, and this data has nothing to do with the child data for each child | |
519 | on the bus. | |
520 | ||
521 | ||
22ec1363 SG |
522 | Driver Lifecycle |
523 | ---------------- | |
524 | ||
525 | Here are the stages that a device goes through in driver model. Note that all | |
526 | methods mentioned here are optional - e.g. if there is no probe() method for | |
527 | a device then it will not be called. A simple device may have very few | |
528 | methods actually defined. | |
529 | ||
530 | 1. Bind stage | |
531 | ||
532 | A device and its driver are bound using one of these two methods: | |
533 | ||
534 | - Scan the U_BOOT_DEVICE() definitions. U-Boot It looks up the | |
535 | name specified by each, to find the appropriate driver. It then calls | |
536 | device_bind() to create a new device and bind' it to its driver. This will | |
537 | call the device's bind() method. | |
538 | ||
539 | - Scan through the device tree definitions. U-Boot looks at top-level | |
540 | nodes in the the device tree. It looks at the compatible string in each node | |
541 | and uses the of_match part of the U_BOOT_DRIVER() structure to find the | |
542 | right driver for each node. It then calls device_bind() to bind the | |
543 | newly-created device to its driver (thereby creating a device structure). | |
544 | This will also call the device's bind() method. | |
545 | ||
546 | At this point all the devices are known, and bound to their drivers. There | |
547 | is a 'struct udevice' allocated for all devices. However, nothing has been | |
548 | activated (except for the root device). Each bound device that was created | |
549 | from a U_BOOT_DEVICE() declaration will hold the platdata pointer specified | |
550 | in that declaration. For a bound device created from the device tree, | |
551 | platdata will be NULL, but of_offset will be the offset of the device tree | |
552 | node that caused the device to be created. The uclass is set correctly for | |
553 | the device. | |
554 | ||
555 | The device's bind() method is permitted to perform simple actions, but | |
556 | should not scan the device tree node, not initialise hardware, nor set up | |
557 | structures or allocate memory. All of these tasks should be left for | |
558 | the probe() method. | |
559 | ||
560 | Note that compared to Linux, U-Boot's driver model has a separate step of | |
561 | probe/remove which is independent of bind/unbind. This is partly because in | |
562 | U-Boot it may be expensive to probe devices and we don't want to do it until | |
563 | they are needed, or perhaps until after relocation. | |
564 | ||
565 | 2. Activation/probe | |
566 | ||
567 | When a device needs to be used, U-Boot activates it, by following these | |
568 | steps (see device_probe()): | |
569 | ||
570 | a. If priv_auto_alloc_size is non-zero, then the device-private space | |
571 | is allocated for the device and zeroed. It will be accessible as | |
572 | dev->priv. The driver can put anything it likes in there, but should use | |
573 | it for run-time information, not platform data (which should be static | |
574 | and known before the device is probed). | |
575 | ||
576 | b. If platdata_auto_alloc_size is non-zero, then the platform data space | |
577 | is allocated. This is only useful for device tree operation, since | |
578 | otherwise you would have to specific the platform data in the | |
579 | U_BOOT_DEVICE() declaration. The space is allocated for the device and | |
580 | zeroed. It will be accessible as dev->platdata. | |
581 | ||
582 | c. If the device's uclass specifies a non-zero per_device_auto_alloc_size, | |
583 | then this space is allocated and zeroed also. It is allocated for and | |
584 | stored in the device, but it is uclass data. owned by the uclass driver. | |
585 | It is possible for the device to access it. | |
586 | ||
e59f458d SG |
587 | d. If the device's immediate parent specifies a per_child_auto_alloc_size |
588 | then this space is allocated. This is intended for use by the parent | |
589 | device to keep track of things related to the child. For example a USB | |
590 | flash stick attached to a USB host controller would likely use this | |
591 | space. The controller can hold information about the USB state of each | |
592 | of its children. | |
593 | ||
594 | e. All parent devices are probed. It is not possible to activate a device | |
22ec1363 SG |
595 | unless its predecessors (all the way up to the root device) are activated. |
596 | This means (for example) that an I2C driver will require that its bus | |
597 | be activated. | |
598 | ||
e59f458d | 599 | f. The device's sequence number is assigned, either the requested one |
5a66a8ff SG |
600 | (assuming no conflicts) or the next available one if there is a conflict |
601 | or nothing particular is requested. | |
602 | ||
e59f458d | 603 | g. If the driver provides an ofdata_to_platdata() method, then this is |
22ec1363 SG |
604 | called to convert the device tree data into platform data. This should |
605 | do various calls like fdtdec_get_int(gd->fdt_blob, dev->of_offset, ...) | |
606 | to access the node and store the resulting information into dev->platdata. | |
607 | After this point, the device works the same way whether it was bound | |
608 | using a device tree node or U_BOOT_DEVICE() structure. In either case, | |
609 | the platform data is now stored in the platdata structure. Typically you | |
610 | will use the platdata_auto_alloc_size feature to specify the size of the | |
611 | platform data structure, and U-Boot will automatically allocate and zero | |
612 | it for you before entry to ofdata_to_platdata(). But if not, you can | |
613 | allocate it yourself in ofdata_to_platdata(). Note that it is preferable | |
614 | to do all the device tree decoding in ofdata_to_platdata() rather than | |
615 | in probe(). (Apart from the ugliness of mixing configuration and run-time | |
616 | data, one day it is possible that U-Boot will cache platformat data for | |
617 | devices which are regularly de/activated). | |
618 | ||
e59f458d | 619 | h. The device's probe() method is called. This should do anything that |
22ec1363 SG |
620 | is required by the device to get it going. This could include checking |
621 | that the hardware is actually present, setting up clocks for the | |
622 | hardware and setting up hardware registers to initial values. The code | |
623 | in probe() can access: | |
624 | ||
625 | - platform data in dev->platdata (for configuration) | |
626 | - private data in dev->priv (for run-time state) | |
627 | - uclass data in dev->uclass_priv (for things the uclass stores | |
628 | about this device) | |
629 | ||
630 | Note: If you don't use priv_auto_alloc_size then you will need to | |
631 | allocate the priv space here yourself. The same applies also to | |
632 | platdata_auto_alloc_size. Remember to free them in the remove() method. | |
633 | ||
e59f458d | 634 | i. The device is marked 'activated' |
22ec1363 | 635 | |
e59f458d | 636 | j. The uclass's post_probe() method is called, if one exists. This may |
22ec1363 SG |
637 | cause the uclass to do some housekeeping to record the device as |
638 | activated and 'known' by the uclass. | |
639 | ||
640 | 3. Running stage | |
641 | ||
642 | The device is now activated and can be used. From now until it is removed | |
643 | all of the above structures are accessible. The device appears in the | |
644 | uclass's list of devices (so if the device is in UCLASS_GPIO it will appear | |
645 | as a device in the GPIO uclass). This is the 'running' state of the device. | |
646 | ||
647 | 4. Removal stage | |
648 | ||
649 | When the device is no-longer required, you can call device_remove() to | |
650 | remove it. This performs the probe steps in reverse: | |
651 | ||
652 | a. The uclass's pre_remove() method is called, if one exists. This may | |
653 | cause the uclass to do some housekeeping to record the device as | |
654 | deactivated and no-longer 'known' by the uclass. | |
655 | ||
656 | b. All the device's children are removed. It is not permitted to have | |
657 | an active child device with a non-active parent. This means that | |
658 | device_remove() is called for all the children recursively at this point. | |
659 | ||
660 | c. The device's remove() method is called. At this stage nothing has been | |
661 | deallocated so platform data, private data and the uclass data will all | |
662 | still be present. This is where the hardware can be shut down. It is | |
663 | intended that the device be completely inactive at this point, For U-Boot | |
664 | to be sure that no hardware is running, it should be enough to remove | |
665 | all devices. | |
666 | ||
e59f458d SG |
667 | d. The device memory is freed (platform data, private data, uclass data, |
668 | parent data). | |
22ec1363 SG |
669 | |
670 | Note: Because the platform data for a U_BOOT_DEVICE() is defined with a | |
671 | static pointer, it is not de-allocated during the remove() method. For | |
672 | a device instantiated using the device tree data, the platform data will | |
673 | be dynamically allocated, and thus needs to be deallocated during the | |
674 | remove() method, either: | |
675 | ||
676 | 1. if the platdata_auto_alloc_size is non-zero, the deallocation | |
677 | happens automatically within the driver model core; or | |
678 | ||
679 | 2. when platdata_auto_alloc_size is 0, both the allocation (in probe() | |
680 | or preferably ofdata_to_platdata()) and the deallocation in remove() | |
681 | are the responsibility of the driver author. | |
682 | ||
5a66a8ff SG |
683 | e. The device sequence number is set to -1, meaning that it no longer |
684 | has an allocated sequence. If the device is later reactivated and that | |
685 | sequence number is still free, it may well receive the name sequence | |
686 | number again. But from this point, the sequence number previously used | |
687 | by this device will no longer exist (think of SPI bus 2 being removed | |
688 | and bus 2 is no longer available for use). | |
689 | ||
690 | f. The device is marked inactive. Note that it is still bound, so the | |
22ec1363 SG |
691 | device structure itself is not freed at this point. Should the device be |
692 | activated again, then the cycle starts again at step 2 above. | |
693 | ||
694 | 5. Unbind stage | |
695 | ||
696 | The device is unbound. This is the step that actually destroys the device. | |
697 | If a parent has children these will be destroyed first. After this point | |
698 | the device does not exist and its memory has be deallocated. | |
699 | ||
700 | ||
65c70539 SG |
701 | Data Structures |
702 | --------------- | |
703 | ||
704 | Driver model uses a doubly-linked list as the basic data structure. Some | |
705 | nodes have several lists running through them. Creating a more efficient | |
706 | data structure might be worthwhile in some rare cases, once we understand | |
707 | what the bottlenecks are. | |
708 | ||
709 | ||
710 | Changes since v1 | |
711 | ---------------- | |
712 | ||
713 | For the record, this implementation uses a very similar approach to the | |
714 | original patches, but makes at least the following changes: | |
715 | ||
34e4a2ec | 716 | - Tried to aggressively remove boilerplate, so that for most drivers there |
65c70539 SG |
717 | is little or no 'driver model' code to write. |
718 | - Moved some data from code into data structure - e.g. store a pointer to | |
719 | the driver operations structure in the driver, rather than passing it | |
720 | to the driver bind function. | |
ae7f4513 | 721 | - Rename some structures to make them more similar to Linux (struct udevice |
65c70539 SG |
722 | instead of struct instance, struct platdata, etc.) |
723 | - Change the name 'core' to 'uclass', meaning U-Boot class. It seems that | |
724 | this concept relates to a class of drivers (or a subsystem). We shouldn't | |
725 | use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems | |
726 | better than 'core'. | |
54c5d08a | 727 | - Remove 'struct driver_instance' and just use a single 'struct udevice'. |
65c70539 SG |
728 | This removes a level of indirection that doesn't seem necessary. |
729 | - Built in device tree support, to avoid the need for platdata | |
730 | - Removed the concept of driver relocation, and just make it possible for | |
731 | the new driver (created after relocation) to access the old driver data. | |
732 | I feel that relocation is a very special case and will only apply to a few | |
733 | drivers, many of which can/will just re-init anyway. So the overhead of | |
734 | dealing with this might not be worth it. | |
735 | - Implemented a GPIO system, trying to keep it simple | |
736 | ||
737 | ||
00606d7e SG |
738 | Pre-Relocation Support |
739 | ---------------------- | |
740 | ||
741 | For pre-relocation we simply call the driver model init function. Only | |
742 | drivers marked with DM_FLAG_PRE_RELOC or the device tree | |
743 | 'u-boot,dm-pre-reloc' flag are initialised prior to relocation. This helps | |
744 | to reduce the driver model overhead. | |
745 | ||
746 | Then post relocation we throw that away and re-init driver model again. | |
747 | For drivers which require some sort of continuity between pre- and | |
748 | post-relocation devices, we can provide access to the pre-relocation | |
749 | device pointers, but this is not currently implemented (the root device | |
750 | pointer is saved but not made available through the driver model API). | |
751 | ||
752 | ||
38687ae6 SG |
753 | SPL Support |
754 | ----------- | |
755 | ||
756 | Driver model can operate in SPL. Its efficient implementation and small code | |
757 | size provide for a small overhead which is acceptable for all but the most | |
758 | constrained systems. | |
759 | ||
760 | To enable driver model in SPL, define CONFIG_SPL_DM. You might want to | |
761 | consider the following option also. See the main README for more details. | |
762 | ||
763 | - CONFIG_SYS_MALLOC_SIMPLE | |
764 | - CONFIG_DM_WARN | |
765 | - CONFIG_DM_DEVICE_REMOVE | |
766 | - CONFIG_DM_STDIO | |
65c70539 | 767 | |
65c70539 | 768 | |
38687ae6 SG |
769 | Enabling Driver Model |
770 | --------------------- | |
65c70539 | 771 | |
38687ae6 SG |
772 | Driver model is being brought into U-Boot gradually. As each subsystems gets |
773 | support, a uclass is created and a CONFIG to enable use of driver model for | |
774 | that subsystem. | |
775 | ||
776 | For example CONFIG_DM_SERIAL enables driver model for serial. With that | |
777 | defined, the old serial support is not enabled, and your serial driver must | |
778 | conform to driver model. With that undefined, the old serial support is | |
779 | enabled and driver model is not available for serial. This means that when | |
780 | you convert a driver, you must either convert all its boards, or provide for | |
781 | the driver to be compiled both with and without driver model (generally this | |
782 | is not very hard). | |
783 | ||
784 | See the main README for full details of the available driver model CONFIG | |
785 | options. | |
786 | ||
787 | ||
788 | Things to punt for later | |
789 | ------------------------ | |
65c70539 | 790 | |
65c70539 SG |
791 | Uclasses are statically numbered at compile time. It would be possible to |
792 | change this to dynamic numbering, but then we would require some sort of | |
793 | lookup service, perhaps searching by name. This is slightly less efficient | |
794 | so has been left out for now. One small advantage of dynamic numbering might | |
795 | be fewer merge conflicts in uclass-id.h. | |
796 | ||
797 | ||
798 | Simon Glass | |
799 | sjg@chromium.org | |
800 | April 2013 | |
801 | Updated 7-May-13 | |
802 | Updated 14-Jun-13 | |
803 | Updated 18-Oct-13 | |
804 | Updated 5-Nov-13 |