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
56 handles parameter data and platdata (data which tells the driver how
57 to operate on a particular platform) and it uses private driver data.
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):
304 private data (accessible through dev_get_priv(dev) once the driver has
312 The U_BOOT_DRIVER macro creates a data structure accessible from 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
328 Platform Data
329 -------------
331 *** Note: platform data is the old way of doing things. It is
333 *** platform-specific settings like the address of its registers, bus
337 *** the cut-down device tree and libfdt libraries) you should stay away
338 *** from platform data.
340 Platform data is like Linux platform data, if you are familiar with that.
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
354 times by supplying 6 lots of platform data. Each lot of platform data
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
358 the platform data, which is set for this one port and clear for the rest.
362 so on. Platform data provides this link between the generic piece of code
365 Examples of platform data include:
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
373 Where does the platform data come from? It is either held in a structure
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
378 sets up a table of driver names and their associated platform data.
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
384 the declaration for the platform data, which would normally appear
402 -----------
404 While platdata is useful, a more flexible way of providing device data is
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
436 the platform data will be present.
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 -----------
527 Firstly, a bus can request that its children store some 'parent data' which
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
563 the per-child platform data from the device tree and set it up for the child.
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)
592 The uclass for the device can also contain data private to that uclass.
594 uclass, and this data has nothing to do with the child data for each child
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
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
660    otherwise you would have to specific the platform data in the
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,
666    stored in the device, but it is uclass data. owned by the uclass driver.
686    called to convert the device tree data into platform data. This should
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.
691    the platform data is now stored in the platdata structure. Typically you
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
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
731 When the device is no-longer required, you can call device_remove() to
736    deactivated and no-longer 'known' by the uclass.
739    an active child device with a non-active parent. This means that
743    deallocated so platform data, private data and the uclass data will all
745    intended that the device be completely inactive at this point, For U-Boot
749    d. The device memory is freed (platform data, private data, uclass data,
750    parent data).
752    Note: Because the platform data for a U_BOOT_DEVICE() is defined with a
753    static pointer, it is not de-allocated during the remove() method. For
754    a device instantiated using the device tree data, the platform data will
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
783 Data Structures
784 ---------------
786 Driver model uses a doubly-linked list as the basic data structure. Some
788 data structure might be worthwhile in some rare cases, once we understand
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
813 the new driver (created after relocation) to access the old driver data.
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