Eric Lee / smarc-uboot

Download as
Browse Code »

Commit 2f3b95dbc78ce96b0f9f471e688db66223988419

Authored by Simon Glass
1 parent 040b69af72
Exists in v2017.01-smarct4x and in 39 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, emb_lf_v2023.04, emb_lf_v2024.04, imx_v2015.04_4.1.15_1.0.0_ga, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc-imx6_v2018.03_4.14.98_2.0.0_ga, smarc-imx7_v2017.03_4.9.11_1.0.0_ga, smarc-imx7_v2018.03_4.14.98_2.0.0_ga, smarc-imx_v2015.04_4.1.15_1.0.0_ga, smarc-imx_v2017.03_4.9.11_1.0.0_ga, smarc-imx_v2017.03_4.9.88_2.0.0_ga, smarc-imx_v2017.03_o8.1.0_1.3.0_8m, smarc-imx_v2018.03_4.14.78_1.0.0_ga, smarc-m6.0.1_2.1.0-ga, smarc-n7.1.2_2.0.0-ga, smarc-rel_imx_4.1.15_2.0.0_ga, smarc_8m-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8m_00d0-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0, smarc_8mq_lf_v2020.04, ti-u-boot-2015.07, v2015.07-smarct33, v2015.07-smarct33-emmc, v2015.07-smarct4x, v2016.05-dlt, v2016.05-smarct3x, v2016.05-smarct3x-emmc, v2016.05-smarct4x, v2017.01-smarct3x, v2017.01-smarct3x-emmc

dm: core: Set device tree node for root device 

The root device corresponds to the root device tree node, so set this up.
Also add a few notes to the documentation.

Signed-off-by: Simon Glass <sjg@chromium.org>

Showing 2 changed files with 7 additions and 0 deletions Inline Diff

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