Browse Source

doc: driver-model: Convert fdt-fixup.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
f156aae256
2 changed files with 29 additions and 28 deletions
  1. 28 28
      doc/driver-model/fdt-fixup.rst
  2. 1 0
      doc/driver-model/index.rst

+ 28 - 28
doc/driver-model/fdt-fixup.txt → doc/driver-model/fdt-fixup.rst

@@ -1,15 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. 2017-01-06, Mario Six <mario.six@gdsys.cc>
+
 Pre-relocation device tree manipulation
 Pre-relocation device tree manipulation
 =======================================
 =======================================
 
 
-Contents:
-
-1. Purpose
-2. Implementation
-3. Example
-4. Work to be done
-
-1. Purpose
-----------
+Purpose
+-------
 
 
 In certain markets, it is beneficial for manufacturers of embedded devices to
 In certain markets, it is beneficial for manufacturers of embedded devices to
 offer certain ranges of products, where the functionality of the devices within
 offer certain ranges of products, where the functionality of the devices within
@@ -61,14 +57,16 @@ we have the pre-relocation driver model at our disposal at this stage, which
 means that we can query the hardware for the existence and variety of the
 means that we can query the hardware for the existence and variety of the
 components easily.
 components easily.
 
 
-2. Implementation
------------------
+Implementation
+--------------
 
 
 To take advantage of the pre-relocation device tree manipulation mechanism,
 To take advantage of the pre-relocation device tree manipulation mechanism,
 boards have to implement the function board_fix_fdt, which has the following
 boards have to implement the function board_fix_fdt, which has the following
 signature:
 signature:
 
 
-int board_fix_fdt (void *rw_fdt_blob)
+.. code-block:: c
+
+   int board_fix_fdt (void *rw_fdt_blob)
 
 
 The passed-in void pointer is a writeable pointer to the device tree, which can
 The passed-in void pointer is a writeable pointer to the device tree, which can
 be used to manipulate the device tree using e.g. functions from
 be used to manipulate the device tree using e.g. functions from
@@ -79,10 +77,10 @@ unrecoverably halt the boot process, as with any function from init_sequence_f
 (in common/board_f.c).
 (in common/board_f.c).
 
 
 Furthermore, the Kconfig option OF_BOARD_FIXUP has to be set for the function
 Furthermore, the Kconfig option OF_BOARD_FIXUP has to be set for the function
-to be called:
+to be called::
 
 
-Device Tree Control
--> [*] Board-specific manipulation of Device Tree
+   Device Tree Control
+   -> [*] Board-specific manipulation of Device Tree
 
 
 +----------------------------------------------------------+
 +----------------------------------------------------------+
 | WARNING: The actual manipulation of the device tree has  |
 | WARNING: The actual manipulation of the device tree has  |
@@ -97,23 +95,27 @@ Device Tree Control
 Hence, the recommended layout of the board_fixup_fdt call-back function is the
 Hence, the recommended layout of the board_fixup_fdt call-back function is the
 following:
 following:
 
 
-int board_fix_fdt(void *rw_fdt_blob)
-{
-	/* Collect information about device's hardware and store them in e.g.
-	   local variables */
+.. code-block:: c
+
+	int board_fix_fdt(void *rw_fdt_blob)
+	{
+		/*
+		 * Collect information about device's hardware and store
+		 * them in e.g. local variables
+		 */
 
 
-	/* Do device tree manipulation using the values previously collected */
+		/* Do device tree manipulation using the values previously collected */
 
 
-	/* Return 0 on successful manipulation and non-zero otherwise */
-}
+		/* Return 0 on successful manipulation and non-zero otherwise */
+	}
 
 
 If this convention is kept, both an "additive" approach, meaning that nodes for
 If this convention is kept, both an "additive" approach, meaning that nodes for
 detected components are added to the device tree, as well as a "subtractive"
 detected components are added to the device tree, as well as a "subtractive"
 approach, meaning that nodes for absent components are removed from the tree,
 approach, meaning that nodes for absent components are removed from the tree,
 as well as a combination of both approaches should work.
 as well as a combination of both approaches should work.
 
 
-3. Example
-----------
+Example
+-------
 
 
 The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a
 The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a
 board_fix_fdt function, in which six GPIO expanders (which might be present or
 board_fix_fdt function, in which six GPIO expanders (which might be present or
@@ -123,10 +125,8 @@ subsequently deactivated in the device tree if they are not present.
 Note that the dm_i2c_simple_probe function does not use the device tree, hence
 Note that the dm_i2c_simple_probe function does not use the device tree, hence
 it is safe to call it after the tree has already been manipulated.
 it is safe to call it after the tree has already been manipulated.
 
 
-4. Work to be done
-------------------
+Work to be done
+---------------
 
 
 * The application of device tree overlay should be possible in board_fixup_fdt,
 * The application of device tree overlay should be possible in board_fixup_fdt,
   but has not been tested at this stage.
   but has not been tested at this stage.
-
-2017-01-06, Mario Six <mario.six@gdsys.cc>

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

@@ -7,4 +7,5 @@ Driver Model
    :maxdepth: 2
    :maxdepth: 2
 
 
    design
    design
+   fdt-fixup
    migration
    migration