doc: driver-model: Convert livetree.txt to reST
Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
This commit is contained in:
Bin Meng
Tom Rini
parent
61c3e77330
commit
6c49c22846
@ -10,4 +10,5 @@ Driver Model
|
||||
fdt-fixup
|
||||
fs_firmware_loader
|
||||
i2c-howto
|
||||
livetree
|
||||
migration
|
||||
|
||||
@ -1,5 +1,8 @@
|
||||
Driver Model with Live Device Tree
|
||||
==================================
|
||||
.. SPDX-License-Identifier: GPL-2.0+
|
||||
.. sectionauthor:: Simon Glass <sjg@chromium.org>
|
||||
|
||||
Live Device Tree
|
||||
================
|
||||
|
||||
|
||||
Introduction
|
||||
@ -20,7 +23,7 @@ Motivation
|
||||
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)
|
||||
|
||||
@ -53,12 +56,12 @@ 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
|
||||
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.
|
||||
|
||||
@ -85,6 +88,8 @@ converted to use the dev_read_() interface.
|
||||
|
||||
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);
|
||||
@ -94,17 +99,21 @@ For example, the old code may be like this:
|
||||
|
||||
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;
|
||||
|
||||
@ -115,6 +124,8 @@ back to using ofnode. For example, for old code like this:
|
||||
|
||||
you should use:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ofnode subnode;
|
||||
|
||||
ofnode_for_each_subnode(subnode, dev_ofnode(dev)) {
|
||||
@ -128,8 +139,8 @@ 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
|
||||
: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
|
||||
@ -149,20 +160,29 @@ 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
|
||||
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
|
||||
@ -199,13 +219,13 @@ the flat tree.
|
||||
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
|
||||
@ -225,7 +245,7 @@ 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
|
||||
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.
|
||||
|
||||
@ -236,23 +256,22 @@ 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
|
||||
- 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
|
||||
@ -265,8 +284,3 @@ of work to do to flesh this out:
|
||||
- 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
Block a user