-Driver Model with Live Device Tree
-==================================
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
+
+Live Device Tree
+================
Introduction
The flat device tree has several advantages:
- it is the format produced by the device tree compiler, so no translation
-is needed
+ is needed
- it is fairly compact (e.g. there is no need for pointers)
node (when the live tree node is not yet set up) or a livetree node. The
caller of an ofnode function does not need to worry about these details.
-The main users of the information in a device tree are drivers. These have
-a 'struct udevice *' which is attached to a device tree node. Therefore it
+The main users of the information in a device tree are drivers. These have
+a 'struct udevice \*' which is attached to a device tree node. Therefore it
makes sense to be able to read device tree properties using the
-'struct udevice *', rather than having to obtain the ofnode first.
+'struct udevice \*', rather than having to obtain the ofnode first.
-The 'dev_read_...()' interface provides this. It allows properties to be
+The 'dev_read\_...()' interface provides this. It allows properties to be
easily read from the device tree using only a device pointer. Under the
hood it uses ofnode so it works with both flat and live device trees.
For example, the old code may be like this:
+.. code-block:: c
+
struct udevice *bus;
const void *blob = gd->fdt_blob;
int node = dev_of_offset(bus);
The new code is:
+.. code-block:: c
+
struct udevice *bus;
i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000);
-The dev_read_...() interface is more convenient and works with both the
+The dev_read\_...() interface is more convenient and works with both the
flat and live device trees. See include/dm/read.h for a list of functions.
Where properties must be read from sub-nodes or other nodes, you must fall
back to using ofnode. For example, for old code like this:
+.. code-block:: c
+
const void *blob = gd->fdt_blob;
int subnode;
you should use:
+.. code-block:: c
+
ofnode subnode;
ofnode_for_each_subnode(subnode, dev_ofnode(dev)) {
The internal data structures of the livetree are defined in include/dm/of.h :
- struct device_node - holds information about a device tree node
- struct property - holds information about a property within a node
+ :struct device_node: holds information about a device tree node
+ :struct property: holds information about a property within a node
Nodes have pointers to their first property, their parent, their first child
and their sibling. This allows nodes to be linked together in a hierarchical
used. Similarly it is not possible to call ofnode_to_offset() on a livetree
node.
- ofnode_to_np() - converts ofnode to struct device_node *
- ofnode_to_offset() - converts ofnode to offset
+ofnode_to_np():
+ converts ofnode to struct device_node *
+ofnode_to_offset():
+ converts ofnode to offset
- no_to_ofnode() - converts node pointer to ofnode
- offset_to_ofnode() - converts offset to ofnode
+no_to_ofnode():
+ converts node pointer to ofnode
+offset_to_ofnode():
+ converts offset to ofnode
Other useful functions:
- of_live_active() returns true if livetree is in use, false if flat tree
- ofnode_valid() return true if a given node is valid
- ofnode_is_np() returns true if a given node is a livetree node
- ofnode_equal() compares two ofnodes
- ofnode_null() returns a null ofnode (for which ofnode_valid() returns false)
+of_live_active():
+ returns true if livetree is in use, false if flat tree
+ofnode_valid():
+ return true if a given node is valid
+ofnode_is_np():
+ returns true if a given node is a livetree node
+ofnode_equal():
+ compares two ofnodes
+ofnode_null():
+ returns a null ofnode (for which ofnode_valid() returns false)
Phandles
Internal implementation
-----------------------
-The dev_read_...() functions have two implementations. When
+The dev_read\_...() functions have two implementations. When
CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode
functions directly. This is useful when livetree is not enabled. The ofnode
functions call ofnode_is_np(node) which will always return false if livetree
is disabled, just falling back to flat tree code.
-This optimisation means that without livetree enabled, the dev_read_...() and
+This optimisation means that without livetree enabled, the dev_read\_...() and
ofnode interfaces do not noticeably add to code size.
The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is
With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND).
For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present
-the ofnode and dev_read_...() functions return either one or other type of
+the ofnode and dev_read\_...() functions return either one or other type of
error. This is clearly not desirable. Once tests are added for all the
functions this can be tidied up.
Adding a new function for device-tree access involves the following steps:
- Add two dev_read() functions:
- - inline version in the read.h header file, which calls an ofnode
- function
- - standard version in the read.c file (or perhaps another file), which
- also calls an ofnode function
+ - inline version in the read.h header file, which calls an ofnode function
+ - standard version in the read.c file (or perhaps another file), which
+ also calls an ofnode function
- The implementations of these functions can be the same. The purpose
- of the inline version is purely to reduce code size impact.
+ The implementations of these functions can be the same. The purpose
+ of the inline version is purely to reduce code size impact.
- Add an ofnode function. This should call ofnode_is_np() to work out
- whether a livetree or flat tree is used. For the livetree it should
- call an of_...() function. For the flat tree it should call an
- fdt_...() function. The livetree version will be optimised out at
- compile time if livetree is not enabled.
+ whether a livetree or flat tree is used. For the livetree it should
+ call an of\_...() function. For the flat tree it should call an
+ fdt\_...() function. The livetree version will be optimised out at
+ compile time if livetree is not enabled.
- - Add an of_...() function for the livetree implementation. If a similar
- function is available in Linux, the implementation should be taken
- from there and modified as little as possible (generally not at all).
+ - Add an of\_...() function for the livetree implementation. If a similar
+ function is available in Linux, the implementation should be taken
+ from there and modified as little as possible (generally not at all).
Future work
- support for livetree modification
- addition of more access functions as needed
- support for livetree in SPL and before relocation (if desired)
-
-
---
-Simon Glass <sjg@chromium.org>
-5-Aug-17