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