blob: 96525b6ccc5ff95342b70342de928cb8cfe2c53b [file] [log] [blame]
Bin Menged205e62019-07-18 00:33:49 -07001.. SPDX-License-Identifier: GPL-2.0+
2.. sectionauthor:: Simon Glass <sjg@chromium.org>
3
4Design Details
5==============
Simon Glass65c70532014-02-26 15:59:17 -07006
7This README contains high-level information about driver model, a unified
8way of declaring and accessing drivers in U-Boot. The original work was done
9by:
10
Bin Menged205e62019-07-18 00:33:49 -070011 * Marek Vasut <marex@denx.de>
12 * Pavel Herrmann <morpheus.ibis@gmail.com>
13 * Viktor Křivák <viktor.krivak@gmail.com>
14 * Tomas Hlavacek <tmshlvck@gmail.com>
Simon Glass65c70532014-02-26 15:59:17 -070015
16This has been both simplified and extended into the current implementation
17by:
18
Bin Menged205e62019-07-18 00:33:49 -070019 * Simon Glass <sjg@chromium.org>
Simon Glass65c70532014-02-26 15:59:17 -070020
21
22Terminology
23-----------
24
Bin Menged205e62019-07-18 00:33:49 -070025Uclass
26 a group of devices which operate in the same way. A uclass provides
27 a way of accessing individual devices within the group, but always
28 using the same interface. For example a GPIO uclass provides
29 operations for get/set value. An I2C uclass may have 10 I2C ports,
30 4 with one driver, and 6 with another.
Simon Glass65c70532014-02-26 15:59:17 -070031
Bin Menged205e62019-07-18 00:33:49 -070032Driver
33 some code which talks to a peripheral and presents a higher-level
34 interface to it.
Simon Glass65c70532014-02-26 15:59:17 -070035
Bin Menged205e62019-07-18 00:33:49 -070036Device
37 an instance of a driver, tied to a particular port or peripheral.
Simon Glass65c70532014-02-26 15:59:17 -070038
39
40How to try it
41-------------
42
Bin Menged205e62019-07-18 00:33:49 -070043Build U-Boot sandbox and run it::
Simon Glass65c70532014-02-26 15:59:17 -070044
Masahiro Yamada33fcd1b2014-12-19 14:16:44 +090045 make sandbox_defconfig
Simon Glass65c70532014-02-26 15:59:17 -070046 make
Masahiro Yamada33fcd1b2014-12-19 14:16:44 +090047 ./u-boot -d u-boot.dtb
Simon Glass65c70532014-02-26 15:59:17 -070048
49 (type 'reset' to exit U-Boot)
50
51
52There is a uclass called 'demo'. This uclass handles
53saying hello, and reporting its status. There are two drivers in this
54uclass:
55
56 - simple: Just prints a message for hello, doesn't implement status
57 - shape: Prints shapes and reports number of characters printed as status
58
59The demo class is pretty simple, but not trivial. The intention is that it
60can be used for testing, so it will implement all driver model features and
61provide good code coverage of them. It does have multiple drivers, it
62handles parameter data and platdata (data which tells the driver how
63to operate on a particular platform) and it uses private driver data.
64
Bin Menged205e62019-07-18 00:33:49 -070065To try it, see the example session below::
Simon Glass65c70532014-02-26 15:59:17 -070066
Bin Menged205e62019-07-18 00:33:49 -070067 =>demo hello 1
68 Hello '@' from 07981110: red 4
69 =>demo status 2
70 Status: 0
71 =>demo hello 2
72 g
73 r@
74 e@@
75 e@@@
76 n@@@@
77 g@@@@@
78 =>demo status 2
79 Status: 21
80 =>demo hello 4 ^
81 y^^^
82 e^^^^^
83 l^^^^^^^
84 l^^^^^^^
85 o^^^^^
86 w^^^
87 =>demo status 4
88 Status: 36
89 =>
Simon Glass65c70532014-02-26 15:59:17 -070090
91
92Running the tests
93-----------------
94
95The intent with driver model is that the core portion has 100% test coverage
96in sandbox, and every uclass has its own test. As a move towards this, tests
Bin Menged205e62019-07-18 00:33:49 -070097are provided in test/dm. To run them, try::
Simon Glass65c70532014-02-26 15:59:17 -070098
Jagan Tekie57f9c82016-03-17 12:23:18 +053099 ./test/py/test.py --bd sandbox --build -k ut_dm -v
Simon Glass65c70532014-02-26 15:59:17 -0700100
Bin Menged205e62019-07-18 00:33:49 -0700101You should see something like this::
Simon Glass65c70532014-02-26 15:59:17 -0700102
Bin Menged205e62019-07-18 00:33:49 -0700103 (venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v
104 +make O=/root/u-boot/build-sandbox -s sandbox_defconfig
105 +make O=/root/u-boot/build-sandbox -s -j8
106 ============================= test session starts ==============================
107 platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/python
108 cachedir: .cache
109 rootdir: /root/u-boot, inifile:
110 collected 199 items
Simon Glass98a16052015-04-19 07:21:01 -0600111
Bin Menged205e62019-07-18 00:33:49 -0700112 test/py/tests/test_ut.py::test_ut_dm_init PASSED
113 test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED
114 test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED
115 test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED
116 test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED
117 test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED
118 test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED
119 test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED
120 test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED
121 test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED
122 test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED
123 test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED
124 test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED
125 test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED
126 test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED
127 test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED
128 test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED
129 test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED
130 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED
131 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED
132 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED
133 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED
134 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED
135 test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED
136 test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED
137 test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED
138 test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED
139 test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED
140 test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED
141 test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED
142 test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED
143 test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED
144 test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED
145 test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED
146 test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED
147 test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED
148 test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED
149 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED
150 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED
151 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED
152 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED
153 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED
154 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED
155 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED
156 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED
157 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED
158 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED
159 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED
160 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED
161 test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED
162 test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED
163 test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED
164 test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED
165 test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED
166 test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED
167 test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED
168 test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED
169 test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED
170 test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED
171 test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED
172 test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED
173 test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED
174 test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED
175 test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED
176 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED
177 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED
178 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED
179 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED
180 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED
181 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED
182 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED
183 test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED
184 test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED
185 test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED
186 test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED
187 test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED
188 test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED
189 test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED
190 test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED
191 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED
192 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED
193 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED
194 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED
195 test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED
196 test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED
197 test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED
198 test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED
199 test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED
200 test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED
201 test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED
202 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED
203 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED
204 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED
205 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED
206 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED
207 test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED
208 test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED
209 test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED
210 test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED
211 test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED
212 test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED
213 test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED
214 test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED
215 test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED
216 test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED
217 test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED
218 test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED
219 test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED
220 test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED
221 test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED
222 test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED
223 test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED
224 test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED
225 test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED
226 test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED
Simon Glass98a16052015-04-19 07:21:01 -0600227
Bin Menged205e62019-07-18 00:33:49 -0700228 ======================= 84 tests deselected by '-kut_dm' =======================
229 ================== 115 passed, 84 deselected in 3.77 seconds ===================
Simon Glass65c70532014-02-26 15:59:17 -0700230
231What is going on?
232-----------------
233
Dario Binacchi2a372012020-02-09 19:57:41 +0100234Let's start at the top. The demo command is in cmd/demo.c. It does
Chris Packham34e4a2e2014-06-07 10:35:55 +1200235the usual command processing and then:
Simon Glass65c70532014-02-26 15:59:17 -0700236
Bin Menged205e62019-07-18 00:33:49 -0700237.. code-block:: c
238
Heiko Schocher54c5d082014-05-22 12:43:05 +0200239 struct udevice *demo_dev;
Simon Glass65c70532014-02-26 15:59:17 -0700240
241 ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev);
242
243UCLASS_DEMO means the class of devices which implement 'demo'. Other
244classes might be MMC, or GPIO, hashing or serial. The idea is that the
245devices in the class all share a particular way of working. The class
246presents a unified view of all these devices to U-Boot.
247
248This function looks up a device for the demo uclass. Given a device
249number we can find the device because all devices have registered with
250the UCLASS_DEMO uclass.
251
252The device is automatically activated ready for use by uclass_get_device().
253
254Now that we have the device we can do things like:
255
Bin Menged205e62019-07-18 00:33:49 -0700256.. code-block:: c
257
Simon Glass65c70532014-02-26 15:59:17 -0700258 return demo_hello(demo_dev, ch);
259
260This function is in the demo uclass. It takes care of calling the 'hello'
261method of the relevant driver. Bearing in mind that there are two drivers,
262this particular device may use one or other of them.
263
264The code for demo_hello() is in drivers/demo/demo-uclass.c:
265
Bin Menged205e62019-07-18 00:33:49 -0700266.. code-block:: c
Simon Glass65c70532014-02-26 15:59:17 -0700267
Bin Menged205e62019-07-18 00:33:49 -0700268 int demo_hello(struct udevice *dev, int ch)
269 {
270 const struct demo_ops *ops = device_get_ops(dev);
Simon Glass65c70532014-02-26 15:59:17 -0700271
Bin Menged205e62019-07-18 00:33:49 -0700272 if (!ops->hello)
273 return -ENOSYS;
274
275 return ops->hello(dev, ch);
276 }
Simon Glass65c70532014-02-26 15:59:17 -0700277
278As you can see it just calls the relevant driver method. One of these is
279in drivers/demo/demo-simple.c:
280
Bin Menged205e62019-07-18 00:33:49 -0700281.. code-block:: c
Simon Glass65c70532014-02-26 15:59:17 -0700282
Bin Menged205e62019-07-18 00:33:49 -0700283 static int simple_hello(struct udevice *dev, int ch)
284 {
285 const struct dm_demo_pdata *pdata = dev_get_platdata(dev);
Simon Glass65c70532014-02-26 15:59:17 -0700286
Bin Menged205e62019-07-18 00:33:49 -0700287 printf("Hello from %08x: %s %d\n", map_to_sysmem(dev),
288 pdata->colour, pdata->sides);
289
290 return 0;
291 }
Simon Glass65c70532014-02-26 15:59:17 -0700292
293
294So that is a trip from top (command execution) to bottom (driver action)
295but it leaves a lot of topics to address.
296
297
298Declaring Drivers
299-----------------
300
301A driver declaration looks something like this (see
302drivers/demo/demo-shape.c):
303
Bin Menged205e62019-07-18 00:33:49 -0700304.. code-block:: c
Simon Glass65c70532014-02-26 15:59:17 -0700305
Bin Menged205e62019-07-18 00:33:49 -0700306 static const struct demo_ops shape_ops = {
307 .hello = shape_hello,
308 .status = shape_status,
309 };
310
311 U_BOOT_DRIVER(demo_shape_drv) = {
312 .name = "demo_shape_drv",
313 .id = UCLASS_DEMO,
314 .ops = &shape_ops,
315 .priv_data_size = sizeof(struct shape_data),
316 };
Simon Glass65c70532014-02-26 15:59:17 -0700317
318
319This driver has two methods (hello and status) and requires a bit of
320private data (accessible through dev_get_priv(dev) once the driver has
321been probed). It is a member of UCLASS_DEMO so will register itself
322there.
323
324In U_BOOT_DRIVER it is also possible to specify special methods for bind
325and unbind, and these are called at appropriate times. For many drivers
326it is hoped that only 'probe' and 'remove' will be needed.
327
328The U_BOOT_DRIVER macro creates a data structure accessible from C,
329so driver model can find the drivers that are available.
330
331The methods a device can provide are documented in the device.h header.
332Briefly, they are:
333
Bin Menged205e62019-07-18 00:33:49 -0700334 * bind - make the driver model aware of a device (bind it to its driver)
335 * unbind - make the driver model forget the device
336 * ofdata_to_platdata - convert device tree data to platdata - see later
337 * probe - make a device ready for use
338 * remove - remove a device so it cannot be used until probed again
Simon Glass65c70532014-02-26 15:59:17 -0700339
340The sequence to get a device to work is bind, ofdata_to_platdata (if using
341device tree) and probe.
342
343
344Platform Data
345-------------
346
Bin Menged205e62019-07-18 00:33:49 -0700347Note: platform data is the old way of doing things. It is
348basically a C structure which is passed to drivers to tell them about
349platform-specific settings like the address of its registers, bus
350speed, etc. Device tree is now the preferred way of handling this.
351Unless you have a good reason not to use device tree (the main one
352being you need serial support in SPL and don't have enough SRAM for
353the cut-down device tree and libfdt libraries) you should stay away
354from platform data.
Simon Glass97f3ee32015-07-06 12:54:22 -0600355
Simon Glass22ec1362014-06-11 23:29:55 -0600356Platform data is like Linux platform data, if you are familiar with that.
357It provides the board-specific information to start up a device.
358
359Why is this information not just stored in the device driver itself? The
360idea is that the device driver is generic, and can in principle operate on
361any board that has that type of device. For example, with modern
362highly-complex SoCs it is common for the IP to come from an IP vendor, and
363therefore (for example) the MMC controller may be the same on chips from
364different vendors. It makes no sense to write independent drivers for the
365MMC controller on each vendor's SoC, when they are all almost the same.
366Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same,
367but lie at different addresses in the address space.
368
369Using the UART example, we have a single driver and it is instantiated 6
370times by supplying 6 lots of platform data. Each lot of platform data
371gives the driver name and a pointer to a structure containing information
372about this instance - e.g. the address of the register space. It may be that
373one of the UARTS supports RS-485 operation - this can be added as a flag in
374the platform data, which is set for this one port and clear for the rest.
375
376Think of your driver as a generic piece of code which knows how to talk to
377a device, but needs to know where it is, any variant/option information and
378so on. Platform data provides this link between the generic piece of code
379and the specific way it is bound on a particular board.
380
381Examples of platform data include:
382
383 - The base address of the IP block's register space
384 - Configuration options, like:
Bin Menged205e62019-07-18 00:33:49 -0700385 - the SPI polarity and maximum speed for a SPI controller
386 - the I2C speed to use for an I2C device
387 - the number of GPIOs available in a GPIO device
Simon Glass22ec1362014-06-11 23:29:55 -0600388
389Where does the platform data come from? It is either held in a structure
390which is compiled into U-Boot, or it can be parsed from the Device Tree
391(see 'Device Tree' below).
392
393For an example of how it can be compiled in, see demo-pdata.c which
Simon Glass65c70532014-02-26 15:59:17 -0700394sets up a table of driver names and their associated platform data.
395The data can be interpreted by the drivers however they like - it is
396basically a communication scheme between the board-specific code and
397the generic drivers, which are intended to work on any board.
398
Chris Packham34e4a2e2014-06-07 10:35:55 +1200399Drivers can access their data via dev->info->platdata. Here is
Simon Glass65c70532014-02-26 15:59:17 -0700400the declaration for the platform data, which would normally appear
401in the board file.
402
Bin Menged205e62019-07-18 00:33:49 -0700403.. code-block:: c
404
Dario Binacchi2a372012020-02-09 19:57:41 +0100405 static const struct dm_demo_pdata red_square = {
Simon Glass65c70532014-02-26 15:59:17 -0700406 .colour = "red",
407 .sides = 4.
408 };
Bin Menged205e62019-07-18 00:33:49 -0700409
Simon Glass65c70532014-02-26 15:59:17 -0700410 static const struct driver_info info[] = {
411 {
412 .name = "demo_shape_drv",
413 .platdata = &red_square,
414 },
415 };
416
417 demo1 = driver_bind(root, &info[0]);
418
419
420Device Tree
421-----------
422
423While platdata is useful, a more flexible way of providing device data is
Simon Glass97f3ee32015-07-06 12:54:22 -0600424by using device tree. In U-Boot you should use this where possible. Avoid
425sending patches which make use of the U_BOOT_DEVICE() macro unless strictly
426necessary.
427
428With device tree we replace the above code with the following device tree
429fragment:
Simon Glass65c70532014-02-26 15:59:17 -0700430
Bin Menged205e62019-07-18 00:33:49 -0700431.. code-block:: c
432
Simon Glass65c70532014-02-26 15:59:17 -0700433 red-square {
434 compatible = "demo-shape";
435 colour = "red";
436 sides = <4>;
437 };
438
Simon Glass22ec1362014-06-11 23:29:55 -0600439This means that instead of having lots of U_BOOT_DEVICE() declarations in
440the board file, we put these in the device tree. This approach allows a lot
441more generality, since the same board file can support many types of boards
442(e,g. with the same SoC) just by using different device trees. An added
443benefit is that the Linux device tree can be used, thus further simplifying
444the task of board-bring up either for U-Boot or Linux devs (whoever gets to
445the board first!).
Simon Glass65c70532014-02-26 15:59:17 -0700446
447The easiest way to make this work it to add a few members to the driver:
448
Bin Menged205e62019-07-18 00:33:49 -0700449.. code-block:: c
450
Simon Glass65c70532014-02-26 15:59:17 -0700451 .platdata_auto_alloc_size = sizeof(struct dm_test_pdata),
452 .ofdata_to_platdata = testfdt_ofdata_to_platdata,
Simon Glass65c70532014-02-26 15:59:17 -0700453
454The 'auto_alloc' feature allowed space for the platdata to be allocated
Simon Glass22ec1362014-06-11 23:29:55 -0600455and zeroed before the driver's ofdata_to_platdata() method is called. The
456ofdata_to_platdata() method, which the driver write supplies, should parse
457the device tree node for this device and place it in dev->platdata. Thus
458when the probe method is called later (to set up the device ready for use)
459the platform data will be present.
Simon Glass65c70532014-02-26 15:59:17 -0700460
461Note that both methods are optional. If you provide an ofdata_to_platdata
Simon Glass22ec1362014-06-11 23:29:55 -0600462method then it will be called first (during activation). If you provide a
463probe method it will be called next. See Driver Lifecycle below for more
464details.
Simon Glass65c70532014-02-26 15:59:17 -0700465
466If you don't want to have the platdata automatically allocated then you
467can leave out platdata_auto_alloc_size. In this case you can use malloc
468in your ofdata_to_platdata (or probe) method to allocate the required memory,
469and you should free it in the remove method.
470
Simon Glass2f3b95d2015-01-25 08:26:58 -0700471The driver model tree is intended to mirror that of the device tree. The
472root driver is at device tree offset 0 (the root node, '/'), and its
473children are the children of the root node.
474
Tom Rini15416c82018-08-31 11:59:11 -0400475In order for a device tree to be valid, the content must be correct with
476respect to either device tree specification
477(https://www.devicetree.org/specifications/) or the device tree bindings that
478are found in the doc/device-tree-bindings directory. When not U-Boot specific
479the bindings in this directory tend to come from the Linux Kernel. As such
480certain design decisions may have been made already for us in terms of how
481specific devices are described and bound. In most circumstances we wish to
482retain compatibility without additional changes being made to the device tree
483source files.
Simon Glass65c70532014-02-26 15:59:17 -0700484
485Declaring Uclasses
486------------------
487
488The demo uclass is declared like this:
489
Bin Menged205e62019-07-18 00:33:49 -0700490.. code-block:: c
491
Dario Binacchi2a372012020-02-09 19:57:41 +0100492 UCLASS_DRIVER(demo) = {
Bin Menged205e62019-07-18 00:33:49 -0700493 .id = UCLASS_DEMO,
494 };
Simon Glass65c70532014-02-26 15:59:17 -0700495
496It is also possible to specify special methods for probe, etc. The uclass
Dario Binacchi2a372012020-02-09 19:57:41 +0100497numbering comes from include/dm/uclass-id.h. To add a new uclass, add to the
Simon Glass65c70532014-02-26 15:59:17 -0700498end of the enum there, then declare your uclass as above.
499
500
Simon Glass5a66a8f2014-07-23 06:55:12 -0600501Device Sequence Numbers
502-----------------------
503
504U-Boot numbers devices from 0 in many situations, such as in the command
505line for I2C and SPI buses, and the device names for serial ports (serial0,
506serial1, ...). Driver model supports this numbering and permits devices
Simon Glass9cc36a22015-01-25 08:27:05 -0700507to be locating by their 'sequence'. This numbering uniquely identifies a
Simon Glass547cea12014-10-13 23:41:51 -0600508device in its uclass, so no two devices within a particular uclass can have
509the same sequence number.
Simon Glass5a66a8f2014-07-23 06:55:12 -0600510
511Sequence numbers start from 0 but gaps are permitted. For example, a board
Simon Glass9cc36a22015-01-25 08:27:05 -0700512may have I2C buses 1, 4, 5 but no 0, 2 or 3. The choice of how devices are
Simon Glass5a66a8f2014-07-23 06:55:12 -0600513numbered is up to a particular board, and may be set by the SoC in some
514cases. While it might be tempting to automatically renumber the devices
515where there are gaps in the sequence, this can lead to confusion and is
516not the way that U-Boot works.
517
518Each device can request a sequence number. If none is required then the
519device will be automatically allocated the next available sequence number.
520
521To specify the sequence number in the device tree an alias is typically
Simon Glass9cc36a22015-01-25 08:27:05 -0700522used. Make sure that the uclass has the DM_UC_FLAG_SEQ_ALIAS flag set.
Simon Glass5a66a8f2014-07-23 06:55:12 -0600523
Bin Menged205e62019-07-18 00:33:49 -0700524.. code-block:: none
525
526 aliases {
527 serial2 = "/serial@22230000";
528 };
Simon Glass5a66a8f2014-07-23 06:55:12 -0600529
530This indicates that in the uclass called "serial", the named node
531("/serial@22230000") will be given sequence number 2. Any command or driver
532which requests serial device 2 will obtain this device.
533
Simon Glass9cc36a22015-01-25 08:27:05 -0700534More commonly you can use node references, which expand to the full path:
Simon Glass5a66a8f2014-07-23 06:55:12 -0600535
Bin Menged205e62019-07-18 00:33:49 -0700536.. code-block:: none
537
538 aliases {
539 serial2 = &serial_2;
540 };
541 ...
542 serial_2: serial@22230000 {
543 ...
544 };
Simon Glass5a66a8f2014-07-23 06:55:12 -0600545
Simon Glass9cc36a22015-01-25 08:27:05 -0700546The alias resolves to the same string in this case, but this version is
547easier to read.
Simon Glass5a66a8f2014-07-23 06:55:12 -0600548
549Device sequence numbers are resolved when a device is probed. Before then
550the sequence number is only a request which may or may not be honoured,
551depending on what other devices have been probed. However the numbering is
552entirely under the control of the board author so a conflict is generally
553an error.
554
555
Simon Glassa327dee2014-07-23 06:55:21 -0600556Bus Drivers
557-----------
558
559A common use of driver model is to implement a bus, a device which provides
560access to other devices. Example of buses include SPI and I2C. Typically
561the bus provides some sort of transport or translation that makes it
562possible to talk to the devices on the bus.
563
Simon Glass2017aae2015-01-25 08:27:20 -0700564Driver model provides some useful features to help with implementing buses.
565Firstly, a bus can request that its children store some 'parent data' which
566can be used to keep track of child state. Secondly, the bus can define
567methods which are called when a child is probed or removed. This is similar
568to the methods the uclass driver provides. Thirdly, per-child platform data
569can be provided to specify things like the child's address on the bus. This
570persists across child probe()/remove() cycles.
571
572For consistency and ease of implementation, the bus uclass can specify the
573per-child platform data, so that it can be the same for all children of buses
574in that uclass. There are also uclass methods which can be called when
575children are bound and probed.
Simon Glassa327dee2014-07-23 06:55:21 -0600576
577Here an explanation of how a bus fits with a uclass may be useful. Consider
578a USB bus with several devices attached to it, each from a different (made
Bin Menged205e62019-07-18 00:33:49 -0700579up) uclass::
Simon Glassa327dee2014-07-23 06:55:21 -0600580
581 xhci_usb (UCLASS_USB)
Heinrich Schuchardtda2fa6d2020-02-26 20:18:54 +0100582 eth (UCLASS_ETH)
Simon Glassa327dee2014-07-23 06:55:21 -0600583 camera (UCLASS_CAMERA)
584 flash (UCLASS_FLASH_STORAGE)
585
586Each of the devices is connected to a different address on the USB bus.
587The bus device wants to store this address and some other information such
588as the bus speed for each device.
589
Simon Glass2017aae2015-01-25 08:27:20 -0700590To achieve this, the bus device can use dev->parent_platdata in each of its
591three children. This can be auto-allocated if the bus driver (or bus uclass)
592has a non-zero value for per_child_platdata_auto_alloc_size. If not, then
593the bus device or uclass can allocate the space itself before the child
594device is probed.
Simon Glassa327dee2014-07-23 06:55:21 -0600595
596Also the bus driver can define the child_pre_probe() and child_post_remove()
597methods to allow it to do some processing before the child is activated or
598after it is deactivated.
599
Simon Glass2017aae2015-01-25 08:27:20 -0700600Similarly the bus uclass can define the child_post_bind() method to obtain
601the per-child platform data from the device tree and set it up for the child.
602The bus uclass can also provide a child_pre_probe() method. Very often it is
603the bus uclass that controls these features, since it avoids each driver
604having to do the same processing. Of course the driver can still tweak and
605override these activities.
606
Simon Glassa327dee2014-07-23 06:55:21 -0600607Note that the information that controls this behaviour is in the bus's
608driver, not the child's. In fact it is possible that child has no knowledge
609that it is connected to a bus. The same child device may even be used on two
610different bus types. As an example. the 'flash' device shown above may also
Bin Menged205e62019-07-18 00:33:49 -0700611be connected on a SATA bus or standalone with no bus::
Simon Glassa327dee2014-07-23 06:55:21 -0600612
613 xhci_usb (UCLASS_USB)
614 flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus
615
Heinrich Schuchardt2f8f5e22020-05-20 23:27:27 +0200616 sata (UCLASS_AHCI)
Simon Glassa327dee2014-07-23 06:55:21 -0600617 flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by SATA bus
618
619 flash (UCLASS_FLASH_STORAGE) - no parent data/methods (not on a bus)
620
621Above you can see that the driver for xhci_usb/sata controls the child's
622bus methods. In the third example the device is not on a bus, and therefore
623will not have these methods at all. Consider the case where the flash
624device defines child methods. These would be used for *its* children, and
625would be quite separate from the methods defined by the driver for the bus
626that the flash device is connetced to. The act of attaching a device to a
627parent device which is a bus, causes the device to start behaving like a
628bus device, regardless of its own views on the matter.
629
630The uclass for the device can also contain data private to that uclass.
Dario Binacchicea8f2c2020-06-04 14:58:13 +0200631But note that each device on the bus may be a member of a different
Simon Glassa327dee2014-07-23 06:55:21 -0600632uclass, and this data has nothing to do with the child data for each child
Simon Glass2017aae2015-01-25 08:27:20 -0700633on the bus. It is the bus' uclass that controls the child with respect to
634the bus.
Simon Glassa327dee2014-07-23 06:55:21 -0600635
636
Simon Glass22ec1362014-06-11 23:29:55 -0600637Driver Lifecycle
638----------------
639
640Here are the stages that a device goes through in driver model. Note that all
641methods mentioned here are optional - e.g. if there is no probe() method for
642a device then it will not be called. A simple device may have very few
643methods actually defined.
644
Bin Menged205e62019-07-18 00:33:49 -0700645Bind stage
646^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600647
Stephen Warrendaac3bf2016-05-11 15:26:24 -0600648U-Boot discovers devices using one of these two methods:
Simon Glass22ec1362014-06-11 23:29:55 -0600649
Bin Menged205e62019-07-18 00:33:49 -0700650- Scan the U_BOOT_DEVICE() definitions. U-Boot looks up the name specified
651 by each, to find the appropriate U_BOOT_DRIVER() definition. In this case,
652 there is no path by which driver_data may be provided, but the U_BOOT_DEVICE()
653 may provide platdata.
Simon Glass22ec1362014-06-11 23:29:55 -0600654
Bin Menged205e62019-07-18 00:33:49 -0700655- Scan through the device tree definitions. U-Boot looks at top-level
656 nodes in the the device tree. It looks at the compatible string in each node
657 and uses the of_match table of the U_BOOT_DRIVER() structure to find the
658 right driver for each node. In this case, the of_match table may provide a
659 driver_data value, but platdata cannot be provided until later.
Stephen Warrendaac3bf2016-05-11 15:26:24 -0600660
661For each device that is discovered, U-Boot then calls device_bind() to create a
662new device, initializes various core fields of the device object such as name,
663uclass & driver, initializes any optional fields of the device object that are
664applicable such as of_offset, driver_data & platdata, and finally calls the
665driver's bind() method if one is defined.
Simon Glass22ec1362014-06-11 23:29:55 -0600666
667At this point all the devices are known, and bound to their drivers. There
668is a 'struct udevice' allocated for all devices. However, nothing has been
669activated (except for the root device). Each bound device that was created
670from a U_BOOT_DEVICE() declaration will hold the platdata pointer specified
671in that declaration. For a bound device created from the device tree,
672platdata will be NULL, but of_offset will be the offset of the device tree
673node that caused the device to be created. The uclass is set correctly for
674the device.
675
676The device's bind() method is permitted to perform simple actions, but
677should not scan the device tree node, not initialise hardware, nor set up
678structures or allocate memory. All of these tasks should be left for
679the probe() method.
680
681Note that compared to Linux, U-Boot's driver model has a separate step of
682probe/remove which is independent of bind/unbind. This is partly because in
683U-Boot it may be expensive to probe devices and we don't want to do it until
684they are needed, or perhaps until after relocation.
685
Simon Glassb0dcc872020-04-05 15:38:19 -0600686Reading ofdata
687^^^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600688
Simon Glassb0dcc872020-04-05 15:38:19 -0600689Most devices have data in the device tree which they can read to find out the
690base address of hardware registers and parameters relating to driver
691operation. This is called 'ofdata' (Open-Firmware data).
692
693The device's_ofdata_to_platdata() implemnents allocation and reading of
694platdata. A parent's ofdata is always read before a child.
695
696The steps are:
Simon Glass22ec1362014-06-11 23:29:55 -0600697
Bin Menged205e62019-07-18 00:33:49 -0700698 1. If priv_auto_alloc_size is non-zero, then the device-private space
Simon Glass22ec1362014-06-11 23:29:55 -0600699 is allocated for the device and zeroed. It will be accessible as
700 dev->priv. The driver can put anything it likes in there, but should use
701 it for run-time information, not platform data (which should be static
702 and known before the device is probed).
703
Bin Menged205e62019-07-18 00:33:49 -0700704 2. If platdata_auto_alloc_size is non-zero, then the platform data space
Simon Glass22ec1362014-06-11 23:29:55 -0600705 is allocated. This is only useful for device tree operation, since
706 otherwise you would have to specific the platform data in the
707 U_BOOT_DEVICE() declaration. The space is allocated for the device and
708 zeroed. It will be accessible as dev->platdata.
709
Bin Menged205e62019-07-18 00:33:49 -0700710 3. If the device's uclass specifies a non-zero per_device_auto_alloc_size,
Simon Glass22ec1362014-06-11 23:29:55 -0600711 then this space is allocated and zeroed also. It is allocated for and
712 stored in the device, but it is uclass data. owned by the uclass driver.
713 It is possible for the device to access it.
714
Bin Menged205e62019-07-18 00:33:49 -0700715 4. If the device's immediate parent specifies a per_child_auto_alloc_size
Simon Glasse59f4582014-07-23 06:55:20 -0600716 then this space is allocated. This is intended for use by the parent
717 device to keep track of things related to the child. For example a USB
718 flash stick attached to a USB host controller would likely use this
719 space. The controller can hold information about the USB state of each
720 of its children.
721
Simon Glassb0dcc872020-04-05 15:38:19 -0600722 5. If the driver provides an ofdata_to_platdata() method, then this is
723 called to convert the device tree data into platform data. This should
724 do various calls like dev_read_u32(dev, ...) to access the node and store
725 the resulting information into dev->platdata. After this point, the device
726 works the same way whether it was bound using a device tree node or
727 U_BOOT_DEVICE() structure. In either case, the platform data is now stored
728 in the platdata structure. Typically you will use the
729 platdata_auto_alloc_size feature to specify the size of the platform data
730 structure, and U-Boot will automatically allocate and zero it for you before
731 entry to ofdata_to_platdata(). But if not, you can allocate it yourself in
732 ofdata_to_platdata(). Note that it is preferable to do all the device tree
733 decoding in ofdata_to_platdata() rather than in probe(). (Apart from the
734 ugliness of mixing configuration and run-time data, one day it is possible
735 that U-Boot will cache platform data for devices which are regularly
736 de/activated).
737
738 5. The device is marked 'platdata valid'.
739
740Note that ofdata reading is always done (for a child and all its parents)
741before probing starts. Thus devices go through two distinct states when
742probing: reading platform data and actually touching the hardware to bring
743the device up.
744
745Having probing separate from ofdata-reading helps deal with of-platdata, where
746the probe() method is common to both DT/of-platdata operation, but the
747ofdata_to_platdata() method is implemented differently.
748
749Another case has come up where this separate is useful. Generation of ACPI
750tables uses the of-platdata but does not want to probe the device. Probing
751would cause U-Boot to violate one of its design principles, viz that it
752should only probe devices that are used. For ACPI we want to generate a
753table for each device, even if U-Boot does not use it. In fact it may not
754even be possible to probe the device - e.g. an SD card which is not
755present will cause an error on probe, yet we still must tell Linux about
756the SD card connector in case it is used while Linux is running.
757
758It is important that the ofdata_to_platdata() method does not actually probe
759the device itself. However there are cases where other devices must be probed
760in the ofdata_to_platdata() method. An example is where a device requires a
761GPIO for it to operate. To select a GPIO obviously requires that the GPIO
762device is probed. This is OK when used by common, core devices such as GPIO,
763clock, interrupts, reset and the like.
764
765If your device relies on its parent setting up a suitable address space, so
766that dev_read_addr() works correctly, then make sure that the parent device
767has its setup code in ofdata_to_platdata(). If it has it in the probe method,
768then you cannot call dev_read_addr() from the child device's
769ofdata_to_platdata() method. Move it to probe() instead. Buses like PCI can
770fall afoul of this rule.
771
772Activation/probe
773^^^^^^^^^^^^^^^^
774
775When a device needs to be used, U-Boot activates it, by first reading ofdata
776as above and then following these steps (see device_probe()):
777
778 1. All parent devices are probed. It is not possible to activate a device
Simon Glass22ec1362014-06-11 23:29:55 -0600779 unless its predecessors (all the way up to the root device) are activated.
780 This means (for example) that an I2C driver will require that its bus
781 be activated.
782
Simon Glassb0dcc872020-04-05 15:38:19 -0600783 2. The device's sequence number is assigned, either the requested one
Simon Glass5a66a8f2014-07-23 06:55:12 -0600784 (assuming no conflicts) or the next available one if there is a conflict
785 or nothing particular is requested.
786
Simon Glassb0dcc872020-04-05 15:38:19 -0600787 4. The device's probe() method is called. This should do anything that
Simon Glass22ec1362014-06-11 23:29:55 -0600788 is required by the device to get it going. This could include checking
789 that the hardware is actually present, setting up clocks for the
790 hardware and setting up hardware registers to initial values. The code
791 in probe() can access:
792
793 - platform data in dev->platdata (for configuration)
794 - private data in dev->priv (for run-time state)
795 - uclass data in dev->uclass_priv (for things the uclass stores
796 about this device)
797
798 Note: If you don't use priv_auto_alloc_size then you will need to
799 allocate the priv space here yourself. The same applies also to
800 platdata_auto_alloc_size. Remember to free them in the remove() method.
801
Simon Glassb0dcc872020-04-05 15:38:19 -0600802 5. The device is marked 'activated'
Simon Glass22ec1362014-06-11 23:29:55 -0600803
Bin Menged205e62019-07-18 00:33:49 -0700804 10. The uclass's post_probe() method is called, if one exists. This may
Simon Glass22ec1362014-06-11 23:29:55 -0600805 cause the uclass to do some housekeeping to record the device as
806 activated and 'known' by the uclass.
807
Bin Menged205e62019-07-18 00:33:49 -0700808Running stage
809^^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600810
811The device is now activated and can be used. From now until it is removed
812all of the above structures are accessible. The device appears in the
813uclass's list of devices (so if the device is in UCLASS_GPIO it will appear
814as a device in the GPIO uclass). This is the 'running' state of the device.
815
Bin Menged205e62019-07-18 00:33:49 -0700816Removal stage
817^^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600818
819When the device is no-longer required, you can call device_remove() to
820remove it. This performs the probe steps in reverse:
821
Bin Menged205e62019-07-18 00:33:49 -0700822 1. The uclass's pre_remove() method is called, if one exists. This may
Simon Glass22ec1362014-06-11 23:29:55 -0600823 cause the uclass to do some housekeeping to record the device as
824 deactivated and no-longer 'known' by the uclass.
825
Bin Menged205e62019-07-18 00:33:49 -0700826 2. All the device's children are removed. It is not permitted to have
Simon Glass22ec1362014-06-11 23:29:55 -0600827 an active child device with a non-active parent. This means that
828 device_remove() is called for all the children recursively at this point.
829
Bin Menged205e62019-07-18 00:33:49 -0700830 3. The device's remove() method is called. At this stage nothing has been
Simon Glass22ec1362014-06-11 23:29:55 -0600831 deallocated so platform data, private data and the uclass data will all
832 still be present. This is where the hardware can be shut down. It is
833 intended that the device be completely inactive at this point, For U-Boot
834 to be sure that no hardware is running, it should be enough to remove
835 all devices.
836
Bin Menged205e62019-07-18 00:33:49 -0700837 4. The device memory is freed (platform data, private data, uclass data,
Simon Glasse59f4582014-07-23 06:55:20 -0600838 parent data).
Simon Glass22ec1362014-06-11 23:29:55 -0600839
840 Note: Because the platform data for a U_BOOT_DEVICE() is defined with a
841 static pointer, it is not de-allocated during the remove() method. For
842 a device instantiated using the device tree data, the platform data will
843 be dynamically allocated, and thus needs to be deallocated during the
844 remove() method, either:
845
Bin Menged205e62019-07-18 00:33:49 -0700846 - if the platdata_auto_alloc_size is non-zero, the deallocation
847 happens automatically within the driver model core; or
Simon Glass22ec1362014-06-11 23:29:55 -0600848
Bin Menged205e62019-07-18 00:33:49 -0700849 - when platdata_auto_alloc_size is 0, both the allocation (in probe()
850 or preferably ofdata_to_platdata()) and the deallocation in remove()
851 are the responsibility of the driver author.
Simon Glass22ec1362014-06-11 23:29:55 -0600852
Bin Menged205e62019-07-18 00:33:49 -0700853 5. The device sequence number is set to -1, meaning that it no longer
Simon Glass5a66a8f2014-07-23 06:55:12 -0600854 has an allocated sequence. If the device is later reactivated and that
855 sequence number is still free, it may well receive the name sequence
856 number again. But from this point, the sequence number previously used
857 by this device will no longer exist (think of SPI bus 2 being removed
858 and bus 2 is no longer available for use).
859
Bin Menged205e62019-07-18 00:33:49 -0700860 6. The device is marked inactive. Note that it is still bound, so the
Simon Glass22ec1362014-06-11 23:29:55 -0600861 device structure itself is not freed at this point. Should the device be
862 activated again, then the cycle starts again at step 2 above.
863
Bin Menged205e62019-07-18 00:33:49 -0700864Unbind stage
865^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600866
867The device is unbound. This is the step that actually destroys the device.
868If a parent has children these will be destroyed first. After this point
869the device does not exist and its memory has be deallocated.
870
871
Simon Glass65c70532014-02-26 15:59:17 -0700872Data Structures
873---------------
874
875Driver model uses a doubly-linked list as the basic data structure. Some
876nodes have several lists running through them. Creating a more efficient
877data structure might be worthwhile in some rare cases, once we understand
878what the bottlenecks are.
879
880
881Changes since v1
882----------------
883
884For the record, this implementation uses a very similar approach to the
885original patches, but makes at least the following changes:
886
Chris Packham34e4a2e2014-06-07 10:35:55 +1200887- Tried to aggressively remove boilerplate, so that for most drivers there
Bin Menged205e62019-07-18 00:33:49 -0700888 is little or no 'driver model' code to write.
Simon Glass65c70532014-02-26 15:59:17 -0700889- Moved some data from code into data structure - e.g. store a pointer to
Bin Menged205e62019-07-18 00:33:49 -0700890 the driver operations structure in the driver, rather than passing it
891 to the driver bind function.
Simon Glassae7f4512014-06-11 23:29:45 -0600892- Rename some structures to make them more similar to Linux (struct udevice
Bin Menged205e62019-07-18 00:33:49 -0700893 instead of struct instance, struct platdata, etc.)
Simon Glass65c70532014-02-26 15:59:17 -0700894- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
Bin Menged205e62019-07-18 00:33:49 -0700895 this concept relates to a class of drivers (or a subsystem). We shouldn't
896 use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
897 better than 'core'.
Heiko Schocher54c5d082014-05-22 12:43:05 +0200898- Remove 'struct driver_instance' and just use a single 'struct udevice'.
Bin Menged205e62019-07-18 00:33:49 -0700899 This removes a level of indirection that doesn't seem necessary.
Simon Glass65c70532014-02-26 15:59:17 -0700900- Built in device tree support, to avoid the need for platdata
901- Removed the concept of driver relocation, and just make it possible for
Bin Menged205e62019-07-18 00:33:49 -0700902 the new driver (created after relocation) to access the old driver data.
903 I feel that relocation is a very special case and will only apply to a few
904 drivers, many of which can/will just re-init anyway. So the overhead of
905 dealing with this might not be worth it.
Simon Glass65c70532014-02-26 15:59:17 -0700906- Implemented a GPIO system, trying to keep it simple
907
908
Simon Glass00606d72014-07-23 06:55:03 -0600909Pre-Relocation Support
910----------------------
911
912For pre-relocation we simply call the driver model init function. Only
Bin Meng1a6bd472018-10-24 06:36:40 -0700913drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc'
914property are initialised prior to relocation. This helps to reduce the driver
915model overhead. This flag applies to SPL and TPL as well, if device tree is
916enabled (CONFIG_OF_CONTROL) there.
917
918Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc'
919property can provide better control granularity on which device is bound
920before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all
921devices with the same driver are bound, which requires allocation a large
922amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the
923only way for statically declared devices via U_BOOT_DEVICE() to be bound
924prior to relocation.
Simon Glass00606d72014-07-23 06:55:03 -0600925
Heiko Stübner27326c72017-02-18 19:46:21 +0100926It is possible to limit this to specific relocation steps, by using
927the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags
Simon Glass06f94462018-10-01 12:22:18 -0600928in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper'
929which means that it will be processed (and a driver bound) in U-Boot proper
930prior to relocation, but will not be available in SPL or TPL.
Heiko Stübner27326c72017-02-18 19:46:21 +0100931
Patrick Delaunay54e12232019-05-21 19:19:13 +0200932To reduce the size of SPL and TPL, only the nodes with pre-relocation properties
933('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in their
934device trees (see README.SPL for details); the remaining nodes are always bound.
935
Simon Glass00606d72014-07-23 06:55:03 -0600936Then post relocation we throw that away and re-init driver model again.
937For drivers which require some sort of continuity between pre- and
938post-relocation devices, we can provide access to the pre-relocation
939device pointers, but this is not currently implemented (the root device
940pointer is saved but not made available through the driver model API).
941
942
Simon Glass38687ae2014-11-10 17:16:54 -0700943SPL Support
944-----------
945
946Driver model can operate in SPL. Its efficient implementation and small code
947size provide for a small overhead which is acceptable for all but the most
948constrained systems.
949
950To enable driver model in SPL, define CONFIG_SPL_DM. You might want to
951consider the following option also. See the main README for more details.
952
953 - CONFIG_SYS_MALLOC_SIMPLE
954 - CONFIG_DM_WARN
955 - CONFIG_DM_DEVICE_REMOVE
956 - CONFIG_DM_STDIO
957
958
959Enabling Driver Model
960---------------------
961
962Driver model is being brought into U-Boot gradually. As each subsystems gets
963support, a uclass is created and a CONFIG to enable use of driver model for
964that subsystem.
965
966For example CONFIG_DM_SERIAL enables driver model for serial. With that
967defined, the old serial support is not enabled, and your serial driver must
968conform to driver model. With that undefined, the old serial support is
969enabled and driver model is not available for serial. This means that when
970you convert a driver, you must either convert all its boards, or provide for
971the driver to be compiled both with and without driver model (generally this
972is not very hard).
973
974See the main README for full details of the available driver model CONFIG
975options.
976
977
Simon Glass65c70532014-02-26 15:59:17 -0700978Things to punt for later
979------------------------
980
Simon Glass65c70532014-02-26 15:59:17 -0700981Uclasses are statically numbered at compile time. It would be possible to
982change this to dynamic numbering, but then we would require some sort of
983lookup service, perhaps searching by name. This is slightly less efficient
984so has been left out for now. One small advantage of dynamic numbering might
985be fewer merge conflicts in uclass-id.h.