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>
diff --git a/doc/driver-model/fdt-fixup.txt b/doc/driver-model/fdt-fixup.rst
similarity index 89%
rename from doc/driver-model/fdt-fixup.txt
rename to doc/driver-model/fdt-fixup.rst
index 70344bd..974c090 100644
--- a/doc/driver-model/fdt-fixup.txt
+++ b/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
=======================================
-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
offer certain ranges of products, where the functionality of the devices within
@@ -61,14 +57,16 @@
means that we can query the hardware for the existence and variety of the
components easily.
-2. Implementation
------------------
+Implementation
+--------------
To take advantage of the pre-relocation device tree manipulation mechanism,
boards have to implement the function board_fix_fdt, which has the following
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
be used to manipulate the device tree using e.g. functions from
@@ -79,10 +77,10 @@
(in common/board_f.c).
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 |
@@ -97,23 +95,27 @@
Hence, the recommended layout of the board_fixup_fdt call-back function is the
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
- /* Do device tree manipulation using the values previously collected */
+ int board_fix_fdt(void *rw_fdt_blob)
+ {
+ /*
+ * Collect information about device's hardware and store
+ * them in e.g. local variables
+ */
- /* Return 0 on successful manipulation and non-zero otherwise */
-}
+ /* Do device tree manipulation using the values previously collected */
+
+ /* Return 0 on successful manipulation and non-zero otherwise */
+ }
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"
approach, meaning that nodes for absent components are removed from the tree,
as well as a combination of both approaches should work.
-3. Example
-----------
+Example
+-------
The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a
board_fix_fdt function, in which six GPIO expanders (which might be present or
@@ -123,10 +125,8 @@
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.
-4. Work to be done
-------------------
+Work to be done
+---------------
* The application of device tree overlay should be possible in board_fixup_fdt,
but has not been tested at this stage.
-
-2017-01-06, Mario Six <mario.six@gdsys.cc>
diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst
index 663aa5d..71ad062 100644
--- a/doc/driver-model/index.rst
+++ b/doc/driver-model/index.rst
@@ -7,4 +7,5 @@
:maxdepth: 2
design
+ fdt-fixup
migration