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.
251 method of the relevant driver. Bearing in mind that there are two drivers,
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);
266 As you can see it just calls the relevant driver method. One of these is
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
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
432 and zeroed before the driver's ofdata_to_platdata() method is called. The
433 ofdata_to_platdata() method, which the driver write supplies, should parse
434 the device tree node for this device and place it in dev->platdata. Thus
435 when the probe method is called later (to set up the device ready for use)
439 method then it will be called first (during activation). If you provide a
440 probe method it will be called next. See Driver Lifecycle below for more
445 in your ofdata_to_platdata (or probe) method to allocate the required memory,
446 and you should free it in the remove method.
454 ------------------
468 -----------------------
470 U-Boot numbers devices from 0 in many situations, such as in the command
482 not the way that U-Boot works.
519 -----------
530 to the methods the uclass driver provides. Thirdly, per-child platform data
535 per-child platform data, so that it can be the same for all children of buses
552 To achieve this, the bus device can use dev->parent_platdata in each of its
553 three children. This can be auto-allocated if the bus driver (or bus uclass)
554 has a non-zero value for per_child_platdata_auto_alloc_size. If not, then
562 Similarly the bus uclass can define the child_post_bind() method to obtain
563 the per-child platform data from the device tree and set it up for the child.
564 The bus uclass can also provide a child_pre_probe() method. Very often it is
576       flash (UCLASS_FLASH_STORAGE)  - parent data/methods defined by USB bus
579       flash (UCLASS_FLASH_STORAGE)  - parent data/methods defined by SATA bus
581    flash (UCLASS_FLASH_STORAGE)  - no parent data/methods (not on a bus)
600 ----------------
603 methods mentioned here are optional - e.g. if there is no probe() method for
609 U-Boot discovers devices using one of these two methods:
611    - Scan the U_BOOT_DEVICE() definitions. U-Boot looks up the name specified
616    - Scan through the device tree definitions. U-Boot looks at top-level
622 For each device that is discovered, U-Boot then calls device_bind() to create a
626 driver's bind() method if one is defined.
637 The device's bind() method is permitted to perform simple actions, but
640 the probe() method.
642 Note that compared to Linux, U-Boot's driver model has a separate step of
644 U-Boot it may be expensive to probe devices and we don't want to do it until
649 When a device needs to be used, U-Boot activates it, by following these
652    a. If priv_auto_alloc_size is non-zero, then the device-private space
654    dev->priv. The driver can put anything it likes in there, but should use
655    it for run-time information, not platform data (which should be static
658    b. If platdata_auto_alloc_size is non-zero, then the platform data space
662    zeroed. It will be accessible as dev->platdata.
664    c. If the device's uclass specifies a non-zero per_device_auto_alloc_size,
685    g. If the driver provides an ofdata_to_platdata() method, then this is
687    do various calls like fdtdec_get_int(gd->fdt_blob, dev_of_offset(dev), ...)
688    to access the node and store the resulting information into dev->platdata.
693    platform data structure, and U-Boot will automatically allocate and zero
697    in probe(). (Apart from the ugliness of mixing configuration and run-time
698    data, one day it is possible that U-Boot will cache platformat data for
701    h. The device's probe() method is called. This should do anything that
707       - platform data in dev->platdata (for configuration)
708       - private data in dev->priv (for run-time state)
709       - uclass data in dev->uclass_priv (for things the uclass stores
714    platdata_auto_alloc_size. Remember to free them in the remove() method.
718    j. The uclass's post_probe() method is called, if one exists. This may
731 When the device is no-longer required, you can call device_remove() to
734    a. The uclass's pre_remove() method is called, if one exists. This may
736    deactivated and no-longer 'known' by the uclass.
739    an active child device with a non-active parent. This means that
742    c. The device's remove() method is called. At this stage nothing has been
745    intended that the device be completely inactive at this point, For U-Boot
753    static pointer, it is not de-allocated during the remove() method. For
756    remove() method, either:
758       1. if the platdata_auto_alloc_size is non-zero, the deallocation
765    e. The device sequence number is set to -1, meaning that it no longer
784 ---------------
786 Driver model uses a doubly-linked list as the basic data structure. Some
793 ----------------
798 - Tried to aggressively remove boilerplate, so that for most drivers there
800 - Moved some data from code into data structure - e.g. store a pointer to
803 - Rename some structures to make them more similar to Linux (struct udevice
805 - Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
807 use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
809 - Remove 'struct driver_instance' and just use a single 'struct udevice'.
811 - Built in device tree support, to avoid the need for platdata
812 - Removed the concept of driver relocation, and just make it possible for
815 drivers, many of which can/will just re-init anyway. So the overhead of
817 - Implemented a GPIO system, trying to keep it simple
820 Pre-Relocation Support
821 ----------------------
823 For pre-relocation we simply call the driver model init function. Only
825 'u-boot,dm-pre-reloc' flag are initialised prior to relocation. This helps
829 the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags
832 Then post relocation we throw that away and re-init driver model again.
833 For drivers which require some sort of continuity between pre- and
834 post-relocation devices, we can provide access to the pre-relocation
840 -----------
849    - CONFIG_SYS_MALLOC_SIMPLE
850    - CONFIG_DM_WARN
851    - CONFIG_DM_DEVICE_REMOVE
852    - CONFIG_DM_STDIO
856 ---------------------
858 Driver model is being brought into U-Boot gradually. As each subsystems gets
875 ------------------------
881 be fewer merge conflicts in uclass-id.h.
887 Updated 7-May-13
888 Updated 14-Jun-13
889 Updated 18-Oct-13
890 Updated 5-Nov-13