blob: b0e6337030a186c04380054204218a123f2c2951 [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
Simon Glasscaa4daa2020-12-03 16:55:18 -070062handles parameter data and plat (data which tells the driver how
Simon Glass65c70532014-02-26 15:59:17 -070063to 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 {
Simon Glassc69cda22020-12-03 16:55:20 -0700285 const struct dm_demo_pdata *pdata = dev_get_plat(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
Simon Glassd1998a92020-12-03 16:55:21 -0700336 * of_to_plat - convert device tree data to plat - see later
Bin Menged205e62019-07-18 00:33:49 -0700337 * 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
Simon Glassd1998a92020-12-03 16:55:21 -0700340The sequence to get a device to work is bind, of_to_plat (if using
Simon Glass65c70532014-02-26 15:59:17 -0700341device 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
Simon Glasscaa4daa2020-12-03 16:55:18 -0700399Drivers can access their data via dev->info->plat. 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",
Simon Glasscaa4daa2020-12-03 16:55:18 -0700413 .plat = &red_square,
Simon Glass65c70532014-02-26 15:59:17 -0700414 },
415 };
416
417 demo1 = driver_bind(root, &info[0]);
418
419
420Device Tree
421-----------
422
Simon Glasscaa4daa2020-12-03 16:55:18 -0700423While plat 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
Simon Glass20e442a2020-12-28 20:34:54 -0700425sending patches which make use of the U_BOOT_DRVINFO() macro unless strictly
Simon Glass97f3ee32015-07-06 12:54:22 -0600426necessary.
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 Glass20e442a2020-12-28 20:34:54 -0700439This means that instead of having lots of U_BOOT_DRVINFO() declarations in
Simon Glass22ec1362014-06-11 23:29:55 -0600440the 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 Glasscaa4daa2020-12-03 16:55:18 -0700451 .plat_auto = sizeof(struct dm_test_pdata),
Simon Glassd1998a92020-12-03 16:55:21 -0700452 .of_to_plat = testfdt_of_to_plat,
Simon Glass65c70532014-02-26 15:59:17 -0700453
Simon Glasscaa4daa2020-12-03 16:55:18 -0700454The 'auto' feature allowed space for the plat to be allocated
Simon Glassd1998a92020-12-03 16:55:21 -0700455and zeroed before the driver's of_to_plat() method is called. The
456of_to_plat() method, which the driver write supplies, should parse
Simon Glasscaa4daa2020-12-03 16:55:18 -0700457the device tree node for this device and place it in dev->plat. Thus
Simon Glass22ec1362014-06-11 23:29:55 -0600458when 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
Simon Glassd1998a92020-12-03 16:55:21 -0700461Note that both methods are optional. If you provide an of_to_plat
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
Simon Glasscaa4daa2020-12-03 16:55:18 -0700466If you don't want to have the plat automatically allocated then you
467can leave out plat_auto. In this case you can use malloc
Simon Glassd1998a92020-12-03 16:55:21 -0700468in your of_to_plat (or probe) method to allocate the required memory,
Simon Glass65c70532014-02-26 15:59:17 -0700469and 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
Simon Glass5e663382020-12-16 21:20:33 -0700518Where a device gets its sequence number is controlled by the DM_SEQ_ALIAS
519Kconfig option, which can have a different value in U-Boot proper and SPL.
520If this option is not set, aliases are ignored.
Simon Glass5a66a8f2014-07-23 06:55:12 -0600521
Simon Glass5e663382020-12-16 21:20:33 -0700522Even if CONFIG_DM_SEQ_ALIAS is enabled, the uclass must still have the
523DM_UC_FLAG_SEQ_ALIAS flag set, for its devices to be sequenced by aliases.
524
525With those options set, devices with an alias (e.g. "serial2") will get that
526sequence number (e.g. 2). Other devices get the next available number after all
527aliases and all existing numbers. This means that if there is just a single
528alias "serial2", unaliased serial devices will be assigned 3 or more, with 0 and
5291 being unused.
530
531If CONFIG_DM_SEQ_ALIAS or DM_UC_FLAG_SEQ_ALIAS are not set, all devices will get
532sequence numbers in a simple ordering starting from 0. To find the next number
533to allocate, driver model scans through to find the maximum existing number,
534then uses the next one. It does not attempt to fill in gaps.
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@22230000";
540 };
Simon Glass5a66a8f2014-07-23 06:55:12 -0600541
542This indicates that in the uclass called "serial", the named node
543("/serial@22230000") will be given sequence number 2. Any command or driver
544which requests serial device 2 will obtain this device.
545
Simon Glass9cc36a22015-01-25 08:27:05 -0700546More commonly you can use node references, which expand to the full path:
Simon Glass5a66a8f2014-07-23 06:55:12 -0600547
Bin Menged205e62019-07-18 00:33:49 -0700548.. code-block:: none
549
550 aliases {
551 serial2 = &serial_2;
552 };
553 ...
554 serial_2: serial@22230000 {
555 ...
556 };
Simon Glass5a66a8f2014-07-23 06:55:12 -0600557
Simon Glass9cc36a22015-01-25 08:27:05 -0700558The alias resolves to the same string in this case, but this version is
559easier to read.
Simon Glass5a66a8f2014-07-23 06:55:12 -0600560
Simon Glass5e663382020-12-16 21:20:33 -0700561Device sequence numbers are resolved when a device is bound and the number does
562not change for the life of the device.
Simon Glass5a66a8f2014-07-23 06:55:12 -0600563
Simon Glass5e663382020-12-16 21:20:33 -0700564There are some situations where the uclass must allocate sequence numbers,
565since a strictly increase sequence (with devicetree nodes bound first) is not
566suitable. An example of this is the PCI bus. In this case, you can set the
567uclass DM_UC_FLAG_NO_AUTO_SEQ flag. With this flag set, only devices with an
568alias will be assigned a number by driver model. The rest is left to the uclass
569to sort out, e.g. when enumerating the bus.
570
571Note that changing the sequence number for a device (e.g. in a driver) is not
572permitted. If it is felt to be necessary, ask on the mailing list.
Simon Glass5a66a8f2014-07-23 06:55:12 -0600573
Simon Glassa327dee2014-07-23 06:55:21 -0600574Bus Drivers
575-----------
576
577A common use of driver model is to implement a bus, a device which provides
578access to other devices. Example of buses include SPI and I2C. Typically
579the bus provides some sort of transport or translation that makes it
580possible to talk to the devices on the bus.
581
Simon Glass2017aae2015-01-25 08:27:20 -0700582Driver model provides some useful features to help with implementing buses.
583Firstly, a bus can request that its children store some 'parent data' which
584can be used to keep track of child state. Secondly, the bus can define
585methods which are called when a child is probed or removed. This is similar
586to the methods the uclass driver provides. Thirdly, per-child platform data
587can be provided to specify things like the child's address on the bus. This
588persists across child probe()/remove() cycles.
589
590For consistency and ease of implementation, the bus uclass can specify the
591per-child platform data, so that it can be the same for all children of buses
592in that uclass. There are also uclass methods which can be called when
593children are bound and probed.
Simon Glassa327dee2014-07-23 06:55:21 -0600594
595Here an explanation of how a bus fits with a uclass may be useful. Consider
596a USB bus with several devices attached to it, each from a different (made
Bin Menged205e62019-07-18 00:33:49 -0700597up) uclass::
Simon Glassa327dee2014-07-23 06:55:21 -0600598
599 xhci_usb (UCLASS_USB)
Heinrich Schuchardtda2fa6d2020-02-26 20:18:54 +0100600 eth (UCLASS_ETH)
Simon Glassa327dee2014-07-23 06:55:21 -0600601 camera (UCLASS_CAMERA)
602 flash (UCLASS_FLASH_STORAGE)
603
604Each of the devices is connected to a different address on the USB bus.
605The bus device wants to store this address and some other information such
606as the bus speed for each device.
607
Simon Glasscaa4daa2020-12-03 16:55:18 -0700608To achieve this, the bus device can use dev->parent_plat in each of its
Simon Glass2017aae2015-01-25 08:27:20 -0700609three children. This can be auto-allocated if the bus driver (or bus uclass)
Simon Glasscaa4daa2020-12-03 16:55:18 -0700610has a non-zero value for per_child_plat_auto. If not, then
Simon Glass2017aae2015-01-25 08:27:20 -0700611the bus device or uclass can allocate the space itself before the child
612device is probed.
Simon Glassa327dee2014-07-23 06:55:21 -0600613
614Also the bus driver can define the child_pre_probe() and child_post_remove()
615methods to allow it to do some processing before the child is activated or
616after it is deactivated.
617
Simon Glass2017aae2015-01-25 08:27:20 -0700618Similarly the bus uclass can define the child_post_bind() method to obtain
619the per-child platform data from the device tree and set it up for the child.
620The bus uclass can also provide a child_pre_probe() method. Very often it is
621the bus uclass that controls these features, since it avoids each driver
622having to do the same processing. Of course the driver can still tweak and
623override these activities.
624
Simon Glassa327dee2014-07-23 06:55:21 -0600625Note that the information that controls this behaviour is in the bus's
626driver, not the child's. In fact it is possible that child has no knowledge
627that it is connected to a bus. The same child device may even be used on two
628different bus types. As an example. the 'flash' device shown above may also
Bin Menged205e62019-07-18 00:33:49 -0700629be connected on a SATA bus or standalone with no bus::
Simon Glassa327dee2014-07-23 06:55:21 -0600630
631 xhci_usb (UCLASS_USB)
632 flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus
633
Heinrich Schuchardt2f8f5e22020-05-20 23:27:27 +0200634 sata (UCLASS_AHCI)
Simon Glassa327dee2014-07-23 06:55:21 -0600635 flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by SATA bus
636
637 flash (UCLASS_FLASH_STORAGE) - no parent data/methods (not on a bus)
638
639Above you can see that the driver for xhci_usb/sata controls the child's
640bus methods. In the third example the device is not on a bus, and therefore
641will not have these methods at all. Consider the case where the flash
642device defines child methods. These would be used for *its* children, and
643would be quite separate from the methods defined by the driver for the bus
644that the flash device is connetced to. The act of attaching a device to a
645parent device which is a bus, causes the device to start behaving like a
646bus device, regardless of its own views on the matter.
647
648The uclass for the device can also contain data private to that uclass.
Dario Binacchicea8f2c2020-06-04 14:58:13 +0200649But note that each device on the bus may be a member of a different
Simon Glassa327dee2014-07-23 06:55:21 -0600650uclass, and this data has nothing to do with the child data for each child
Simon Glass2017aae2015-01-25 08:27:20 -0700651on the bus. It is the bus' uclass that controls the child with respect to
652the bus.
Simon Glassa327dee2014-07-23 06:55:21 -0600653
654
Simon Glass22ec1362014-06-11 23:29:55 -0600655Driver Lifecycle
656----------------
657
658Here are the stages that a device goes through in driver model. Note that all
659methods mentioned here are optional - e.g. if there is no probe() method for
660a device then it will not be called. A simple device may have very few
661methods actually defined.
662
Bin Menged205e62019-07-18 00:33:49 -0700663Bind stage
664^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600665
Stephen Warrendaac3bf2016-05-11 15:26:24 -0600666U-Boot discovers devices using one of these two methods:
Simon Glass22ec1362014-06-11 23:29:55 -0600667
Simon Glass20e442a2020-12-28 20:34:54 -0700668- Scan the U_BOOT_DRVINFO() definitions. U-Boot looks up the name specified
Bin Menged205e62019-07-18 00:33:49 -0700669 by each, to find the appropriate U_BOOT_DRIVER() definition. In this case,
Simon Glass20e442a2020-12-28 20:34:54 -0700670 there is no path by which driver_data may be provided, but the U_BOOT_DRVINFO()
Simon Glasscaa4daa2020-12-03 16:55:18 -0700671 may provide plat.
Simon Glass22ec1362014-06-11 23:29:55 -0600672
Bin Menged205e62019-07-18 00:33:49 -0700673- Scan through the device tree definitions. U-Boot looks at top-level
674 nodes in the the device tree. It looks at the compatible string in each node
675 and uses the of_match table of the U_BOOT_DRIVER() structure to find the
676 right driver for each node. In this case, the of_match table may provide a
Simon Glasscaa4daa2020-12-03 16:55:18 -0700677 driver_data value, but plat cannot be provided until later.
Stephen Warrendaac3bf2016-05-11 15:26:24 -0600678
679For each device that is discovered, U-Boot then calls device_bind() to create a
680new device, initializes various core fields of the device object such as name,
681uclass & driver, initializes any optional fields of the device object that are
Simon Glasscaa4daa2020-12-03 16:55:18 -0700682applicable such as of_offset, driver_data & plat, and finally calls the
Stephen Warrendaac3bf2016-05-11 15:26:24 -0600683driver's bind() method if one is defined.
Simon Glass22ec1362014-06-11 23:29:55 -0600684
685At this point all the devices are known, and bound to their drivers. There
686is a 'struct udevice' allocated for all devices. However, nothing has been
687activated (except for the root device). Each bound device that was created
Simon Glass20e442a2020-12-28 20:34:54 -0700688from a U_BOOT_DRVINFO() declaration will hold the plat pointer specified
Simon Glass22ec1362014-06-11 23:29:55 -0600689in that declaration. For a bound device created from the device tree,
Simon Glasscaa4daa2020-12-03 16:55:18 -0700690plat will be NULL, but of_offset will be the offset of the device tree
Simon Glass22ec1362014-06-11 23:29:55 -0600691node that caused the device to be created. The uclass is set correctly for
692the device.
693
Simon Glass5e663382020-12-16 21:20:33 -0700694The device's sequence number is assigned, either the requested one or the next
695available one (after all aliases are processed) if nothing particular is
696requested.
697
Simon Glass22ec1362014-06-11 23:29:55 -0600698The device's bind() method is permitted to perform simple actions, but
699should not scan the device tree node, not initialise hardware, nor set up
700structures or allocate memory. All of these tasks should be left for
701the probe() method.
702
703Note that compared to Linux, U-Boot's driver model has a separate step of
704probe/remove which is independent of bind/unbind. This is partly because in
705U-Boot it may be expensive to probe devices and we don't want to do it until
706they are needed, or perhaps until after relocation.
707
Simon Glassb0dcc872020-04-05 15:38:19 -0600708Reading ofdata
709^^^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600710
Simon Glassb0dcc872020-04-05 15:38:19 -0600711Most devices have data in the device tree which they can read to find out the
712base address of hardware registers and parameters relating to driver
713operation. This is called 'ofdata' (Open-Firmware data).
714
Simon Glassd1998a92020-12-03 16:55:21 -0700715The device's of_to_plat() implemnents allocation and reading of
Simon Glasscaa4daa2020-12-03 16:55:18 -0700716plat. A parent's ofdata is always read before a child.
Simon Glassb0dcc872020-04-05 15:38:19 -0600717
718The steps are:
Simon Glass22ec1362014-06-11 23:29:55 -0600719
Simon Glass41575d82020-12-03 16:55:17 -0700720 1. If priv_auto is non-zero, then the device-private space
Simon Glass22ec1362014-06-11 23:29:55 -0600721 is allocated for the device and zeroed. It will be accessible as
722 dev->priv. The driver can put anything it likes in there, but should use
723 it for run-time information, not platform data (which should be static
724 and known before the device is probed).
725
Simon Glasscaa4daa2020-12-03 16:55:18 -0700726 2. If plat_auto is non-zero, then the platform data space
Simon Glass22ec1362014-06-11 23:29:55 -0600727 is allocated. This is only useful for device tree operation, since
Heinrich Schuchardt54894482021-01-31 11:04:12 +0100728 otherwise you would have to specify the platform data in the
Simon Glass20e442a2020-12-28 20:34:54 -0700729 U_BOOT_DRVINFO() declaration. The space is allocated for the device and
Simon Glasscaa4daa2020-12-03 16:55:18 -0700730 zeroed. It will be accessible as dev->plat.
Simon Glass22ec1362014-06-11 23:29:55 -0600731
Simon Glass41575d82020-12-03 16:55:17 -0700732 3. If the device's uclass specifies a non-zero per_device_auto,
Simon Glass22ec1362014-06-11 23:29:55 -0600733 then this space is allocated and zeroed also. It is allocated for and
734 stored in the device, but it is uclass data. owned by the uclass driver.
735 It is possible for the device to access it.
736
Simon Glass41575d82020-12-03 16:55:17 -0700737 4. If the device's immediate parent specifies a per_child_auto
Simon Glasse59f4582014-07-23 06:55:20 -0600738 then this space is allocated. This is intended for use by the parent
739 device to keep track of things related to the child. For example a USB
740 flash stick attached to a USB host controller would likely use this
741 space. The controller can hold information about the USB state of each
742 of its children.
743
Simon Glassd1998a92020-12-03 16:55:21 -0700744 5. If the driver provides an of_to_plat() method, then this is
Simon Glassb0dcc872020-04-05 15:38:19 -0600745 called to convert the device tree data into platform data. This should
746 do various calls like dev_read_u32(dev, ...) to access the node and store
Simon Glasscaa4daa2020-12-03 16:55:18 -0700747 the resulting information into dev->plat. After this point, the device
Simon Glassb0dcc872020-04-05 15:38:19 -0600748 works the same way whether it was bound using a device tree node or
Simon Glass20e442a2020-12-28 20:34:54 -0700749 U_BOOT_DRVINFO() structure. In either case, the platform data is now stored
Simon Glasscaa4daa2020-12-03 16:55:18 -0700750 in the plat structure. Typically you will use the
751 plat_auto feature to specify the size of the platform data
Simon Glassb0dcc872020-04-05 15:38:19 -0600752 structure, and U-Boot will automatically allocate and zero it for you before
Simon Glassd1998a92020-12-03 16:55:21 -0700753 entry to of_to_plat(). But if not, you can allocate it yourself in
754 of_to_plat(). Note that it is preferable to do all the device tree
755 decoding in of_to_plat() rather than in probe(). (Apart from the
Simon Glassb0dcc872020-04-05 15:38:19 -0600756 ugliness of mixing configuration and run-time data, one day it is possible
757 that U-Boot will cache platform data for devices which are regularly
758 de/activated).
759
Simon Glasscaa4daa2020-12-03 16:55:18 -0700760 6. The device is marked 'plat valid'.
Simon Glassb0dcc872020-04-05 15:38:19 -0600761
762Note that ofdata reading is always done (for a child and all its parents)
763before probing starts. Thus devices go through two distinct states when
764probing: reading platform data and actually touching the hardware to bring
765the device up.
766
767Having probing separate from ofdata-reading helps deal with of-platdata, where
768the probe() method is common to both DT/of-platdata operation, but the
Simon Glassd1998a92020-12-03 16:55:21 -0700769of_to_plat() method is implemented differently.
Simon Glassb0dcc872020-04-05 15:38:19 -0600770
771Another case has come up where this separate is useful. Generation of ACPI
772tables uses the of-platdata but does not want to probe the device. Probing
773would cause U-Boot to violate one of its design principles, viz that it
774should only probe devices that are used. For ACPI we want to generate a
775table for each device, even if U-Boot does not use it. In fact it may not
776even be possible to probe the device - e.g. an SD card which is not
777present will cause an error on probe, yet we still must tell Linux about
778the SD card connector in case it is used while Linux is running.
779
Simon Glassd1998a92020-12-03 16:55:21 -0700780It is important that the of_to_plat() method does not actually probe
Simon Glassb0dcc872020-04-05 15:38:19 -0600781the device itself. However there are cases where other devices must be probed
Simon Glassd1998a92020-12-03 16:55:21 -0700782in the of_to_plat() method. An example is where a device requires a
Simon Glassb0dcc872020-04-05 15:38:19 -0600783GPIO for it to operate. To select a GPIO obviously requires that the GPIO
784device is probed. This is OK when used by common, core devices such as GPIO,
785clock, interrupts, reset and the like.
786
787If your device relies on its parent setting up a suitable address space, so
788that dev_read_addr() works correctly, then make sure that the parent device
Simon Glassd1998a92020-12-03 16:55:21 -0700789has its setup code in of_to_plat(). If it has it in the probe method,
Simon Glassb0dcc872020-04-05 15:38:19 -0600790then you cannot call dev_read_addr() from the child device's
Simon Glassd1998a92020-12-03 16:55:21 -0700791of_to_plat() method. Move it to probe() instead. Buses like PCI can
Simon Glassb0dcc872020-04-05 15:38:19 -0600792fall afoul of this rule.
793
794Activation/probe
795^^^^^^^^^^^^^^^^
796
797When a device needs to be used, U-Boot activates it, by first reading ofdata
798as above and then following these steps (see device_probe()):
799
800 1. All parent devices are probed. It is not possible to activate a device
Simon Glass22ec1362014-06-11 23:29:55 -0600801 unless its predecessors (all the way up to the root device) are activated.
802 This means (for example) that an I2C driver will require that its bus
803 be activated.
804
Simon Glass5e663382020-12-16 21:20:33 -0700805 2. The device's probe() method is called. This should do anything that
Simon Glass22ec1362014-06-11 23:29:55 -0600806 is required by the device to get it going. This could include checking
807 that the hardware is actually present, setting up clocks for the
808 hardware and setting up hardware registers to initial values. The code
809 in probe() can access:
810
Simon Glasscaa4daa2020-12-03 16:55:18 -0700811 - platform data in dev->plat (for configuration)
Simon Glass22ec1362014-06-11 23:29:55 -0600812 - private data in dev->priv (for run-time state)
813 - uclass data in dev->uclass_priv (for things the uclass stores
814 about this device)
815
Simon Glass41575d82020-12-03 16:55:17 -0700816 Note: If you don't use priv_auto then you will need to
Simon Glass22ec1362014-06-11 23:29:55 -0600817 allocate the priv space here yourself. The same applies also to
Simon Glasscaa4daa2020-12-03 16:55:18 -0700818 plat_auto. Remember to free them in the remove() method.
Simon Glass22ec1362014-06-11 23:29:55 -0600819
Simon Glass5e663382020-12-16 21:20:33 -0700820 3. The device is marked 'activated'
Simon Glass22ec1362014-06-11 23:29:55 -0600821
Simon Glass5e663382020-12-16 21:20:33 -0700822 4. The uclass's post_probe() 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 activated and 'known' by the uclass.
825
Bin Menged205e62019-07-18 00:33:49 -0700826Running stage
827^^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600828
829The device is now activated and can be used. From now until it is removed
830all of the above structures are accessible. The device appears in the
831uclass's list of devices (so if the device is in UCLASS_GPIO it will appear
832as a device in the GPIO uclass). This is the 'running' state of the device.
833
Bin Menged205e62019-07-18 00:33:49 -0700834Removal stage
835^^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600836
837When the device is no-longer required, you can call device_remove() to
838remove it. This performs the probe steps in reverse:
839
Bin Menged205e62019-07-18 00:33:49 -0700840 1. The uclass's pre_remove() method is called, if one exists. This may
Simon Glass22ec1362014-06-11 23:29:55 -0600841 cause the uclass to do some housekeeping to record the device as
842 deactivated and no-longer 'known' by the uclass.
843
Bin Menged205e62019-07-18 00:33:49 -0700844 2. All the device's children are removed. It is not permitted to have
Simon Glass22ec1362014-06-11 23:29:55 -0600845 an active child device with a non-active parent. This means that
846 device_remove() is called for all the children recursively at this point.
847
Bin Menged205e62019-07-18 00:33:49 -0700848 3. The device's remove() method is called. At this stage nothing has been
Simon Glass22ec1362014-06-11 23:29:55 -0600849 deallocated so platform data, private data and the uclass data will all
850 still be present. This is where the hardware can be shut down. It is
851 intended that the device be completely inactive at this point, For U-Boot
852 to be sure that no hardware is running, it should be enough to remove
853 all devices.
854
Bin Menged205e62019-07-18 00:33:49 -0700855 4. The device memory is freed (platform data, private data, uclass data,
Simon Glasse59f4582014-07-23 06:55:20 -0600856 parent data).
Simon Glass22ec1362014-06-11 23:29:55 -0600857
Simon Glass20e442a2020-12-28 20:34:54 -0700858 Note: Because the platform data for a U_BOOT_DRVINFO() is defined with a
Simon Glass22ec1362014-06-11 23:29:55 -0600859 static pointer, it is not de-allocated during the remove() method. For
860 a device instantiated using the device tree data, the platform data will
861 be dynamically allocated, and thus needs to be deallocated during the
862 remove() method, either:
863
Heinrich Schuchardt54894482021-01-31 11:04:12 +0100864 - if the plat_auto is non-zero, the deallocation happens automatically
865 within the driver model core in the unbind stage; or
Simon Glass22ec1362014-06-11 23:29:55 -0600866
Simon Glasscaa4daa2020-12-03 16:55:18 -0700867 - when plat_auto is 0, both the allocation (in probe()
Simon Glassd1998a92020-12-03 16:55:21 -0700868 or preferably of_to_plat()) and the deallocation in remove()
Bin Menged205e62019-07-18 00:33:49 -0700869 are the responsibility of the driver author.
Simon Glass22ec1362014-06-11 23:29:55 -0600870
Simon Glass5e663382020-12-16 21:20:33 -0700871 5. The device is marked inactive. Note that it is still bound, so the
Simon Glass22ec1362014-06-11 23:29:55 -0600872 device structure itself is not freed at this point. Should the device be
873 activated again, then the cycle starts again at step 2 above.
874
Bin Menged205e62019-07-18 00:33:49 -0700875Unbind stage
876^^^^^^^^^^^^
Simon Glass22ec1362014-06-11 23:29:55 -0600877
878The device is unbound. This is the step that actually destroys the device.
879If a parent has children these will be destroyed first. After this point
880the device does not exist and its memory has be deallocated.
881
882
Simon Glass7a3c6282021-01-24 14:32:48 -0700883Special cases for removal
884-------------------------
885
886Some devices need to do clean-up before the OS is called. For example, a USB
887driver may want to stop the bus. This can be done in the remove() method.
888Some special flags are used to determine whether to remove the device:
889
890 DM_FLAG_OS_PREPARE - indicates that the device needs to get ready for OS
891 boot. The device will be removed just before the OS is booted
892 DM_REMOVE_ACTIVE_DMA - indicates that the device uses DMA. This is
893 effectively the same as DM_FLAG_OS_PREPARE, so the device is removed
894 before the OS is booted
895 DM_FLAG_VITAL - indicates that the device is 'vital' to the operation of
896 other devices. It is possible to remove this device after all regular
897 devices are removed. This is useful e.g. for a clock, which need to
898 be active during the device-removal phase.
899
900The dm_remove_devices_flags() function can be used to remove devices based on
901their driver flags.
902
Simon Glass42a26682021-03-25 10:26:03 +1300903
904Error codes
905-----------
906
907Driver model tries to use errors codes in a consistent way, as follows:
908
909\-EAGAIN
910 Try later, e.g. dependencies not ready
911
912\-EINVAL
913 Invalid argument, such as `dev_read_...()` failed or any other
914 devicetree-related access. Also used when a driver method is passed an
915 argument it considers invalid or does not support.
916
917\-EIO
918 Failed to perform an I/O operation. This is used when a local device
919 (i.e. part of the SOC) does not work as expected. Use -EREMOTEIO for
920 failures to talk to a separate device, e.g. over an I2C or SPI
921 channel.
922
923\-ENODEV
924 Do not bind the device. This should not be used to indicate an
925 error probing the device or for any other purpose, lest driver model get
926 confused. Using `-ENODEV` inside a driver method makes no sense, since
927 clearly there is a device.
928
929\-ENOENT
930 Entry or object not found. This is used when a device, file or directory
931 cannot be found (e.g. when looked up by name), It can also indicate a
932 missing devicetree subnode.
933
934\-ENOMEM
935 Out of memory
936
937\-ENOSPC
938 Ran out of space (e.g. in a buffer or limited-size array)
939
940\-ENOSYS
941 Function not implemented. This is returned by uclasses where the driver does
942 not implement a particular method. It can also be returned by drivers when
943 a particular sub-method is not implemented. This is widely checked in the
944 wider code base, where a feature may or may not be compiled into U-Boot. It
945 indicates that the feature is not available, but this is often just normal
946 operation. Please do not use -ENOSUPP. If an incorrect or unknown argument
947 is provided to a method (e.g. an unknown clock ID), return -EINVAL.
948
949\-ENXIO
950 Couldn't find device/address. This is used when a device or address
951 could not be obtained or is not valid. It is often used to indicate a
952 different type of problem, if -ENOENT is already used for something else in
953 the driver.
954
955\-EPERM
956 This is -1 so some older code may use it as a generic error. This indicates
957 that an operation is not permitted, e.g. a security violation or policy
958 constraint. It is returned internally when binding devices before relocation,
959 if the device is not marked for pre-relocation use.
960
961\-EPFNOSUPPORT
962 Missing uclass. This is deliberately an uncommon error code so that it can
963 easily be distinguished. If you see this very early in U-Boot, it means that
964 a device exists with a particular uclass but the uclass does not (mostly
965 likely because it is not compiled in). Enable DEBUG in uclass.c or lists.c
966 to see which uclass ID or driver is causing the problem.
967
968\-EREMOTEIO
969 This indicates an error in talking to a peripheral over a comms link, such
970 as I2C or SPI. It might indicate that the device is not present or is not
971 responding as expected.
972
973\-ETIMEDOUT
974 Hardware access or some other operation has timed out. This is used where
975 there is an expected time of response and that was exceeded by enough of
976 a margin that there is probably something wrong.
977
978
979Less common ones:
980
981\-ECOMM
982 Not widely used, but similar to -EREMOTEIO. Can be useful as a secondary
983 error to distinguish the problem from -EREMOTEIO.
984
985\-EKEYREJECTED
986 Attempt to remove a device which does not match the removal flags. See
987 device_remove().
988
989\-EILSEQ
990 Devicetree read failure, specifically trying to read a string index which
991 does not exist, in a string-listg property
992
993\-ENOEXEC
994 Attempt to use a uclass method on a device not in that uclass. This is
995 seldom checked at present, since it is generally a programming error and a
996 waste of code space. A DEBUG-only check would be useful here.
997
998\-ENODATA
999 Devicetree read error, where a property exists but has no data associated
1000 with it
1001
1002\-EOVERFLOW
1003 Devicetree read error, where the property is longer than expected
1004
1005\-EPROBE_DEFER
1006 Attempt to remove a non-vital device when the removal flags indicate that
1007 only vital devices should be removed
1008
1009\-ERANGE
1010 Returned by regmap functions when arguments are out of range. This can be
1011 useful for disinguishing regmap errors from other errors obtained while
1012 probing devices.
1013
1014Drivers should use the same conventions so that things function as expected.
1015In particular, if a driver fails to probe, or a uclass operation fails, the
1016error code is the primary way to indicate what actually happened.
1017
1018Printing error messages in drivers is discouraged due to code size bloat and
1019since it can result in messages appearing in normal operation. For example, if
1020a command tries two different devices and uses whichever one probes correctly,
1021we don't want an error message displayed, even if the command itself might show
1022a warning or informational message. Ideally, messages in drivers should only be
1023displayed when debugging, e.g. by using log_debug() although in extreme cases
1024log_warning() or log_error() may be used.
1025
1026Error messages can be logged using `log_msg_ret()`, so that enabling
1027`CONFIG_LOG` and `CONFIG_LOG_ERROR_RETURN` shows a trace of error codes returned
1028through the call stack. That can be a handy way of quickly figuring out where
1029an error occurred. Get into the habit of return errors with
1030`return log_msg_ret("here", ret)` instead of just `return ret`. The string
1031just needs to be long enough to find in a single function, since a log record
1032stores (and can print with `CONFIG_LOGF_FUNC`) the function where it was
1033generated.
1034
1035
Simon Glass65c70532014-02-26 15:59:17 -07001036Data Structures
1037---------------
1038
1039Driver model uses a doubly-linked list as the basic data structure. Some
1040nodes have several lists running through them. Creating a more efficient
1041data structure might be worthwhile in some rare cases, once we understand
1042what the bottlenecks are.
1043
1044
1045Changes since v1
1046----------------
1047
1048For the record, this implementation uses a very similar approach to the
1049original patches, but makes at least the following changes:
1050
Chris Packham34e4a2e2014-06-07 10:35:55 +12001051- Tried to aggressively remove boilerplate, so that for most drivers there
Bin Menged205e62019-07-18 00:33:49 -07001052 is little or no 'driver model' code to write.
Simon Glass65c70532014-02-26 15:59:17 -07001053- Moved some data from code into data structure - e.g. store a pointer to
Bin Menged205e62019-07-18 00:33:49 -07001054 the driver operations structure in the driver, rather than passing it
1055 to the driver bind function.
Simon Glassae7f4512014-06-11 23:29:45 -06001056- Rename some structures to make them more similar to Linux (struct udevice
Simon Glasscaa4daa2020-12-03 16:55:18 -07001057 instead of struct instance, struct plat, etc.)
Simon Glass65c70532014-02-26 15:59:17 -07001058- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
Bin Menged205e62019-07-18 00:33:49 -07001059 this concept relates to a class of drivers (or a subsystem). We shouldn't
1060 use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
1061 better than 'core'.
Heiko Schocher54c5d082014-05-22 12:43:05 +02001062- Remove 'struct driver_instance' and just use a single 'struct udevice'.
Bin Menged205e62019-07-18 00:33:49 -07001063 This removes a level of indirection that doesn't seem necessary.
Simon Glasscaa4daa2020-12-03 16:55:18 -07001064- Built in device tree support, to avoid the need for plat
Simon Glass65c70532014-02-26 15:59:17 -07001065- Removed the concept of driver relocation, and just make it possible for
Bin Menged205e62019-07-18 00:33:49 -07001066 the new driver (created after relocation) to access the old driver data.
1067 I feel that relocation is a very special case and will only apply to a few
1068 drivers, many of which can/will just re-init anyway. So the overhead of
1069 dealing with this might not be worth it.
Simon Glass65c70532014-02-26 15:59:17 -07001070- Implemented a GPIO system, trying to keep it simple
1071
1072
Simon Glass00606d72014-07-23 06:55:03 -06001073Pre-Relocation Support
1074----------------------
1075
1076For pre-relocation we simply call the driver model init function. Only
Bin Meng1a6bd472018-10-24 06:36:40 -07001077drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc'
1078property are initialised prior to relocation. This helps to reduce the driver
1079model overhead. This flag applies to SPL and TPL as well, if device tree is
1080enabled (CONFIG_OF_CONTROL) there.
1081
1082Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc'
1083property can provide better control granularity on which device is bound
1084before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all
1085devices with the same driver are bound, which requires allocation a large
1086amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the
Simon Glass20e442a2020-12-28 20:34:54 -07001087only way for statically declared devices via U_BOOT_DRVINFO() to be bound
Bin Meng1a6bd472018-10-24 06:36:40 -07001088prior to relocation.
Simon Glass00606d72014-07-23 06:55:03 -06001089
Heiko Stübner27326c72017-02-18 19:46:21 +01001090It is possible to limit this to specific relocation steps, by using
1091the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags
Simon Glass06f94462018-10-01 12:22:18 -06001092in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper'
1093which means that it will be processed (and a driver bound) in U-Boot proper
1094prior to relocation, but will not be available in SPL or TPL.
Heiko Stübner27326c72017-02-18 19:46:21 +01001095
Patrick Delaunay54e12232019-05-21 19:19:13 +02001096To reduce the size of SPL and TPL, only the nodes with pre-relocation properties
1097('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in their
1098device trees (see README.SPL for details); the remaining nodes are always bound.
1099
Simon Glass00606d72014-07-23 06:55:03 -06001100Then post relocation we throw that away and re-init driver model again.
1101For drivers which require some sort of continuity between pre- and
1102post-relocation devices, we can provide access to the pre-relocation
1103device pointers, but this is not currently implemented (the root device
1104pointer is saved but not made available through the driver model API).
1105
1106
Simon Glass38687ae2014-11-10 17:16:54 -07001107SPL Support
1108-----------
1109
1110Driver model can operate in SPL. Its efficient implementation and small code
1111size provide for a small overhead which is acceptable for all but the most
1112constrained systems.
1113
1114To enable driver model in SPL, define CONFIG_SPL_DM. You might want to
1115consider the following option also. See the main README for more details.
1116
1117 - CONFIG_SYS_MALLOC_SIMPLE
1118 - CONFIG_DM_WARN
1119 - CONFIG_DM_DEVICE_REMOVE
1120 - CONFIG_DM_STDIO
1121
1122
1123Enabling Driver Model
1124---------------------
1125
1126Driver model is being brought into U-Boot gradually. As each subsystems gets
1127support, a uclass is created and a CONFIG to enable use of driver model for
1128that subsystem.
1129
1130For example CONFIG_DM_SERIAL enables driver model for serial. With that
1131defined, the old serial support is not enabled, and your serial driver must
1132conform to driver model. With that undefined, the old serial support is
1133enabled and driver model is not available for serial. This means that when
1134you convert a driver, you must either convert all its boards, or provide for
1135the driver to be compiled both with and without driver model (generally this
1136is not very hard).
1137
1138See the main README for full details of the available driver model CONFIG
1139options.
1140
1141
Simon Glass65c70532014-02-26 15:59:17 -07001142Things to punt for later
1143------------------------
1144
Simon Glass65c70532014-02-26 15:59:17 -07001145Uclasses are statically numbered at compile time. It would be possible to
1146change this to dynamic numbering, but then we would require some sort of
1147lookup service, perhaps searching by name. This is slightly less efficient
1148so has been left out for now. One small advantage of dynamic numbering might
1149be fewer merge conflicts in uclass-id.h.