doc/driver-model/livetree.txt

1 Driver Model with Live Device Tree
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.
20 The flat device tree has several advantages:
22 - it is the format produced by the device tree compiler, so no translation
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
48 In U-Boot a live device tree ('livetree') is currently supported only
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
70 tree will be used in SPL and before relocation in U-Boot proper. Just
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
131    struct device_node - holds information about a device tree 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
161    of_live_active() returns true if livetree is in use, false if flat tree
171 There is full phandle support for live tree. All functions make use of
173 livetree and flat tree transparently. See for example
180 You should use dev_read_addr() and friends to read addresses from device-tree
195 more efficient implementation for modification of the device tree than using
196 the flat tree.
206 is disabled, just falling back to flat tree code.
226 With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).
236 Adding a new function for device-tree access involves the following steps:
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
261 Live tree support was introduced in U-Boot 2017.07. There is still quite a bit