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 -----------------
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
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:
222 ======================= 84 tests deselected by '-kut_dm' =======================
226 -----------------
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
325 device tree) and probe.
329 -------------
333 *** platform-specific settings like the address of its registers, bus
334 *** speed, etc. Device tree is now the preferred way of handling this.
335 *** Unless you have a good reason not to use device tree (the main one
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
375 (see 'Device Tree' below).
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
401 Device Tree
402 -----------
405 by using device tree. In U-Boot you should use this where possible. Avoid
409 With device tree we replace the above code with the following device tree
412 	red-square {
413 		compatible = "demo-shape";
419 the board file, we put these in the device tree. This approach allows a lot
422 benefit is that the Linux device tree can be used, thus further simplifying
423 the task of board-bring up either for U-Boot or Linux devs (whoever gets to
434 the device tree node for this device and place it in dev->platdata. Thus
448 The driver model tree is intended to mirror that of the device tree. The
449 root driver is at device tree offset 0 (the root node, '/'), and its
452 In order for a device tree to be valid, the content must be correct with
453 respect to either device tree specification
454 (https://www.devicetree.org/specifications/) or the device tree bindings that
455 are found in the doc/device-tree-bindings directory.  When not U-Boot specific
459 retain compatibility without additional changes being made to the device tree
463 ------------------
477 -----------------------
479 U-Boot numbers devices from 0 in many situations, such as in the command
491 not the way that U-Boot works.
496 To specify the sequence number in the device tree an alias is typically
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
626 nodes in the the device tree. It looks at the compatible string in each node
631 For each device that is discovered, U-Boot then calls device_bind() to create a
641 in that declaration. For a bound device created from the device tree,
642 platdata will be NULL, but of_offset will be the offset of the device tree
647 should not scan the device tree node, not initialise hardware, nor set up
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
668    is allocated. This is only useful for device tree operation, since
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,
695    called to convert the device tree data into platform data. This should
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.
699    using a device tree node or U_BOOT_DEVICE() structure. In either case,
702    platform data structure, and U-Boot will automatically allocate and zero
705    to do all the device tree decoding in ofdata_to_platdata() rather than
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
763    a device instantiated using the device tree data, the platform data will
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'
835 model overhead. This flag applies to SPL and TPL as well, if device tree is
838 Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc'
842 amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the
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
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