Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 |
Chris Packham | 34e4a2e | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 23 | a way of accessing individual devices within the group, but always |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Masahiro Yamada | 33fcd1b | 2014-12-19 14:16:44 +0900 | [diff] [blame] | 39 | make sandbox_defconfig |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 40 | make |
Masahiro Yamada | 33fcd1b | 2014-12-19 14:16:44 +0900 | [diff] [blame] | 41 | ./u-boot -d u-boot.dtb |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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...> |
Simon Glass | 4324174 | 2014-10-04 11:29:51 -0600 | [diff] [blame] | 98 | Running 29 driver model tests |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 99 | Test: dm_test_autobind |
| 100 | Test: dm_test_autoprobe |
Simon Glass | 1ca7e20 | 2014-07-23 06:55:18 -0600 | [diff] [blame] | 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' |
Simon Glass | 997c87b | 2014-07-23 06:55:19 -0600 | [diff] [blame] | 105 | Test: dm_test_bus_children_funcs |
Simon Glass | a8981d4 | 2014-10-13 23:41:49 -0600 | [diff] [blame] | 106 | Test: dm_test_bus_children_iterators |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 107 | Test: dm_test_bus_parent_data |
Simon Glass | a327dee | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 108 | Test: dm_test_bus_parent_ops |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 109 | Test: dm_test_children |
| 110 | Test: dm_test_fdt |
Simon Glass | 5a66a8f | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 111 | Device 'd-test': seq 3 is in use by 'b-test' |
Simon Glass | f4cdead | 2014-07-23 06:55:14 -0600 | [diff] [blame] | 112 | Test: dm_test_fdt_offset |
Simon Glass | 00606d7 | 2014-07-23 06:55:03 -0600 | [diff] [blame] | 113 | Test: dm_test_fdt_pre_reloc |
Simon Glass | 5a66a8f | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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' |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 117 | Test: dm_test_gpio |
Simon Glass | 4b8f11c | 2014-10-04 11:29:48 -0600 | [diff] [blame] | 118 | extra-gpios: get_value: error: gpio b5 not reserved |
| 119 | Test: dm_test_gpio_anon |
Simon Glass | 4324174 | 2014-10-04 11:29:51 -0600 | [diff] [blame] | 120 | Test: dm_test_gpio_copy |
| 121 | Test: dm_test_gpio_leak |
| 122 | extra-gpios: get_value: error: gpio b5 not reserved |
Simon Glass | d44f597 | 2014-10-04 11:29:49 -0600 | [diff] [blame] | 123 | Test: dm_test_gpio_requestf |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 124 | Test: dm_test_leak |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 125 | Test: dm_test_lifecycle |
| 126 | Test: dm_test_operations |
| 127 | Test: dm_test_ordering |
| 128 | Test: dm_test_platdata |
Simon Glass | 00606d7 | 2014-07-23 06:55:03 -0600 | [diff] [blame] | 129 | Test: dm_test_pre_reloc |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 130 | Test: dm_test_remove |
Simon Glass | 4b8f11c | 2014-10-04 11:29:48 -0600 | [diff] [blame] | 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 |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 151 | Test: dm_test_uclass |
Simon Glass | c910e2e | 2014-07-23 06:55:15 -0600 | [diff] [blame] | 152 | Test: dm_test_uclass_before_ready |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 153 | Failures: 0 |
| 154 | |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 |
Chris Packham | 34e4a2e | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 160 | the usual command processing and then: |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 161 | |
Heiko Schocher | 54c5d08 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 162 | struct udevice *demo_dev; |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Heiko Schocher | 54c5d08 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 187 | int demo_hello(struct udevice *dev, int ch) |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Heiko Schocher | 54c5d08 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 200 | static int simple_hello(struct udevice *dev, int ch) |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Chris Packham | 34e4a2e | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 305 | Drivers can access their data via dev->info->platdata. Here is |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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!). |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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, |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 348 | |
| 349 | The 'auto_alloc' feature allowed space for the platdata to be allocated |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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. |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 355 | |
| 356 | Note that both methods are optional. If you provide an ofdata_to_platdata |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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. |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | 5a66a8f | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 |
Simon Glass | 547cea1 | 2014-10-13 23:41:51 -0600 | [diff] [blame] | 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. |
Simon Glass | 5a66a8f | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 | |
Simon Glass | a327dee | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 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 | |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 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 |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 599 | f. The device's sequence number is assigned, either the requested one |
Simon Glass | 5a66a8f | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 600 | (assuming no conflicts) or the next available one if there is a conflict |
| 601 | or nothing particular is requested. |
| 602 | |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 603 | g. If the driver provides an ofdata_to_platdata() method, then this is |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 619 | h. The device's probe() method is called. This should do anything that |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 634 | i. The device is marked 'activated' |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 635 | |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 636 | j. The uclass's post_probe() method is called, if one exists. This may |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | e59f458 | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 667 | d. The device memory is freed (platform data, private data, uclass data, |
| 668 | parent data). |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 5a66a8f | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 |
Simon Glass | 22ec136 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Chris Packham | 34e4a2e | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 716 | - Tried to aggressively remove boilerplate, so that for most drivers there |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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. |
Simon Glass | ae7f451 | 2014-06-11 23:29:45 -0600 | [diff] [blame] | 721 | - Rename some structures to make them more similar to Linux (struct udevice |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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'. |
Heiko Schocher | 54c5d08 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 727 | - Remove 'struct driver_instance' and just use a single 'struct udevice'. |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | 00606d7 | 2014-07-23 06:55:03 -0600 | [diff] [blame] | 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 | |
Simon Glass | 38687ae | 2014-11-10 17:16:54 -0700 | [diff] [blame] | 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 |
| 767 | |
| 768 | |
| 769 | Enabling Driver Model |
| 770 | --------------------- |
| 771 | |
| 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 | |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 788 | Things to punt for later |
| 789 | ------------------------ |
| 790 | |
Simon Glass | 65c7053 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 |