[U-Boot,09/50] doc: driver-model: Convert livetree.txt to reST
diff mbox series

Message ID 1563435275-22326-10-git-send-email-bmeng.cn@gmail.com
State Accepted
Delegated to: Tom Rini
Headers show
Series
  • doc: Shape into useful HTML docs
Related show

Commit Message

Bin Meng July 18, 2019, 7:33 a.m. UTC
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>
---

 doc/driver-model/index.rst                      |  1 +
 doc/driver-model/{livetree.txt => livetree.rst} | 94 ++++++++++++++-----------
 2 files changed, 55 insertions(+), 40 deletions(-)
 rename doc/driver-model/{livetree.txt => livetree.rst} (77%)

Patch
diff mbox series

diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst
index ce857a3..ff9b183 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 01d4488..9f654f3 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 <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