livetree.rst 9.4 KB

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