From f156aae25668a04da1226be35efa8c9ee11c18f4 Mon Sep 17 00:00:00 2001
From: Bin Meng <bmeng.cn@gmail.com>
Date: Thu, 18 Jul 2019 00:33:51 -0700
Subject: [PATCH] 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>
---
 .../{fdt-fixup.txt => fdt-fixup.rst}          | 56 +++++++++----------
 doc/driver-model/index.rst                    |  1 +
 2 files changed, 29 insertions(+), 28 deletions(-)
 rename doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst} (89%)

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 70344bd2c37..974c09031ed 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 @@ 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
 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 @@ unrecoverably halt the boot process, as with any function from init_sequence_f
 (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 @@ Device Tree Control
 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 @@ 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
 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 663aa5d499e..71ad062ab62 100644
--- a/doc/driver-model/index.rst
+++ b/doc/driver-model/index.rst
@@ -7,4 +7,5 @@ Driver Model
    :maxdepth: 2
 
    design
+   fdt-fixup
    migration