doc/driver-model/livetree.txt

6 ------------
8 Traditionally U-Boot has used a 'flat' device tree. This means that it
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 ----------
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
38 Driver model scans the entire device tree sequentially on start-up which
40 modified at run-time, a live tree is much faster. Even if no modification
46 --------------
48 In U-Boot a live device tree ('livetree') is currently supported only
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 ---------------
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);
126 Useful ofnode functions
127 -----------------------
131    struct device_node - holds information about a device tree node
132    struct property    - holds information about a property within a node
142 particular, you should refrain from using functions which access the livetree
143 directly, such as of_read_u32(). Use ofnode functions instead, to allow your
146 Some conversion functions are used internally. Generally these are not needed
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
159 Other useful functions:
169 --------
171 There is full phandle support for live tree. All functions make use of
178 -----------------
180 You should use dev_read_addr() and friends to read addresses from device-tree
185 ------
192 ----------------------
200 -----------------------
202 The dev_read_...() functions have two implementations. When
203 CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode
204 functions directly. This is useful when livetree is not enabled. The ofnode
205 functions call ofnode_is_np(node) which will always return false if livetree
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
228 the ofnode and dev_read_...() functions return either one or other type of
230 functions this can be tidied up.
233 Adding new access functions
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
244 	The implementations of these functions can be the same. The purpose
247    - Add an ofnode function. This should call ofnode_is_np() to work out
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