1 .. SPDX-License-Identifier: GPL-2.0+
2 .. sectionauthor:: Simon Glass <sjg@chromium.org>
11 Traditionally U-Boot has used a 'flat' device tree. This means that it
12 reads directly from the device tree binary structure. It is called a flat
13 device tree because nodes are listed one after the other, with the
14 hierarchy detected by tags in the format.
16 This document describes U-Boot's support for a 'live' device tree, meaning
17 that the tree is loaded into a hierarchical data structure within U-Boot.
23 The flat device tree has several advantages:
25 - it is the format produced by the device tree compiler, so no translation
28 - it is fairly compact (e.g. there is no need for pointers)
30 - it is accessed by the libfdt library, which is well tested and stable
33 However the flat device tree does have some limitations. Adding new
34 properties can involve copying large amounts of data around to make room.
35 The overall tree has a fixed maximum size so sometimes the tree must be
36 rebuilt in a new location to create more space. Even if not adding new
37 properties or nodes, scanning the tree can be slow. For example, finding
38 the parent of a node is a slow process. Reading from nodes involves a
39 small amount parsing which takes a little time.
41 Driver model scans the entire device tree sequentially on start-up which
42 avoids the worst of the flat tree's limitations. But if the tree is to be
43 modified at run-time, a live tree is much faster. Even if no modification
44 is necessary, parsing the tree once and using a live tree from then on
45 seems to save a little time.
51 In U-Boot a live device tree ('livetree') is currently supported only
52 after relocation. Therefore we need a mechanism to specify a device
53 tree node regardless of whether it is in the flat tree or livetree.
55 The 'ofnode' type provides this. An ofnode can point to either a flat tree
56 node (when the live tree node is not yet set up) or a livetree node. The
57 caller of an ofnode function does not need to worry about these details.
59 The main users of the information in a device tree are drivers. These have
60 a 'struct udevice \*' which is attached to a device tree node. Therefore it
61 makes sense to be able to read device tree properties using the
62 'struct udevice \*', rather than having to obtain the ofnode first.
64 The 'dev_read\_...()' interface provides this. It allows properties to be
65 easily read from the device tree using only a device pointer. Under the
66 hood it uses ofnode so it works with both flat and live device trees.
72 CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat
73 tree will be used in SPL and before relocation in U-Boot proper. Just
74 before relocation a livetree is built, and this is used for U-Boot proper
77 Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that
78 for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does
79 not exist, since SPL does not support livetree.
85 Many existing drivers use the fdtdec interface to read device tree
86 properties. This only works with a flat device tree. The drivers should be
87 converted to use the dev_read_() interface.
89 For example, the old code may be like this:
94 const void *blob = gd->fdt_blob;
95 int node = dev_of_offset(bus);
97 i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev);
98 plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
106 i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
107 plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000);
109 The dev_read\_...() interface is more convenient and works with both the
110 flat and live device trees. See include/dm/read.h for a list of functions.
112 Where properties must be read from sub-nodes or other nodes, you must fall
113 back to using ofnode. For example, for old code like this:
117 const void *blob = gd->fdt_blob;
120 fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) {
121 freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000);
131 ofnode_for_each_subnode(subnode, dev_ofnode(dev)) {
132 freq = ofnode_read_u32(node, "spi-max-frequency", 500000);
137 Useful ofnode functions
138 -----------------------
140 The internal data structures of the livetree are defined in include/dm/of.h :
142 :struct device_node: holds information about a device tree node
143 :struct property: holds information about a property within a node
145 Nodes have pointers to their first property, their parent, their first child
146 and their sibling. This allows nodes to be linked together in a hierarchical
149 Properties have pointers to the next property. This allows all properties of
150 a node to be linked together in a chain.
152 It should not be necessary to use these data structures in normal code. In
153 particular, you should refrain from using functions which access the livetree
154 directly, such as of_read_u32(). Use ofnode functions instead, to allow your
155 code to work with a flat tree also.
157 Some conversion functions are used internally. Generally these are not needed
158 for driver code. Note that they will not work if called in the wrong context.
159 For example it is invalid to call ofnode_to_no() when a flat tree is being
160 used. Similarly it is not possible to call ofnode_to_offset() on a livetree
164 converts ofnode to struct device_node *
166 converts ofnode to offset
169 converts node pointer to ofnode
171 converts offset to ofnode
174 Other useful functions:
177 returns true if livetree is in use, false if flat tree
179 return true if a given node is valid
181 returns true if a given node is a livetree node
185 returns a null ofnode (for which ofnode_valid() returns false)
191 There is full phandle support for live tree. All functions make use of
192 struct ofnode_phandle_args, which has an ofnode within it. This supports both
193 livetree and flat tree transparently. See for example
194 ofnode_parse_phandle_with_args().
200 You should use dev_read_addr() and friends to read addresses from device-tree
207 The existing fdtdec interface will eventually be retired. Please try to avoid
208 using it in new code.
211 Modifying the livetree
212 ----------------------
214 This is supported in a limited way, with ofnode_write_prop() and related
217 The unflattening algorithm results in a single block of memory being
218 allocated for the whole tree. When writing new properties, these are
219 allocated new memory outside that block. When the block is freed, the
220 allocated properties remain. This can result in a memory leak.
222 The solution to this leak would be to add a flag for properties (and nodes when
223 support is provided for adding those) that indicates that they should be
224 freed. Then the tree can be scanned for these 'separately allocated' nodes and
225 properties before freeing the memory block.
231 The livetree implementation was originally designed for use with the control
232 FDT. This means that the FDT fix-ups (ft_board_setup() and the like, must use
235 It would be helpful to use livetree for fixups, since adding a lot of nodes and
236 properties would involve less memory copying and be more efficient. As a step
237 towards this, an `oftree` type has been introduced. It is normally set to
238 oftree_default() but can be set to other values. Eventually this should allow
239 the use of FDT fixups using the ofnode interface, instead of the low-level
242 See dm_test_ofnode_root() for some examples.
245 Internal implementation
246 -----------------------
248 The dev_read\_...() functions have two implementations. When
249 CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode
250 functions directly. This is useful when livetree is not enabled. The ofnode
251 functions call ofnode_is_np(node) which will always return false if livetree
252 is disabled, just falling back to flat tree code.
254 This optimisation means that without livetree enabled, the dev_read\_...() and
255 ofnode interfaces do not noticeably add to code size.
257 The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is
260 Most livetree code comes directly from Linux and is modified as little as
261 possible. This is deliberate since this code is fairly stable and does what
262 we want. Some features (such as get/put) are not supported. Internal macros
263 take care of removing these features silently.
265 Within the of_access.c file there are pointers to the alias node, the chosen
266 node and the stdout-path alias.
272 With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).
273 For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present
274 the ofnode and dev_read\_...() functions return either one or other type of
275 error. This is clearly not desirable. Once tests are added for all the
276 functions this can be tidied up.
279 Adding new access functions
280 ---------------------------
282 Adding a new function for device-tree access involves the following steps:
284 - Add two dev_read() functions:
285 - inline version in the read.h header file, which calls an ofnode function
286 - standard version in the read.c file (or perhaps another file), which
287 also calls an ofnode function
289 The implementations of these functions can be the same. The purpose
290 of the inline version is purely to reduce code size impact.
292 - Add an ofnode function. This should call ofnode_is_np() to work out
293 whether a livetree or flat tree is used. For the livetree it should
294 call an of\_...() function. For the flat tree it should call an
295 fdt\_...() function. The livetree version will be optimised out at
296 compile time if livetree is not enabled.
298 - Add an of\_...() function for the livetree implementation. If a similar
299 function is available in Linux, the implementation should be taken
300 from there and modified as little as possible (generally not at all).
306 Live tree support was introduced in U-Boot 2017.07. There is still quite a bit
307 of work to do to flesh this out:
309 - tests for all access functions
310 - more support for livetree modification
311 - addition of more access functions as needed
312 - support for livetree in SPL and before relocation (if desired)