summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBin Meng <bmeng.cn@gmail.com>2019-07-18 00:33:51 -0700
committerTom Rini <trini@konsulko.com>2019-07-24 10:07:24 -0400
commitf156aae25668a04da1226be35efa8c9ee11c18f4 (patch)
treedc0b1776c77fe02c9469904185977c73ceec9baf
parente1910d93b8906f9366f6661adca7a58d4b98dd61 (diff)
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>
-rw-r--r--doc/driver-model/fdt-fixup.rst (renamed from doc/driver-model/fdt-fixup.txt)56
-rw-r--r--doc/driver-model/index.rst1
2 files changed, 29 insertions, 28 deletions
diff --git a/doc/driver-model/fdt-fixup.txt b/doc/driver-model/fdt-fixup.rst
index 70344bd2c3..974c09031e 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
+
+ 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
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 663aa5d499..71ad062ab6 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