doc/develop/driver-model/livetree.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. sectionauthor:: Simon Glass <sjg@chromium.org>
   3
   4 Live Device Tree
   5 ================
   6
   7
   8 Introduction
   9 ------------
  10
  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.
  15
  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.
  18
  19
  20 Motivation
  21 ----------
  22
  23 The 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
  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.
  40
  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.
  46
  47
  48 Implementation
  49 --------------
  50
  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.
  54
  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.
  58
  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.
  63
  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.
  67
  68
  69 Enabling livetree
  70 -----------------
  71
  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
  75 after relocation.
  76
  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.
  80
  81
  82 Porting drivers
  83 ---------------
  84
  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.
  88
  89 For 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
 100 The 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
 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.
 111
 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:
 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
 125 you 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
 137 Useful ofnode functions
 138 -----------------------
 139
 140 The 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
 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
 147 tree.
 148
 149 Properties have pointers to the next property. This allows all properties of
 150 a node to be linked together in a chain.
 151
 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.
 156
 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
 161 node.
 162
 163 ofnode_to_np():
 164    converts ofnode to struct device_node *
 165 ofnode_to_offset():
 166    converts ofnode to offset
 167
 168 no_to_ofnode():
 169    converts node pointer to ofnode
 170 offset_to_ofnode():
 171    converts offset to ofnode
 172
 173
 174 Other useful functions:
 175
 176 of_live_active():
 177    returns true if livetree is in use, false if flat tree
 178 ofnode_valid():
 179    return true if a given node is valid
 180 ofnode_is_np():
 181    returns true if a given node is a livetree node
 182 ofnode_equal():
 183    compares two ofnodes
 184 ofnode_null():
 185    returns a null ofnode (for which ofnode_valid() returns false)
 186
 187
 188 Phandles
 189 --------
 190
 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().
 195
 196
 197 Reading addresses
 198 -----------------
 199
 200 You should use dev_read_addr() and friends to read addresses from device-tree
 201 nodes.
 202
 203
 204 fdtdec
 205 ------
 206
 207 The existing fdtdec interface will eventually be retired. Please try to avoid
 208 using it in new code.
 209
 210
 211 Modifying the livetree
 212 ----------------------
 213
 214 This is supported in a limited way, with ofnode_write_prop() and related
 215 functions.
 216
 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.
 221
 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.
 226
 227 The ofnode_write\_...() functions also support writing to the flat tree. Care
 228 should be taken however, since this can change the position of node names and
 229 properties in the flat tree, thus affecting the live tree. Generally this does
 230 not matter, since when we fire up the live tree we don't ever use the flat tree
 231 again. But in the case of tests, this can cause a problem.
 232
 233 The sandbox tests typically run with OF_LIVE enabled but with the actual live
 234 tree either present or absent. This is to make sure that the flat tree functions
 235 work correctly even with OF_LIVE is enabled. But if a test modifies the flat
 236 device tree, then the live tree can become invalid. Any live tree tests that run
 237 after that point will use a corrupted tree, e.g. with an incorrect property name
 238 or worse. To deal with this we take a copy of the device tree and restore it
 239 after any test that modifies it. Note that this copy is not made on other
 240 boards, only sandbox.
 241
 242
 243 Multiple livetrees
 244 ------------------
 245
 246 The livetree implementation was originally designed for use with the control
 247 FDT. This means that the FDT fix-ups (ft_board_setup() and the like, must use
 248 a flat tree.
 249
 250 It would be helpful to use livetree for fixups, since adding a lot of nodes and
 251 properties would involve less memory copying and be more efficient. As a step
 252 towards this, an `oftree` type has been introduced. It is normally set to
 253 oftree_default() but can be set to other values using oftree_from_fdt().
 254 So long as OF_LIVE is disabled, it is possible to do fixups using the ofnode
 255 interface. The OF_LIVE support required addition of the flattening step at the
 256 end.
 257
 258 See dm_test_ofnode_root() for some examples. The ofnode_path_root() function
 259 causes a flat device tree to be 'registered' such that it can be used by the
 260 ofnode interface.
 261
 262
 263 Internal implementation
 264 -----------------------
 265
 266 The dev_read\_...() functions have two implementations. When
 267 CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode
 268 functions directly. This is useful when livetree is not enabled. The ofnode
 269 functions call ofnode_is_np(node) which will always return false if livetree
 270 is disabled, just falling back to flat tree code.
 271
 272 This optimisation means that without livetree enabled, the dev_read\_...() and
 273 ofnode interfaces do not noticeably add to code size.
 274
 275 The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is
 276 disabled.
 277
 278 Most livetree code comes directly from Linux and is modified as little as
 279 possible. This is deliberate since this code is fairly stable and does what
 280 we want. Some features (such as get/put) are not supported. Internal macros
 281 take care of removing these features silently.
 282
 283 Within the of_access.c file there are pointers to the alias node, the chosen
 284 node and the stdout-path alias.
 285
 286
 287 Errors
 288 ------
 289
 290 With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).
 291 For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present
 292 the ofnode and dev_read\_...() functions return either one or other type of
 293 error. This is clearly not desirable. Once tests are added for all the
 294 functions this can be tidied up.
 295
 296
 297 Adding new access functions
 298 ---------------------------
 299
 300 Adding a new function for device-tree access involves the following steps:
 301
 302    - Add two dev_read() functions:
 303       - inline version in the read.h header file, which calls an ofnode function
 304       - standard version in the read.c file (or perhaps another file), which
 305         also calls an ofnode function
 306
 307         The implementations of these functions can be the same. The purpose
 308         of the inline version is purely to reduce code size impact.
 309
 310    - Add an ofnode function. This should call ofnode_is_np() to work out
 311      whether a livetree or flat tree is used. For the livetree it should
 312      call an of\_...() function. For the flat tree it should call an
 313      fdt\_...() function. The livetree version will be optimised out at
 314      compile time if livetree is not enabled.
 315
 316    - Add an of\_...() function for the livetree implementation. If a similar
 317      function is available in Linux, the implementation should be taken
 318      from there and modified as little as possible (generally not at all).
 319
 320
 321 Future work
 322 -----------
 323
 324 Live tree support was introduced in U-Boot 2017.07. Some possible enhancements
 325 are:
 326
 327 - support for livetree in SPL and before relocation (if desired)
 328 - freeing leaked memory caused by writing new nodes / property values to the
 329   livetree (ofnode_write_prop())