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
58 makes sense to be able to read device tree  properties using the
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);
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
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
169 --------
178 -----------------
180 You should use dev_read_addr() and friends to read addresses from device-tree
185 ------
192 ----------------------
200 -----------------------
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
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