doc/driver-model/livetree.txt

1 Driver Model with Live Device Tree
6 ------------
8 Traditionally U-Boot has used a 'flat' device tree. This means that it
9 reads directly from the device tree binary structure. It is called a flat
10 device tree because nodes are listed one after the other, with the
13 This document describes U-Boot's support for a 'live' device tree, meaning
14 that the tree is loaded into a hierarchical data structure within U-Boot.
18 ----------
20 The flat device tree has several advantages:
22 - it is the format produced by the device tree compiler, so no translation
25 - it is fairly compact (e.g. there is no need for pointers)
27 - it is accessed by the libfdt library, which is well tested and stable
30 However the flat device tree does have some limitations. Adding new
32 The overall tree has a fixed maximum size so sometimes the tree must be
34 properties or nodes, scanning the tree can be slow. For example, finding
38 Driver model scans the entire device tree sequentially on start-up which
39 avoids the worst of the flat tree's limitations. But if the tree is to be
40 modified at run-time, a live tree is much faster. Even if no modification
41 is necessary, parsing the tree once and using a live tree from then on
46 --------------
48 In U-Boot a live device tree ('livetree') is currently supported only
49 after relocation. Therefore we need a mechanism to specify a device
50 tree node regardless of whether it is in the flat tree or livetree.
52 The 'ofnode' type provides this. An ofnode can point to either a flat tree
53 node (when the live tree node is not yet set up) or a livetree node. The
56 The main users of the information in a device tree are  drivers. These have
57 a 'struct udevice *' which is attached to a device tree node. Therefore it
58 makes sense to be able to read device tree  properties using the
62 easily read from the device tree using only a device pointer. Under the
63 hood it uses ofnode so it works with both flat and live device trees.
67 -----------------
70 tree will be used in SPL and before relocation in U-Boot proper. Just
71 before relocation a livetree is built, and this is used for U-Boot proper
80 ---------------
82 Many existing drivers use the fdtdec interface to read device tree
83 properties. This only works with a flat device tree. The drivers should be
89     const void *blob = gd->fdt_blob;
92     i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev);
93     plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
99     i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
100     plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000);
103 flat and live device trees. See include/dm/read.h for a list of functions.
105 Where properties must be read from sub-nodes or other nodes, you must fall
108     const void *blob = gd->fdt_blob;
112         freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
121         freq = ofnode_read_u32(node, "spi-max-frequency", 500000);
127 -----------------------
131    struct device_node - holds information about a device tree node
132    struct property    - holds information about a property within a node
136 tree.
144 code to work with a flat tree also.
148 For example it is invalid to call ofnode_to_no() when a flat tree is being
152    ofnode_to_np() - converts ofnode to struct device_node *
153    ofnode_to_offset() - converts ofnode to offset
155    no_to_ofnode() - converts node pointer to ofnode
156    offset_to_ofnode() - converts offset to ofnode
161    of_live_active() returns true if livetree is in use, false if flat tree
169 --------
171 There is full phandle support for live tree. All functions make use of
173 livetree and flat tree transparently. See for example
178 -----------------
180 You should use dev_read_addr() and friends to read addresses from device-tree
185 ------
192 ----------------------
195 more efficient implementation for modification of the device tree than using
196 the flat tree.
200 -----------------------
206 is disabled, just falling back to flat tree code.
220 node and the stdout-path alias.
224 ------
226 With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).
227 For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present
234 ---------------------------
236 Adding a new function for device-tree access involves the following steps:
238    - Add two dev_read() functions:
239 	- inline version in the read.h header file, which calls an ofnode
241 	- standard version in the read.c file (or perhaps another file), which
247    - Add an ofnode function. This should call ofnode_is_np() to work out
248 	whether a livetree or flat tree is used. For the livetree it should
249 	call an of_...() function. For the flat tree it should call an
253    - Add an of_...() function for the livetree implementation. If a similar
259 -----------
261 Live tree support was introduced in U-Boot 2017.07. There is still quite a bit
264 - tests for all access functions
265 - support for livetree modification
266 - addition of more access functions as needed
267 - support for livetree in SPL and before relocation (if desired)
270 --
272 5-Aug-17