diff options
author | Bin Meng <bmeng.cn@gmail.com> | 2019-07-18 10:33:51 +0300 |
---|---|---|
committer | Tom Rini <trini@konsulko.com> | 2019-07-24 17:07:24 +0300 |
commit | f156aae25668a04da1226be35efa8c9ee11c18f4 (patch) | |
tree | dc0b1776c77fe02c9469904185977c73ceec9baf | |
parent | e1910d93b8906f9366f6661adca7a58d4b98dd61 (diff) | |
download | u-boot-f156aae25668a04da1226be35efa8c9ee11c18f4.tar.xz |
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.rst | 1 |
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 |