Add some documentation for the live device tree support in U-Boot. This was missing from the initial series. Signed-off-by: Simon Glass <sjg@chromium.org> Suggested-by: Lukasz Majewski <lukma@denx.de> Reviewed-by: Łukasz Majewski <lukma@denx.de>master
parent
34e2c285da
commit
d944bf6b5e
@ -0,0 +1,272 @@ |
||||
Driver Model with Live Device Tree |
||||
================================== |
||||
|
||||
|
||||
Introduction |
||||
------------ |
||||
|
||||
Traditionally U-Boot has used a 'flat' device tree. This means that it |
||||
reads directly from the device tree binary structure. It is called a flat |
||||
device tree because nodes are listed one after the other, with the |
||||
hierarchy detected by tags in the format. |
||||
|
||||
This document describes U-Boot's support for a 'live' device tree, meaning |
||||
that the tree is loaded into a hierarchical data structure within U-Boot. |
||||
|
||||
|
||||
Motivation |
||||
---------- |
||||
|
||||
The flat device tree has several advantages: |
||||
|
||||
- it is the format produced by the device tree compiler, so no translation |
||||
is needed |
||||
|
||||
- it is fairly compact (e.g. there is no need for pointers) |
||||
|
||||
- it is accessed by the libfdt library, which is well tested and stable |
||||
|
||||
|
||||
However the flat device tree does have some limitations. Adding new |
||||
properties can involve copying large amounts of data around to make room. |
||||
The overall tree has a fixed maximum size so sometimes the tree must be |
||||
rebuilt in a new location to create more space. Even if not adding new |
||||
properties or nodes, scanning the tree can be slow. For example, finding |
||||
the parent of a node is a slow process. Reading from nodes involves a |
||||
small amount parsing which takes a little time. |
||||
|
||||
Driver model scans the entire device tree sequentially on start-up which |
||||
avoids the worst of the flat tree's limitations. But if the tree is to be |
||||
modified at run-time, a live tree is much faster. Even if no modification |
||||
is necessary, parsing the tree once and using a live tree from then on |
||||
seems to save a little time. |
||||
|
||||
|
||||
Implementation |
||||
-------------- |
||||
|
||||
In U-Boot a live device tree ('livetree') is currently supported only |
||||
after relocation. Therefore we need a mechanism to specify a device |
||||
tree node regardless of whether it is in the flat tree or livetree. |
||||
|
||||
The 'ofnode' type provides this. An ofnode can point to either a flat tree |
||||
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 |
||||
makes sense to be able to read device tree properties using the |
||||
'struct udevice *', rather than having to obtain the ofnode first. |
||||
|
||||
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. |
||||
|
||||
|
||||
Enabling livetree |
||||
----------------- |
||||
|
||||
CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat |
||||
tree will be used in SPL and before relocation in U-Boot proper. Just |
||||
before relocation a livetree is built, and this is used for U-Boot proper |
||||
after relocation. |
||||
|
||||
Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that |
||||
for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does |
||||
not exist, since SPL does not support livetree. |
||||
|
||||
|
||||
Porting drivers |
||||
--------------- |
||||
|
||||
Many existing drivers use the fdtdec interface to read device tree |
||||
properties. This only works with a flat device tree. The drivers should be |
||||
converted to use the dev_read_() interface. |
||||
|
||||
For example, the old code may be like this: |
||||
|
||||
struct udevice *bus; |
||||
const void *blob = gd->fdt_blob; |
||||
int node = dev_of_offset(bus); |
||||
|
||||
i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev); |
||||
plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); |
||||
|
||||
The new code is: |
||||
|
||||
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 |
||||
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: |
||||
|
||||
const void *blob = gd->fdt_blob; |
||||
int subnode; |
||||
|
||||
fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) { |
||||
freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); |
||||
... |
||||
} |
||||
|
||||
you should use: |
||||
|
||||
ofnode subnode; |
||||
|
||||
ofnode_for_each_subnode(subnode, dev_ofnode(dev)) { |
||||
freq = ofnode_read_u32(node, "spi-max-frequency", 500000); |
||||
... |
||||
} |
||||
|
||||
|
||||
Useful ofnode functions |
||||
----------------------- |
||||
|
||||
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 |
||||
|
||||
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 |
||||
tree. |
||||
|
||||
Properties have pointers to the next property. This allows all properties of |
||||
a node to be linked together in a chain. |
||||
|
||||
It should not be necessary to use these data structures in normal code. In |
||||
particular, you should refrain from using functions which access the livetree |
||||
directly, such as of_read_u32(). Use ofnode functions instead, to allow your |
||||
code to work with a flat tree also. |
||||
|
||||
Some conversion functions are used internally. Generally these are not needed |
||||
for driver code. Note that they will not work if called in the wrong context. |
||||
For example it is invalid to call ofnode_to_no() when a flat tree is being |
||||
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 |
||||
|
||||
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) |
||||
|
||||
|
||||
Phandles |
||||
-------- |
||||
|
||||
There is full phandle support for live tree. All functions make use of |
||||
struct ofnode_phandle_args, which has an ofnode within it. This supports both |
||||
livetree and flat tree transparently. See for example |
||||
ofnode_parse_phandle_with_args(). |
||||
|
||||
|
||||
Reading addresses |
||||
----------------- |
||||
|
||||
You should use dev_read_addr() and friends to read addresses from device-tree |
||||
nodes. |
||||
|
||||
|
||||
fdtdec |
||||
------ |
||||
|
||||
The existing fdtdec interface will eventually be retired. Please try to avoid |
||||
using it in new code. |
||||
|
||||
|
||||
Modifying the livetree |
||||
---------------------- |
||||
|
||||
This is not currently supported. Once implemented it should provide a much |
||||
more efficient implementation for modification of the device tree than using |
||||
the flat tree. |
||||
|
||||
|
||||
Internal implementation |
||||
----------------------- |
||||
|
||||
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 |
||||
ofnode interfaces do not noticeably add to code size. |
||||
|
||||
The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is |
||||
disabled. |
||||
|
||||
Most livetree code comes directly from Linux and is modified as little as |
||||
possible. This is deliberate since this code is fairly stable and does what |
||||
we want. Some features (such as get/put) are not supported. Internal macros |
||||
take care of removing these features silently. |
||||
|
||||
Within the of_access.c file there are pointers to the alias node, the chosen |
||||
node and the stdout-path alias. |
||||
|
||||
|
||||
Errors |
||||
------ |
||||
|
||||
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 |
||||
error. This is clearly not desirable. Once tests are added for all the |
||||
functions this can be tidied up. |
||||
|
||||
|
||||
Adding new access functions |
||||
--------------------------- |
||||
|
||||
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 |
||||
|
||||
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. |
||||
|
||||
- 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 |
||||
----------- |
||||
|
||||
Live tree support was introduced in U-Boot 2017.07. There is still quite a bit |
||||
of work to do to flesh this out: |
||||
|
||||
- tests for all access functions |
||||
- 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 |
Loading…
Reference in new issue