From 6c49c22846807375caf434b08f8f2b9d48cf5513 Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Thu, 18 Jul 2019 00:33:54 -0700 Subject: [PATCH] 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 --- doc/driver-model/index.rst | 1 + .../{livetree.txt => livetree.rst} | 94 +++++++++++-------- 2 files changed, 55 insertions(+), 40 deletions(-) rename doc/driver-model/{livetree.txt => livetree.rst} (77%) diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst index ce857a3596..ff9b18350c 100644 --- a/doc/driver-model/index.rst +++ b/doc/driver-model/index.rst @@ -10,4 +10,5 @@ Driver Model fdt-fixup fs_firmware_loader i2c-howto + livetree migration diff --git a/doc/driver-model/livetree.txt b/doc/driver-model/livetree.rst similarity index 77% rename from doc/driver-model/livetree.txt rename to doc/driver-model/livetree.rst index 01d4488c60..9f654f3b89 100644 --- a/doc/driver-model/livetree.txt +++ b/doc/driver-model/livetree.rst @@ -1,5 +1,8 @@ -Driver Model with Live Device Tree -================================== +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass + +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 -5-Aug-17 -- 2.25.1