1.. SPDX-License-Identifier: GPL-2.0+ 2.. sectionauthor:: Simon Glass <sjg@chromium.org> 3 4Live Device Tree 5================ 6 7 8Introduction 9------------ 10 11Traditionally U-Boot has used a 'flat' device tree. This means that it 12reads directly from the device tree binary structure. It is called a flat 13device tree because nodes are listed one after the other, with the 14hierarchy detected by tags in the format. 15 16This document describes U-Boot's support for a 'live' device tree, meaning 17that the tree is loaded into a hierarchical data structure within U-Boot. 18 19 20Motivation 21---------- 22 23The flat device tree has several advantages: 24 25- it is the format produced by the device tree compiler, so no translation 26 is needed 27 28- it is fairly compact (e.g. there is no need for pointers) 29 30- it is accessed by the libfdt library, which is well tested and stable 31 32 33However the flat device tree does have some limitations. Adding new 34properties can involve copying large amounts of data around to make room. 35The overall tree has a fixed maximum size so sometimes the tree must be 36rebuilt in a new location to create more space. Even if not adding new 37properties or nodes, scanning the tree can be slow. For example, finding 38the parent of a node is a slow process. Reading from nodes involves a 39small amount parsing which takes a little time. 40 41Driver model scans the entire device tree sequentially on start-up which 42avoids the worst of the flat tree's limitations. But if the tree is to be 43modified at run-time, a live tree is much faster. Even if no modification 44is necessary, parsing the tree once and using a live tree from then on 45seems to save a little time. 46 47 48Implementation 49-------------- 50 51In U-Boot a live device tree ('livetree') is currently supported only 52after relocation. Therefore we need a mechanism to specify a device 53tree node regardless of whether it is in the flat tree or livetree. 54 55The 'ofnode' type provides this. An ofnode can point to either a flat tree 56node (when the live tree node is not yet set up) or a livetree node. The 57caller of an ofnode function does not need to worry about these details. 58 59The main users of the information in a device tree are drivers. These have 60a 'struct udevice \*' which is attached to a device tree node. Therefore it 61makes sense to be able to read device tree properties using the 62'struct udevice \*', rather than having to obtain the ofnode first. 63 64The 'dev_read\_...()' interface provides this. It allows properties to be 65easily read from the device tree using only a device pointer. Under the 66hood it uses ofnode so it works with both flat and live device trees. 67 68 69Enabling livetree 70----------------- 71 72CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat 73tree will be used in SPL and before relocation in U-Boot proper. Just 74before relocation a livetree is built, and this is used for U-Boot proper 75after relocation. 76 77Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that 78for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does 79not exist, since SPL does not support livetree. 80 81 82Porting drivers 83--------------- 84 85Many existing drivers use the fdtdec interface to read device tree 86properties. This only works with a flat device tree. The drivers should be 87converted to use the dev_read_() interface. 88 89For example, the old code may be like this: 90 91.. code-block:: c 92 93 struct udevice *bus; 94 const void *blob = gd->fdt_blob; 95 int node = dev_of_offset(bus); 96 97 i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev); 98 plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); 99 100The new code is: 101 102.. code-block:: c 103 104 struct udevice *bus; 105 106 i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev); 107 plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000); 108 109The dev_read\_...() interface is more convenient and works with both the 110flat and live device trees. See include/dm/read.h for a list of functions. 111 112Where properties must be read from sub-nodes or other nodes, you must fall 113back to using ofnode. For example, for old code like this: 114 115.. code-block:: c 116 117 const void *blob = gd->fdt_blob; 118 int subnode; 119 120 fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) { 121 freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); 122 ... 123 } 124 125you should use: 126 127.. code-block:: c 128 129 ofnode subnode; 130 131 ofnode_for_each_subnode(subnode, dev_ofnode(dev)) { 132 freq = ofnode_read_u32(node, "spi-max-frequency", 500000); 133 ... 134 } 135 136 137Useful ofnode functions 138----------------------- 139 140The internal data structures of the livetree are defined in include/dm/of.h : 141 142 :struct device_node: holds information about a device tree node 143 :struct property: holds information about a property within a node 144 145Nodes have pointers to their first property, their parent, their first child 146and their sibling. This allows nodes to be linked together in a hierarchical 147tree. 148 149Properties have pointers to the next property. This allows all properties of 150a node to be linked together in a chain. 151 152It should not be necessary to use these data structures in normal code. In 153particular, you should refrain from using functions which access the livetree 154directly, such as of_read_u32(). Use ofnode functions instead, to allow your 155code to work with a flat tree also. 156 157Some conversion functions are used internally. Generally these are not needed 158for driver code. Note that they will not work if called in the wrong context. 159For example it is invalid to call ofnode_to_no() when a flat tree is being 160used. Similarly it is not possible to call ofnode_to_offset() on a livetree 161node. 162 163ofnode_to_np(): 164 converts ofnode to struct device_node * 165ofnode_to_offset(): 166 converts ofnode to offset 167 168no_to_ofnode(): 169 converts node pointer to ofnode 170offset_to_ofnode(): 171 converts offset to ofnode 172 173 174Other useful functions: 175 176of_live_active(): 177 returns true if livetree is in use, false if flat tree 178ofnode_valid(): 179 return true if a given node is valid 180ofnode_is_np(): 181 returns true if a given node is a livetree node 182ofnode_equal(): 183 compares two ofnodes 184ofnode_null(): 185 returns a null ofnode (for which ofnode_valid() returns false) 186 187 188Phandles 189-------- 190 191There is full phandle support for live tree. All functions make use of 192struct ofnode_phandle_args, which has an ofnode within it. This supports both 193livetree and flat tree transparently. See for example 194ofnode_parse_phandle_with_args(). 195 196 197Reading addresses 198----------------- 199 200You should use dev_read_addr() and friends to read addresses from device-tree 201nodes. 202 203 204fdtdec 205------ 206 207The existing fdtdec interface will eventually be retired. Please try to avoid 208using it in new code. 209 210 211Modifying the livetree 212---------------------- 213 214This is not currently supported. Once implemented it should provide a much 215more efficient implementation for modification of the device tree than using 216the flat tree. 217 218 219Internal implementation 220----------------------- 221 222The dev_read\_...() functions have two implementations. When 223CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode 224functions directly. This is useful when livetree is not enabled. The ofnode 225functions call ofnode_is_np(node) which will always return false if livetree 226is disabled, just falling back to flat tree code. 227 228This optimisation means that without livetree enabled, the dev_read\_...() and 229ofnode interfaces do not noticeably add to code size. 230 231The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is 232disabled. 233 234Most livetree code comes directly from Linux and is modified as little as 235possible. This is deliberate since this code is fairly stable and does what 236we want. Some features (such as get/put) are not supported. Internal macros 237take care of removing these features silently. 238 239Within the of_access.c file there are pointers to the alias node, the chosen 240node and the stdout-path alias. 241 242 243Errors 244------ 245 246With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND). 247For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present 248the ofnode and dev_read\_...() functions return either one or other type of 249error. This is clearly not desirable. Once tests are added for all the 250functions this can be tidied up. 251 252 253Adding new access functions 254--------------------------- 255 256Adding a new function for device-tree access involves the following steps: 257 258 - Add two dev_read() functions: 259 - inline version in the read.h header file, which calls an ofnode function 260 - standard version in the read.c file (or perhaps another file), which 261 also calls an ofnode function 262 263 The implementations of these functions can be the same. The purpose 264 of the inline version is purely to reduce code size impact. 265 266 - Add an ofnode function. This should call ofnode_is_np() to work out 267 whether a livetree or flat tree is used. For the livetree it should 268 call an of\_...() function. For the flat tree it should call an 269 fdt\_...() function. The livetree version will be optimised out at 270 compile time if livetree is not enabled. 271 272 - Add an of\_...() function for the livetree implementation. If a similar 273 function is available in Linux, the implementation should be taken 274 from there and modified as little as possible (generally not at all). 275 276 277Future work 278----------- 279 280Live tree support was introduced in U-Boot 2017.07. There is still quite a bit 281of work to do to flesh this out: 282 283- tests for all access functions 284- support for livetree modification 285- addition of more access functions as needed 286- support for livetree in SPL and before relocation (if desired) 287