doc/driver-model/README.txt

4 This README contains high-level information about driver model, a unified
5 way of declaring and accessing drivers in U-Boot. The original work was done
20 -----------
22 Uclass - a group of devices which operate in the same way. A uclass provides
28 Driver - some code which talks to a peripheral and presents a higher-level
31 Device - an instance of a driver, tied to a particular port or peripheral.
35 -------------
37 Build U-Boot sandbox and run it:
41    ./u-boot -d u-boot.dtb
43    (type 'reset' to exit U-Boot)
50    - simple: Just prints a message for hello, doesn't implement status
51    - shape: Prints shapes and reports number of characters printed as status
87 -----------------
89 The intent with driver model is that the core portion has 100% test coverage
90 in sandbox, and every uclass has its own test. As a move towards this, tests
91 are provided in test/dm. To run them, try:
93    ./test/py/test.py --bd sandbox --build -k ut_dm -v
97 (venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v
98 +make O=/root/u-boot/build-sandbox -s sandbox_defconfig
99 +make O=/root/u-boot/build-sandbox -s -j8
100 ============================= test session starts ==============================
101 platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/pyt…
103 rootdir: /root/u-boot, inifile:
106 test/py/tests/test_ut.py::test_ut_dm_init PASSED
107 test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED
108 test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED
109 test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED
110 test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED
111 test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED
112 test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED
113 test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED
114 test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED
115 test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED
116 test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED
117 test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED
118 test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED
119 test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED
120 test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED
121 test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED
122 test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED
123 test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED
124 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED
125 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED
126 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED
127 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED
128 test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED
129 test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED
130 test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED
131 test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED
132 test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED
133 test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED
134 test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED
135 test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED
136 test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED
137 test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED
138 test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED
139 test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED
140 test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED
141 test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED
142 test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED
143 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED
144 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED
145 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED
146 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED
147 test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED
148 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED
149 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED
150 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED
151 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED
152 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED
153 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED
154 test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED
155 test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED
156 test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED
157 test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED
158 test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED
159 test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED
160 test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED
161 test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED
162 test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED
163 test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED
164 test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED
165 test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED
166 test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED
167 test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED
168 test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED
169 test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED
170 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED
171 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED
172 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED
173 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED
174 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED
175 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED
176 test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED
177 test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED
178 test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED
179 test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED
180 test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED
181 test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED
182 test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED
183 test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED
184 test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED
185 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED
186 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED
187 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED
188 test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED
189 test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED
190 test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED
191 test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED
192 test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED
193 test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED
194 test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED
195 test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED
196 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED
197 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED
198 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED
199 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED
200 test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED
201 test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED
202 test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED
203 test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED
204 test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED
205 test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED
206 test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED
207 test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED
208 test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED
209 test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED
210 test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED
211 test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED
212 test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED
213 test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED
214 test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED
215 test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED
216 test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED
217 test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED
218 test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED
219 test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED
220 test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED
222 ======================= 84 tests deselected by '-kut_dm' =======================
226 -----------------
236 classes might be MMC, or GPIO, hashing or serial. The idea is that the
238 presents a unified view of all these devices to U-Boot.
254 The code for demo_hello() is in drivers/demo/demo-uclass.c:
260 	if (!ops->hello)
261 		return -ENOSYS;
263 	return ops->hello(dev, ch);
267 in drivers/demo/demo-simple.c:
274 	       pdata->colour, pdata->sides);
285 -----------------
288 drivers/demo/demo-shape.c):
318     bind - make the driver model aware of a device (bind it to its driver)
319     unbind - make the driver model forget the device
320     ofdata_to_platdata - convert device tree data to platdata - see later
321     probe - make a device ready for use
322     remove - remove a device so it cannot be used until probed again
329 -------------
333 *** platform-specific settings like the address of its registers, bus
336 *** being you need serial support in SPL and don't have enough SRAM for
337 *** the cut-down device tree and libfdt libraries) you should stay away
341 It provides the board-specific information to start up a device.
346 highly-complex SoCs it is common for the IP to come from an IP vendor, and
356 about this instance - e.g. the address of the register space. It may be that
357 one of the UARTS supports RS-485 operation - this can be added as a flag in
367    - The base address of the IP block's register space
368    - Configuration options, like:
369          - the SPI polarity and maximum speed for a SPI controller
370          - the I2C speed to use for an I2C device
371          - the number of GPIOs available in a GPIO device
374 which is compiled into U-Boot, or it can be parsed from the Device Tree
377 For an example of how it can be compiled in, see demo-pdata.c which
379 The data can be interpreted by the drivers however they like - it is
380 basically a communication scheme between the board-specific code and
383 Drivers can access their data via dev->info->platdata. Here is
402 -----------
405 by using device tree. In U-Boot you should use this where possible. Avoid
412 	red-square {
413 		compatible = "demo-shape";
423 the task of board-bring up either for U-Boot or Linux devs (whoever gets to
434 the device tree node for this device and place it in dev->platdata. Thus
455 are found in the doc/device-tree-bindings directory.  When not U-Boot specific
463 ------------------
477 -----------------------
479 U-Boot numbers devices from 0 in many situations, such as in the command
480 line for I2C and SPI buses, and the device names for serial ports (serial0,
491 not the way that U-Boot works.
500 	serial2 = "/serial@22230000";
503 This indicates that in the uclass called "serial", the named node
504 ("/serial@22230000") will be given sequence number 2. Any command or driver
505 which requests serial device 2 will obtain this device.
513 serial_2: serial@22230000 {
528 -----------
539 to the methods the uclass driver provides. Thirdly, per-child platform data
544 per-child platform data, so that it can be the same for all children of buses
561 To achieve this, the bus device can use dev->parent_platdata in each of its
562 three children. This can be auto-allocated if the bus driver (or bus uclass)
563 has a non-zero value for per_child_platdata_auto_alloc_size. If not, then
572 the per-child platform data from the device tree and set it up for the child.
585       flash (UCLASS_FLASH_STORAGE)  - parent data/methods defined by USB bus
588       flash (UCLASS_FLASH_STORAGE)  - parent data/methods defined by SATA bus
590    flash (UCLASS_FLASH_STORAGE)  - no parent data/methods (not on a bus)
609 ----------------
612 methods mentioned here are optional - e.g. if there is no probe() method for
618 U-Boot discovers devices using one of these two methods:
620    - Scan the U_BOOT_DEVICE() definitions. U-Boot looks up the name specified
625    - Scan through the device tree definitions. U-Boot looks at top-level
631 For each device that is discovered, U-Boot then calls device_bind() to create a
651 Note that compared to Linux, U-Boot's driver model has a separate step of
653 U-Boot it may be expensive to probe devices and we don't want to do it until
658 When a device needs to be used, U-Boot activates it, by following these
661    a. If priv_auto_alloc_size is non-zero, then the device-private space
663    dev->priv. The driver can put anything it likes in there, but should use
664    it for run-time information, not platform data (which should be static
667    b. If platdata_auto_alloc_size is non-zero, then the platform data space
671    zeroed. It will be accessible as dev->platdata.
673    c. If the device's uclass specifies a non-zero per_device_auto_alloc_size,
696    do various calls like fdtdec_get_int(gd->fdt_blob, dev_of_offset(dev), ...)
697    to access the node and store the resulting information into dev->platdata.
702    platform data structure, and U-Boot will automatically allocate and zero
706    in probe(). (Apart from the ugliness of mixing configuration and run-time
707    data, one day it is possible that U-Boot will cache platform data for
716       - platform data in dev->platdata (for configuration)
717       - private data in dev->priv (for run-time state)
718       - uclass data in dev->uclass_priv (for things the uclass stores
740 When the device is no-longer required, you can call device_remove() to
745    deactivated and no-longer 'known' by the uclass.
748    an active child device with a non-active parent. This means that
754    intended that the device be completely inactive at this point, For U-Boot
762    static pointer, it is not de-allocated during the remove() method. For
767       1. if the platdata_auto_alloc_size is non-zero, the deallocation
774    e. The device sequence number is set to -1, meaning that it no longer
793 ---------------
795 Driver model uses a doubly-linked list as the basic data structure. Some
802 ----------------
807 - Tried to aggressively remove boilerplate, so that for most drivers there
809 - Moved some data from code into data structure - e.g. store a pointer to
812 - Rename some structures to make them more similar to Linux (struct udevice
814 - Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
816 use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
818 - Remove 'struct driver_instance' and just use a single 'struct udevice'.
820 - Built in device tree support, to avoid the need for platdata
821 - Removed the concept of driver relocation, and just make it possible for
824 drivers, many of which can/will just re-init anyway. So the overhead of
826 - Implemented a GPIO system, trying to keep it simple
829 Pre-Relocation Support
830 ----------------------
832 For pre-relocation we simply call the driver model init function. Only
833 drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc'
838 Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc'
847 the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags
848 in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper'
849 which means that it will be processed (and a driver bound) in U-Boot proper
852 Then post relocation we throw that away and re-init driver model again.
853 For drivers which require some sort of continuity between pre- and
854 post-relocation devices, we can provide access to the pre-relocation
860 -----------
869    - CONFIG_SYS_MALLOC_SIMPLE
870    - CONFIG_DM_WARN
871    - CONFIG_DM_DEVICE_REMOVE
872    - CONFIG_DM_STDIO
876 ---------------------
878 Driver model is being brought into U-Boot gradually. As each subsystems gets
882 For example CONFIG_DM_SERIAL enables driver model for serial. With that
883 defined, the old serial support is not enabled, and your serial driver must
884 conform to driver model. With that undefined, the old serial support is
885 enabled and driver model is not available for serial. This means that when
895 ------------------------
901 be fewer merge conflicts in uclass-id.h.
907 Updated 7-May-13
908 Updated 14-Jun-13
909 Updated 18-Oct-13
910 Updated 5-Nov-13