From f156aae25668a04da1226be35efa8c9ee11c18f4 Mon Sep 17 00:00:00 2001 From: Bin Meng 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 --- .../{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 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 + 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 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 -- 2.39.5