Browse Source

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>
Bin Meng 4 years ago
parent
commit
6c49c22846
2 changed files with 55 additions and 40 deletions
  1. 1 0
      doc/driver-model/index.rst
  2. 54 40
      doc/driver-model/livetree.rst

+ 1 - 0
doc/driver-model/index.rst

@@ -10,4 +10,5 @@ Driver Model
    fdt-fixup
    fdt-fixup
    fs_firmware_loader
    fs_firmware_loader
    i2c-howto
    i2c-howto
+   livetree
    migration
    migration

+ 54 - 40
doc/driver-model/livetree.txt → doc/driver-model/livetree.rst

@@ -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
 Introduction
@@ -20,7 +23,7 @@ Motivation
 The flat device tree has several advantages:
 The flat device tree has several advantages:
 
 
 - it is the format produced by the device tree compiler, so no translation
 - 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)
 - 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
 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.
 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
 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
 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.
 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:
 For example, the old code may be like this:
 
 
+.. code-block:: c
+
     struct udevice *bus;
     struct udevice *bus;
     const void *blob = gd->fdt_blob;
     const void *blob = gd->fdt_blob;
     int node = dev_of_offset(bus);
     int node = dev_of_offset(bus);
@@ -94,17 +99,21 @@ For example, the old code may be like this:
 
 
 The new code is:
 The new code is:
 
 
+.. code-block:: c
+
     struct udevice *bus;
     struct udevice *bus;
 
 
     i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
     i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
     plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000);
     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.
 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
 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:
 back to using ofnode. For example, for old code like this:
 
 
+.. code-block:: c
+
     const void *blob = gd->fdt_blob;
     const void *blob = gd->fdt_blob;
     int subnode;
     int subnode;
 
 
@@ -115,6 +124,8 @@ back to using ofnode. For example, for old code like this:
 
 
 you should use:
 you should use:
 
 
+.. code-block:: c
+
     ofnode subnode;
     ofnode subnode;
 
 
     ofnode_for_each_subnode(subnode, dev_ofnode(dev)) {
     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 :
 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
 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
 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
 used. Similarly it is not possible to call ofnode_to_offset() on a livetree
 node.
 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:
 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
 Phandles
@@ -199,13 +219,13 @@ the flat tree.
 Internal implementation
 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
 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 directly. This is useful when livetree is not enabled. The ofnode
 functions call ofnode_is_np(node) which will always return false if livetree
 functions call ofnode_is_np(node) which will always return false if livetree
 is disabled, just falling back to flat tree code.
 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.
 ofnode interfaces do not noticeably add to code size.
 
 
 The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is
 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).
 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
 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
 error. This is clearly not desirable. Once tests are added for all the
 functions this can be tidied up.
 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:
 Adding a new function for device-tree access involves the following steps:
 
 
    - Add two dev_read() functions:
    - 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
    - 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
 Future work
@@ -265,8 +284,3 @@ of work to do to flesh this out:
 - support for livetree modification
 - support for livetree modification
 - addition of more access functions as needed
 - addition of more access functions as needed
 - support for livetree in SPL and before relocation (if desired)
 - support for livetree in SPL and before relocation (if desired)
-
-
---
-Simon Glass <sjg@chromium.org>
-5-Aug-17