Simon Glass | 069fb77 | 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 | f44e5b4 | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 23 | a way of accessing individual devices within the group, but always |
Simon Glass | 069fb77 | 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 | 2f4e1ea | 2014-12-19 14:16:44 +0900 | [diff] [blame] | 39 | make sandbox_defconfig |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 40 | make |
Masahiro Yamada | 2f4e1ea | 2014-12-19 14:16:44 +0900 | [diff] [blame] | 41 | ./u-boot -d u-boot.dtb |
Simon Glass | 069fb77 | 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 | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 98 | Running 53 driver model tests |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 99 | Test: dm_test_autobind |
| 100 | Test: dm_test_autoprobe |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 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 |
Simon Glass | 4071742 | 2014-07-23 06:55:18 -0600 | [diff] [blame] | 104 | Test: dm_test_bus_children |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 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' |
Simon Glass | 48d4e29 | 2014-07-23 06:55:19 -0600 | [diff] [blame] | 107 | Test: dm_test_bus_children_funcs |
Simon Glass | 44da735 | 2014-10-13 23:41:49 -0600 | [diff] [blame] | 108 | Test: dm_test_bus_children_iterators |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 109 | Test: dm_test_bus_parent_data |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 110 | Test: dm_test_bus_parent_data_uclass |
Simon Glass | d45560d | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 111 | Test: dm_test_bus_parent_ops |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 112 | Test: dm_test_bus_parent_platdata |
| 113 | Test: dm_test_bus_parent_platdata_uclass |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 114 | Test: dm_test_children |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 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 |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 139 | Test: dm_test_fdt |
Simon Glass | c1464ab | 2014-07-23 06:55:14 -0600 | [diff] [blame] | 140 | Test: dm_test_fdt_offset |
Simon Glass | fef72b7 | 2014-07-23 06:55:03 -0600 | [diff] [blame] | 141 | Test: dm_test_fdt_pre_reloc |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 142 | Test: dm_test_fdt_uclass_seq |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 143 | Test: dm_test_gpio |
Simon Glass | 96f7d60 | 2014-10-04 11:29:48 -0600 | [diff] [blame] | 144 | extra-gpios: get_value: error: gpio b5 not reserved |
| 145 | Test: dm_test_gpio_anon |
Simon Glass | b4463db | 2014-10-04 11:29:51 -0600 | [diff] [blame] | 146 | Test: dm_test_gpio_copy |
| 147 | Test: dm_test_gpio_leak |
| 148 | extra-gpios: get_value: error: gpio b5 not reserved |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 149 | Test: dm_test_gpio_phandles |
Simon Glass | 1b27d60 | 2014-10-04 11:29:49 -0600 | [diff] [blame] | 150 | Test: dm_test_gpio_requestf |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 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 |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 158 | Test: dm_test_leak |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 159 | Test: dm_test_lifecycle |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 160 | Test: dm_test_net_retry |
| 161 | Using eth@10004000 device |
| 162 | Using eth@10002000 device |
| 163 | Using eth@10004000 device |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 164 | Test: dm_test_operations |
| 165 | Test: dm_test_ordering |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 166 | Test: dm_test_pci_base |
| 167 | Test: dm_test_pci_swapcase |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 168 | Test: dm_test_platdata |
Simon Glass | fef72b7 | 2014-07-23 06:55:03 -0600 | [diff] [blame] | 169 | Test: dm_test_pre_reloc |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 170 | Test: dm_test_remove |
Simon Glass | 96f7d60 | 2014-10-04 11:29:48 -0600 | [diff] [blame] | 171 | Test: dm_test_spi_find |
| 172 | Invalid chip select 0:0 (err=-19) |
| 173 | SF: Failed to get idcodes |
Simon Glass | 96f7d60 | 2014-10-04 11:29:48 -0600 | [diff] [blame] | 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 |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 190 | Test: dm_test_uclass |
Simon Glass | de70867 | 2014-07-23 06:55:15 -0600 | [diff] [blame] | 191 | Test: dm_test_uclass_before_ready |
Simon Glass | 39f158e | 2015-04-19 07:21:01 -0600 | [diff] [blame] | 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 |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 195 | Failures: 0 |
| 196 | |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 |
Chris Packham | f44e5b4 | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 202 | the usual command processing and then: |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 203 | |
Heiko Schocher | b74fcb4 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 204 | struct udevice *demo_dev; |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Heiko Schocher | b74fcb4 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 229 | int demo_hello(struct udevice *dev, int ch) |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Heiko Schocher | b74fcb4 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 242 | static int simple_hello(struct udevice *dev, int ch) |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | 8a42cbf | 2015-07-06 12:54:22 -0600 | [diff] [blame] | 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 | |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Chris Packham | f44e5b4 | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 356 | Drivers can access their data via dev->info->platdata. Here is |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 |
Simon Glass | 8a42cbf | 2015-07-06 12:54:22 -0600 | [diff] [blame] | 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: |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 384 | |
| 385 | red-square { |
| 386 | compatible = "demo-shape"; |
| 387 | colour = "red"; |
| 388 | sides = <4>; |
| 389 | }; |
| 390 | |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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!). |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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, |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 403 | |
| 404 | The 'auto_alloc' feature allowed space for the platdata to be allocated |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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. |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 410 | |
| 411 | Note that both methods are optional. If you provide an ofdata_to_platdata |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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. |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | cc7cf94 | 2015-01-25 08:26:58 -0700 | [diff] [blame] | 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 | |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 |
Simon Glass | 0ccb097 | 2015-01-25 08:27:05 -0700 | [diff] [blame] | 446 | to be locating by their 'sequence'. This numbering uniquely identifies a |
Simon Glass | 47424ec | 2014-10-13 23:41:51 -0600 | [diff] [blame] | 447 | device in its uclass, so no two devices within a particular uclass can have |
| 448 | the same sequence number. |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 449 | |
| 450 | Sequence numbers start from 0 but gaps are permitted. For example, a board |
Simon Glass | 0ccb097 | 2015-01-25 08:27:05 -0700 | [diff] [blame] | 451 | may have I2C buses 1, 4, 5 but no 0, 2 or 3. The choice of how devices are |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 |
Simon Glass | 0ccb097 | 2015-01-25 08:27:05 -0700 | [diff] [blame] | 461 | used. Make sure that the uclass has the DM_UC_FLAG_SEQ_ALIAS flag set. |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 | |
Simon Glass | 0ccb097 | 2015-01-25 08:27:05 -0700 | [diff] [blame] | 471 | More commonly you can use node references, which expand to the full path: |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 472 | |
Simon Glass | 0ccb097 | 2015-01-25 08:27:05 -0700 | [diff] [blame] | 473 | aliases { |
| 474 | serial2 = &serial_2; |
| 475 | }; |
| 476 | ... |
| 477 | serial_2: serial@22230000 { |
| 478 | ... |
| 479 | }; |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 480 | |
Simon Glass | 0ccb097 | 2015-01-25 08:27:05 -0700 | [diff] [blame] | 481 | The alias resolves to the same string in this case, but this version is |
| 482 | easier to read. |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 | |
Simon Glass | d45560d | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 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 | |
Simon Glass | 0623299 | 2015-01-25 08:27:20 -0700 | [diff] [blame] | 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. |
Simon Glass | d45560d | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 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 | |
Simon Glass | 0623299 | 2015-01-25 08:27:20 -0700 | [diff] [blame] | 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. |
Simon Glass | d45560d | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 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 | |
Simon Glass | 0623299 | 2015-01-25 08:27:20 -0700 | [diff] [blame] | 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 | |
Simon Glass | d45560d | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 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 |
Simon Glass | 0623299 | 2015-01-25 08:27:20 -0700 | [diff] [blame] | 568 | on the bus. It is the bus' uclass that controls the child with respect to |
| 569 | the bus. |
Simon Glass | d45560d | 2014-07-23 06:55:21 -0600 | [diff] [blame] | 570 | |
| 571 | |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 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 |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 649 | f. The device's sequence number is assigned, either the requested one |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 650 | (assuming no conflicts) or the next available one if there is a conflict |
| 651 | or nothing particular is requested. |
| 652 | |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 653 | g. If the driver provides an ofdata_to_platdata() method, then this is |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 669 | h. The device's probe() method is called. This should do anything that |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 684 | i. The device is marked 'activated' |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 685 | |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 686 | j. The uclass's post_probe() method is called, if one exists. This may |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 60d971b | 2014-07-23 06:55:20 -0600 | [diff] [blame] | 717 | d. The device memory is freed (platform data, private data, uclass data, |
| 718 | parent data). |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | db6f020 | 2014-07-23 06:55:12 -0600 | [diff] [blame] | 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 |
Simon Glass | 3b2a815 | 2014-06-11 23:29:55 -0600 | [diff] [blame] | 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 | |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Chris Packham | f44e5b4 | 2014-06-07 10:35:55 +1200 | [diff] [blame] | 766 | - Tried to aggressively remove boilerplate, so that for most drivers there |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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. |
Simon Glass | 767827a | 2014-06-11 23:29:45 -0600 | [diff] [blame] | 771 | - Rename some structures to make them more similar to Linux (struct udevice |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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'. |
Heiko Schocher | b74fcb4 | 2014-05-22 12:43:05 +0200 | [diff] [blame] | 777 | - Remove 'struct driver_instance' and just use a single 'struct udevice'. |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 | |
Simon Glass | fef72b7 | 2014-07-23 06:55:03 -0600 | [diff] [blame] | 787 | |
| 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 | |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 802 | |
Simon Glass | 9fa901b | 2014-11-10 17:16:54 -0700 | [diff] [blame] | 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. |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 809 | |
Simon Glass | 9fa901b | 2014-11-10 17:16:54 -0700 | [diff] [blame] | 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. |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 812 | |
Simon Glass | 9fa901b | 2014-11-10 17:16:54 -0700 | [diff] [blame] | 813 | - CONFIG_SYS_MALLOC_SIMPLE |
| 814 | - CONFIG_DM_WARN |
| 815 | - CONFIG_DM_DEVICE_REMOVE |
| 816 | - CONFIG_DM_STDIO |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 817 | |
Simon Glass | 9fa901b | 2014-11-10 17:16:54 -0700 | [diff] [blame] | 818 | |
| 819 | Enabling Driver Model |
| 820 | --------------------- |
| 821 | |
| 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 | ------------------------ |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 840 | |
Simon Glass | 069fb77 | 2014-02-26 15:59:17 -0700 | [diff] [blame] | 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 |