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