]>
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...> | |
e59f458d | 98 | Running 20 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 |
e59f458d | 106 | Test: dm_test_bus_parent_data |
65c70539 SG |
107 | Test: dm_test_children |
108 | Test: dm_test_fdt | |
5a66a8ff | 109 | Device 'd-test': seq 3 is in use by 'b-test' |
f4cdead2 | 110 | Test: dm_test_fdt_offset |
00606d7e | 111 | Test: dm_test_fdt_pre_reloc |
5a66a8ff SG |
112 | Test: dm_test_fdt_uclass_seq |
113 | Device 'd-test': seq 3 is in use by 'b-test' | |
114 | Device 'a-test': seq 0 is in use by 'd-test' | |
65c70539 SG |
115 | Test: dm_test_gpio |
116 | sandbox_gpio: sb_gpio_get_value: error: offset 4 not reserved | |
117 | Test: dm_test_leak | |
65c70539 SG |
118 | Test: dm_test_lifecycle |
119 | Test: dm_test_operations | |
120 | Test: dm_test_ordering | |
121 | Test: dm_test_platdata | |
00606d7e | 122 | Test: dm_test_pre_reloc |
65c70539 SG |
123 | Test: dm_test_remove |
124 | Test: dm_test_uclass | |
c910e2e2 | 125 | Test: dm_test_uclass_before_ready |
65c70539 SG |
126 | Failures: 0 |
127 | ||
65c70539 SG |
128 | |
129 | What is going on? | |
130 | ----------------- | |
131 | ||
132 | Let's start at the top. The demo command is in common/cmd_demo.c. It does | |
34e4a2ec | 133 | the usual command processing and then: |
65c70539 | 134 | |
54c5d08a | 135 | struct udevice *demo_dev; |
65c70539 SG |
136 | |
137 | ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev); | |
138 | ||
139 | UCLASS_DEMO means the class of devices which implement 'demo'. Other | |
140 | classes might be MMC, or GPIO, hashing or serial. The idea is that the | |
141 | devices in the class all share a particular way of working. The class | |
142 | presents a unified view of all these devices to U-Boot. | |
143 | ||
144 | This function looks up a device for the demo uclass. Given a device | |
145 | number we can find the device because all devices have registered with | |
146 | the UCLASS_DEMO uclass. | |
147 | ||
148 | The device is automatically activated ready for use by uclass_get_device(). | |
149 | ||
150 | Now that we have the device we can do things like: | |
151 | ||
152 | return demo_hello(demo_dev, ch); | |
153 | ||
154 | This function is in the demo uclass. It takes care of calling the 'hello' | |
155 | method of the relevant driver. Bearing in mind that there are two drivers, | |
156 | this particular device may use one or other of them. | |
157 | ||
158 | The code for demo_hello() is in drivers/demo/demo-uclass.c: | |
159 | ||
54c5d08a | 160 | int demo_hello(struct udevice *dev, int ch) |
65c70539 SG |
161 | { |
162 | const struct demo_ops *ops = device_get_ops(dev); | |
163 | ||
164 | if (!ops->hello) | |
165 | return -ENOSYS; | |
166 | ||
167 | return ops->hello(dev, ch); | |
168 | } | |
169 | ||
170 | As you can see it just calls the relevant driver method. One of these is | |
171 | in drivers/demo/demo-simple.c: | |
172 | ||
54c5d08a | 173 | static int simple_hello(struct udevice *dev, int ch) |
65c70539 SG |
174 | { |
175 | const struct dm_demo_pdata *pdata = dev_get_platdata(dev); | |
176 | ||
177 | printf("Hello from %08x: %s %d\n", map_to_sysmem(dev), | |
178 | pdata->colour, pdata->sides); | |
179 | ||
180 | return 0; | |
181 | } | |
182 | ||
183 | ||
184 | So that is a trip from top (command execution) to bottom (driver action) | |
185 | but it leaves a lot of topics to address. | |
186 | ||
187 | ||
188 | Declaring Drivers | |
189 | ----------------- | |
190 | ||
191 | A driver declaration looks something like this (see | |
192 | drivers/demo/demo-shape.c): | |
193 | ||
194 | static const struct demo_ops shape_ops = { | |
195 | .hello = shape_hello, | |
196 | .status = shape_status, | |
197 | }; | |
198 | ||
199 | U_BOOT_DRIVER(demo_shape_drv) = { | |
200 | .name = "demo_shape_drv", | |
201 | .id = UCLASS_DEMO, | |
202 | .ops = &shape_ops, | |
203 | .priv_data_size = sizeof(struct shape_data), | |
204 | }; | |
205 | ||
206 | ||
207 | This driver has two methods (hello and status) and requires a bit of | |
208 | private data (accessible through dev_get_priv(dev) once the driver has | |
209 | been probed). It is a member of UCLASS_DEMO so will register itself | |
210 | there. | |
211 | ||
212 | In U_BOOT_DRIVER it is also possible to specify special methods for bind | |
213 | and unbind, and these are called at appropriate times. For many drivers | |
214 | it is hoped that only 'probe' and 'remove' will be needed. | |
215 | ||
216 | The U_BOOT_DRIVER macro creates a data structure accessible from C, | |
217 | so driver model can find the drivers that are available. | |
218 | ||
219 | The methods a device can provide are documented in the device.h header. | |
220 | Briefly, they are: | |
221 | ||
222 | bind - make the driver model aware of a device (bind it to its driver) | |
223 | unbind - make the driver model forget the device | |
224 | ofdata_to_platdata - convert device tree data to platdata - see later | |
225 | probe - make a device ready for use | |
226 | remove - remove a device so it cannot be used until probed again | |
227 | ||
228 | The sequence to get a device to work is bind, ofdata_to_platdata (if using | |
229 | device tree) and probe. | |
230 | ||
231 | ||
232 | Platform Data | |
233 | ------------- | |
234 | ||
22ec1363 SG |
235 | Platform data is like Linux platform data, if you are familiar with that. |
236 | It provides the board-specific information to start up a device. | |
237 | ||
238 | Why is this information not just stored in the device driver itself? The | |
239 | idea is that the device driver is generic, and can in principle operate on | |
240 | any board that has that type of device. For example, with modern | |
241 | highly-complex SoCs it is common for the IP to come from an IP vendor, and | |
242 | therefore (for example) the MMC controller may be the same on chips from | |
243 | different vendors. It makes no sense to write independent drivers for the | |
244 | MMC controller on each vendor's SoC, when they are all almost the same. | |
245 | Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same, | |
246 | but lie at different addresses in the address space. | |
247 | ||
248 | Using the UART example, we have a single driver and it is instantiated 6 | |
249 | times by supplying 6 lots of platform data. Each lot of platform data | |
250 | gives the driver name and a pointer to a structure containing information | |
251 | about this instance - e.g. the address of the register space. It may be that | |
252 | one of the UARTS supports RS-485 operation - this can be added as a flag in | |
253 | the platform data, which is set for this one port and clear for the rest. | |
254 | ||
255 | Think of your driver as a generic piece of code which knows how to talk to | |
256 | a device, but needs to know where it is, any variant/option information and | |
257 | so on. Platform data provides this link between the generic piece of code | |
258 | and the specific way it is bound on a particular board. | |
259 | ||
260 | Examples of platform data include: | |
261 | ||
262 | - The base address of the IP block's register space | |
263 | - Configuration options, like: | |
264 | - the SPI polarity and maximum speed for a SPI controller | |
265 | - the I2C speed to use for an I2C device | |
266 | - the number of GPIOs available in a GPIO device | |
267 | ||
268 | Where does the platform data come from? It is either held in a structure | |
269 | which is compiled into U-Boot, or it can be parsed from the Device Tree | |
270 | (see 'Device Tree' below). | |
271 | ||
272 | For an example of how it can be compiled in, see demo-pdata.c which | |
65c70539 SG |
273 | sets up a table of driver names and their associated platform data. |
274 | The data can be interpreted by the drivers however they like - it is | |
275 | basically a communication scheme between the board-specific code and | |
276 | the generic drivers, which are intended to work on any board. | |
277 | ||
34e4a2ec | 278 | Drivers can access their data via dev->info->platdata. Here is |
65c70539 SG |
279 | the declaration for the platform data, which would normally appear |
280 | in the board file. | |
281 | ||
282 | static const struct dm_demo_cdata red_square = { | |
283 | .colour = "red", | |
284 | .sides = 4. | |
285 | }; | |
286 | static const struct driver_info info[] = { | |
287 | { | |
288 | .name = "demo_shape_drv", | |
289 | .platdata = &red_square, | |
290 | }, | |
291 | }; | |
292 | ||
293 | demo1 = driver_bind(root, &info[0]); | |
294 | ||
295 | ||
296 | Device Tree | |
297 | ----------- | |
298 | ||
299 | While platdata is useful, a more flexible way of providing device data is | |
300 | by using device tree. With device tree we replace the above code with the | |
301 | following device tree fragment: | |
302 | ||
303 | red-square { | |
304 | compatible = "demo-shape"; | |
305 | colour = "red"; | |
306 | sides = <4>; | |
307 | }; | |
308 | ||
22ec1363 SG |
309 | This means that instead of having lots of U_BOOT_DEVICE() declarations in |
310 | the board file, we put these in the device tree. This approach allows a lot | |
311 | more generality, since the same board file can support many types of boards | |
312 | (e,g. with the same SoC) just by using different device trees. An added | |
313 | benefit is that the Linux device tree can be used, thus further simplifying | |
314 | the task of board-bring up either for U-Boot or Linux devs (whoever gets to | |
315 | the board first!). | |
65c70539 SG |
316 | |
317 | The easiest way to make this work it to add a few members to the driver: | |
318 | ||
319 | .platdata_auto_alloc_size = sizeof(struct dm_test_pdata), | |
320 | .ofdata_to_platdata = testfdt_ofdata_to_platdata, | |
65c70539 SG |
321 | |
322 | The 'auto_alloc' feature allowed space for the platdata to be allocated | |
22ec1363 SG |
323 | and zeroed before the driver's ofdata_to_platdata() method is called. The |
324 | ofdata_to_platdata() method, which the driver write supplies, should parse | |
325 | the device tree node for this device and place it in dev->platdata. Thus | |
326 | when the probe method is called later (to set up the device ready for use) | |
327 | the platform data will be present. | |
65c70539 SG |
328 | |
329 | Note that both methods are optional. If you provide an ofdata_to_platdata | |
22ec1363 SG |
330 | method then it will be called first (during activation). If you provide a |
331 | probe method it will be called next. See Driver Lifecycle below for more | |
332 | details. | |
65c70539 SG |
333 | |
334 | If you don't want to have the platdata automatically allocated then you | |
335 | can leave out platdata_auto_alloc_size. In this case you can use malloc | |
336 | in your ofdata_to_platdata (or probe) method to allocate the required memory, | |
337 | and you should free it in the remove method. | |
338 | ||
339 | ||
340 | Declaring Uclasses | |
341 | ------------------ | |
342 | ||
343 | The demo uclass is declared like this: | |
344 | ||
345 | U_BOOT_CLASS(demo) = { | |
346 | .id = UCLASS_DEMO, | |
347 | }; | |
348 | ||
349 | It is also possible to specify special methods for probe, etc. The uclass | |
350 | numbering comes from include/dm/uclass.h. To add a new uclass, add to the | |
351 | end of the enum there, then declare your uclass as above. | |
352 | ||
353 | ||
5a66a8ff SG |
354 | Device Sequence Numbers |
355 | ----------------------- | |
356 | ||
357 | U-Boot numbers devices from 0 in many situations, such as in the command | |
358 | line for I2C and SPI buses, and the device names for serial ports (serial0, | |
359 | serial1, ...). Driver model supports this numbering and permits devices | |
360 | to be locating by their 'sequence'. | |
361 | ||
362 | Sequence numbers start from 0 but gaps are permitted. For example, a board | |
363 | may have I2C buses 0, 1, 4, 5 but no 2 or 3. The choice of how devices are | |
364 | numbered is up to a particular board, and may be set by the SoC in some | |
365 | cases. While it might be tempting to automatically renumber the devices | |
366 | where there are gaps in the sequence, this can lead to confusion and is | |
367 | not the way that U-Boot works. | |
368 | ||
369 | Each device can request a sequence number. If none is required then the | |
370 | device will be automatically allocated the next available sequence number. | |
371 | ||
372 | To specify the sequence number in the device tree an alias is typically | |
373 | used. | |
374 | ||
375 | aliases { | |
376 | serial2 = "/serial@22230000"; | |
377 | }; | |
378 | ||
379 | This indicates that in the uclass called "serial", the named node | |
380 | ("/serial@22230000") will be given sequence number 2. Any command or driver | |
381 | which requests serial device 2 will obtain this device. | |
382 | ||
383 | Some devices represent buses where the devices on the bus are numbered or | |
384 | addressed. For example, SPI typically numbers its slaves from 0, and I2C | |
385 | uses a 7-bit address. In these cases the 'reg' property of the subnode is | |
386 | used, for example: | |
387 | ||
388 | { | |
389 | aliases { | |
390 | spi2 = "/spi@22300000"; | |
391 | }; | |
392 | ||
393 | spi@22300000 { | |
394 | #address-cells = <1>; | |
395 | #size-cells = <1>; | |
396 | spi-flash@0 { | |
397 | reg = <0>; | |
398 | ... | |
399 | } | |
400 | eeprom@1 { | |
401 | reg = <1>; | |
402 | }; | |
403 | }; | |
404 | ||
405 | In this case we have a SPI bus with two slaves at 0 and 1. The SPI bus | |
406 | itself is numbered 2. So we might access the SPI flash with: | |
407 | ||
408 | sf probe 2:0 | |
409 | ||
410 | and the eeprom with | |
411 | ||
412 | sspi 2:1 32 ef | |
413 | ||
414 | These commands simply need to look up the 2nd device in the SPI uclass to | |
415 | find the right SPI bus. Then, they look at the children of that bus for the | |
416 | right sequence number (0 or 1 in this case). | |
417 | ||
418 | Typically the alias method is used for top-level nodes and the 'reg' method | |
419 | is used only for buses. | |
420 | ||
421 | Device sequence numbers are resolved when a device is probed. Before then | |
422 | the sequence number is only a request which may or may not be honoured, | |
423 | depending on what other devices have been probed. However the numbering is | |
424 | entirely under the control of the board author so a conflict is generally | |
425 | an error. | |
426 | ||
427 | ||
22ec1363 SG |
428 | Driver Lifecycle |
429 | ---------------- | |
430 | ||
431 | Here are the stages that a device goes through in driver model. Note that all | |
432 | methods mentioned here are optional - e.g. if there is no probe() method for | |
433 | a device then it will not be called. A simple device may have very few | |
434 | methods actually defined. | |
435 | ||
436 | 1. Bind stage | |
437 | ||
438 | A device and its driver are bound using one of these two methods: | |
439 | ||
440 | - Scan the U_BOOT_DEVICE() definitions. U-Boot It looks up the | |
441 | name specified by each, to find the appropriate driver. It then calls | |
442 | device_bind() to create a new device and bind' it to its driver. This will | |
443 | call the device's bind() method. | |
444 | ||
445 | - Scan through the device tree definitions. U-Boot looks at top-level | |
446 | nodes in the the device tree. It looks at the compatible string in each node | |
447 | and uses the of_match part of the U_BOOT_DRIVER() structure to find the | |
448 | right driver for each node. It then calls device_bind() to bind the | |
449 | newly-created device to its driver (thereby creating a device structure). | |
450 | This will also call the device's bind() method. | |
451 | ||
452 | At this point all the devices are known, and bound to their drivers. There | |
453 | is a 'struct udevice' allocated for all devices. However, nothing has been | |
454 | activated (except for the root device). Each bound device that was created | |
455 | from a U_BOOT_DEVICE() declaration will hold the platdata pointer specified | |
456 | in that declaration. For a bound device created from the device tree, | |
457 | platdata will be NULL, but of_offset will be the offset of the device tree | |
458 | node that caused the device to be created. The uclass is set correctly for | |
459 | the device. | |
460 | ||
461 | The device's bind() method is permitted to perform simple actions, but | |
462 | should not scan the device tree node, not initialise hardware, nor set up | |
463 | structures or allocate memory. All of these tasks should be left for | |
464 | the probe() method. | |
465 | ||
466 | Note that compared to Linux, U-Boot's driver model has a separate step of | |
467 | probe/remove which is independent of bind/unbind. This is partly because in | |
468 | U-Boot it may be expensive to probe devices and we don't want to do it until | |
469 | they are needed, or perhaps until after relocation. | |
470 | ||
471 | 2. Activation/probe | |
472 | ||
473 | When a device needs to be used, U-Boot activates it, by following these | |
474 | steps (see device_probe()): | |
475 | ||
476 | a. If priv_auto_alloc_size is non-zero, then the device-private space | |
477 | is allocated for the device and zeroed. It will be accessible as | |
478 | dev->priv. The driver can put anything it likes in there, but should use | |
479 | it for run-time information, not platform data (which should be static | |
480 | and known before the device is probed). | |
481 | ||
482 | b. If platdata_auto_alloc_size is non-zero, then the platform data space | |
483 | is allocated. This is only useful for device tree operation, since | |
484 | otherwise you would have to specific the platform data in the | |
485 | U_BOOT_DEVICE() declaration. The space is allocated for the device and | |
486 | zeroed. It will be accessible as dev->platdata. | |
487 | ||
488 | c. If the device's uclass specifies a non-zero per_device_auto_alloc_size, | |
489 | then this space is allocated and zeroed also. It is allocated for and | |
490 | stored in the device, but it is uclass data. owned by the uclass driver. | |
491 | It is possible for the device to access it. | |
492 | ||
e59f458d SG |
493 | d. If the device's immediate parent specifies a per_child_auto_alloc_size |
494 | then this space is allocated. This is intended for use by the parent | |
495 | device to keep track of things related to the child. For example a USB | |
496 | flash stick attached to a USB host controller would likely use this | |
497 | space. The controller can hold information about the USB state of each | |
498 | of its children. | |
499 | ||
500 | e. All parent devices are probed. It is not possible to activate a device | |
22ec1363 SG |
501 | unless its predecessors (all the way up to the root device) are activated. |
502 | This means (for example) that an I2C driver will require that its bus | |
503 | be activated. | |
504 | ||
e59f458d | 505 | f. The device's sequence number is assigned, either the requested one |
5a66a8ff SG |
506 | (assuming no conflicts) or the next available one if there is a conflict |
507 | or nothing particular is requested. | |
508 | ||
e59f458d | 509 | g. If the driver provides an ofdata_to_platdata() method, then this is |
22ec1363 SG |
510 | called to convert the device tree data into platform data. This should |
511 | do various calls like fdtdec_get_int(gd->fdt_blob, dev->of_offset, ...) | |
512 | to access the node and store the resulting information into dev->platdata. | |
513 | After this point, the device works the same way whether it was bound | |
514 | using a device tree node or U_BOOT_DEVICE() structure. In either case, | |
515 | the platform data is now stored in the platdata structure. Typically you | |
516 | will use the platdata_auto_alloc_size feature to specify the size of the | |
517 | platform data structure, and U-Boot will automatically allocate and zero | |
518 | it for you before entry to ofdata_to_platdata(). But if not, you can | |
519 | allocate it yourself in ofdata_to_platdata(). Note that it is preferable | |
520 | to do all the device tree decoding in ofdata_to_platdata() rather than | |
521 | in probe(). (Apart from the ugliness of mixing configuration and run-time | |
522 | data, one day it is possible that U-Boot will cache platformat data for | |
523 | devices which are regularly de/activated). | |
524 | ||
e59f458d | 525 | h. The device's probe() method is called. This should do anything that |
22ec1363 SG |
526 | is required by the device to get it going. This could include checking |
527 | that the hardware is actually present, setting up clocks for the | |
528 | hardware and setting up hardware registers to initial values. The code | |
529 | in probe() can access: | |
530 | ||
531 | - platform data in dev->platdata (for configuration) | |
532 | - private data in dev->priv (for run-time state) | |
533 | - uclass data in dev->uclass_priv (for things the uclass stores | |
534 | about this device) | |
535 | ||
536 | Note: If you don't use priv_auto_alloc_size then you will need to | |
537 | allocate the priv space here yourself. The same applies also to | |
538 | platdata_auto_alloc_size. Remember to free them in the remove() method. | |
539 | ||
e59f458d | 540 | i. The device is marked 'activated' |
22ec1363 | 541 | |
e59f458d | 542 | j. The uclass's post_probe() method is called, if one exists. This may |
22ec1363 SG |
543 | cause the uclass to do some housekeeping to record the device as |
544 | activated and 'known' by the uclass. | |
545 | ||
546 | 3. Running stage | |
547 | ||
548 | The device is now activated and can be used. From now until it is removed | |
549 | all of the above structures are accessible. The device appears in the | |
550 | uclass's list of devices (so if the device is in UCLASS_GPIO it will appear | |
551 | as a device in the GPIO uclass). This is the 'running' state of the device. | |
552 | ||
553 | 4. Removal stage | |
554 | ||
555 | When the device is no-longer required, you can call device_remove() to | |
556 | remove it. This performs the probe steps in reverse: | |
557 | ||
558 | a. The uclass's pre_remove() method is called, if one exists. This may | |
559 | cause the uclass to do some housekeeping to record the device as | |
560 | deactivated and no-longer 'known' by the uclass. | |
561 | ||
562 | b. All the device's children are removed. It is not permitted to have | |
563 | an active child device with a non-active parent. This means that | |
564 | device_remove() is called for all the children recursively at this point. | |
565 | ||
566 | c. The device's remove() method is called. At this stage nothing has been | |
567 | deallocated so platform data, private data and the uclass data will all | |
568 | still be present. This is where the hardware can be shut down. It is | |
569 | intended that the device be completely inactive at this point, For U-Boot | |
570 | to be sure that no hardware is running, it should be enough to remove | |
571 | all devices. | |
572 | ||
e59f458d SG |
573 | d. The device memory is freed (platform data, private data, uclass data, |
574 | parent data). | |
22ec1363 SG |
575 | |
576 | Note: Because the platform data for a U_BOOT_DEVICE() is defined with a | |
577 | static pointer, it is not de-allocated during the remove() method. For | |
578 | a device instantiated using the device tree data, the platform data will | |
579 | be dynamically allocated, and thus needs to be deallocated during the | |
580 | remove() method, either: | |
581 | ||
582 | 1. if the platdata_auto_alloc_size is non-zero, the deallocation | |
583 | happens automatically within the driver model core; or | |
584 | ||
585 | 2. when platdata_auto_alloc_size is 0, both the allocation (in probe() | |
586 | or preferably ofdata_to_platdata()) and the deallocation in remove() | |
587 | are the responsibility of the driver author. | |
588 | ||
5a66a8ff SG |
589 | e. The device sequence number is set to -1, meaning that it no longer |
590 | has an allocated sequence. If the device is later reactivated and that | |
591 | sequence number is still free, it may well receive the name sequence | |
592 | number again. But from this point, the sequence number previously used | |
593 | by this device will no longer exist (think of SPI bus 2 being removed | |
594 | and bus 2 is no longer available for use). | |
595 | ||
596 | f. The device is marked inactive. Note that it is still bound, so the | |
22ec1363 SG |
597 | device structure itself is not freed at this point. Should the device be |
598 | activated again, then the cycle starts again at step 2 above. | |
599 | ||
600 | 5. Unbind stage | |
601 | ||
602 | The device is unbound. This is the step that actually destroys the device. | |
603 | If a parent has children these will be destroyed first. After this point | |
604 | the device does not exist and its memory has be deallocated. | |
605 | ||
606 | ||
65c70539 SG |
607 | Data Structures |
608 | --------------- | |
609 | ||
610 | Driver model uses a doubly-linked list as the basic data structure. Some | |
611 | nodes have several lists running through them. Creating a more efficient | |
612 | data structure might be worthwhile in some rare cases, once we understand | |
613 | what the bottlenecks are. | |
614 | ||
615 | ||
616 | Changes since v1 | |
617 | ---------------- | |
618 | ||
619 | For the record, this implementation uses a very similar approach to the | |
620 | original patches, but makes at least the following changes: | |
621 | ||
34e4a2ec | 622 | - Tried to aggressively remove boilerplate, so that for most drivers there |
65c70539 SG |
623 | is little or no 'driver model' code to write. |
624 | - Moved some data from code into data structure - e.g. store a pointer to | |
625 | the driver operations structure in the driver, rather than passing it | |
626 | to the driver bind function. | |
ae7f4513 | 627 | - Rename some structures to make them more similar to Linux (struct udevice |
65c70539 SG |
628 | instead of struct instance, struct platdata, etc.) |
629 | - Change the name 'core' to 'uclass', meaning U-Boot class. It seems that | |
630 | this concept relates to a class of drivers (or a subsystem). We shouldn't | |
631 | use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems | |
632 | better than 'core'. | |
54c5d08a | 633 | - Remove 'struct driver_instance' and just use a single 'struct udevice'. |
65c70539 SG |
634 | This removes a level of indirection that doesn't seem necessary. |
635 | - Built in device tree support, to avoid the need for platdata | |
636 | - Removed the concept of driver relocation, and just make it possible for | |
637 | the new driver (created after relocation) to access the old driver data. | |
638 | I feel that relocation is a very special case and will only apply to a few | |
639 | drivers, many of which can/will just re-init anyway. So the overhead of | |
640 | dealing with this might not be worth it. | |
641 | - Implemented a GPIO system, trying to keep it simple | |
642 | ||
643 | ||
00606d7e SG |
644 | Pre-Relocation Support |
645 | ---------------------- | |
646 | ||
647 | For pre-relocation we simply call the driver model init function. Only | |
648 | drivers marked with DM_FLAG_PRE_RELOC or the device tree | |
649 | 'u-boot,dm-pre-reloc' flag are initialised prior to relocation. This helps | |
650 | to reduce the driver model overhead. | |
651 | ||
652 | Then post relocation we throw that away and re-init driver model again. | |
653 | For drivers which require some sort of continuity between pre- and | |
654 | post-relocation devices, we can provide access to the pre-relocation | |
655 | device pointers, but this is not currently implemented (the root device | |
656 | pointer is saved but not made available through the driver model API). | |
657 | ||
658 | ||
65c70539 SG |
659 | Things to punt for later |
660 | ------------------------ | |
661 | ||
662 | - SPL support - this will have to be present before many drivers can be | |
663 | converted, but it seems like we can add it once we are happy with the | |
664 | core implementation. | |
65c70539 | 665 | |
00606d7e | 666 | That is not to say that no thinking has gone into this - in fact there |
65c70539 SG |
667 | is quite a lot there. However, getting these right is non-trivial and |
668 | there is a high cost associated with going down the wrong path. | |
669 | ||
670 | For SPL, it may be possible to fit in a simplified driver model with only | |
671 | bind and probe methods, to reduce size. | |
672 | ||
65c70539 SG |
673 | Uclasses are statically numbered at compile time. It would be possible to |
674 | change this to dynamic numbering, but then we would require some sort of | |
675 | lookup service, perhaps searching by name. This is slightly less efficient | |
676 | so has been left out for now. One small advantage of dynamic numbering might | |
677 | be fewer merge conflicts in uclass-id.h. | |
678 | ||
679 | ||
680 | Simon Glass | |
681 | sjg@chromium.org | |
682 | April 2013 | |
683 | Updated 7-May-13 | |
684 | Updated 14-Jun-13 | |
685 | Updated 18-Oct-13 | |
686 | Updated 5-Nov-13 |