From: Bin Meng Date: Thu, 18 Jul 2019 07:33:51 +0000 (-0700) Subject: doc: driver-model: Convert fdt-fixup.txt to reST X-Git-Tag: v2019.10-rc1~16^2~44 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=f156aae25668a04da1226be35efa8c9ee11c18f4;p=oweals%2Fu-boot.git 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 --- diff --git a/doc/driver-model/fdt-fixup.rst b/doc/driver-model/fdt-fixup.rst new file mode 100644 index 0000000000..974c09031e --- /dev/null +++ b/doc/driver-model/fdt-fixup.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. 2017-01-06, Mario Six + +Pre-relocation device tree manipulation +======================================= + +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 +one series either don't differ greatly from another, or can be thought of as +"extensions" of each other, where one device only differs from another in the +addition of a small number of features (e.g. an additional output connector). + +To realize this in hardware, one method is to have a motherboard, and several +possible daughter boards that can be attached to this mother board. Different +daughter boards then either offer the slightly different functionality, or the +addition of the daughter board to the device realizes the "extension" of +functionality to the device described previously. + +For the software, we obviously want to reuse components for all these +variations of the device. This means that the software somehow needs to cope +with the situation that certain ICs may or may not be present on any given +system, depending on which daughter boards are connected to the motherboard. + +In the Linux kernel, one possible solution to this problem is to employ the +device tree overlay mechanism: There exists one "base" device tree, which +features only the components guaranteed to exist in all varieties of the +device. At the start of the kernel, the presence and type of the daughter +boards is then detected, and the corresponding device tree overlays are applied +to support the components on the daughter boards. + +Note that the components present on every variety of the board must, of course, +provide a way to find out if and which daughter boards are installed for this +mechanism to work. + +In the U-Boot boot loader, support for device tree overlays has recently been +integrated, and is used on some boards to alter the device tree that is later +passed to Linux. But since U-Boot's driver model, which is device tree-based as +well, is being used in more and more drivers, the same problem of altering the +device tree starts cropping up in U-Boot itself as well. + +An additional problem with the device tree in U-Boot is that it is read-only, +and the current mechanisms don't allow easy manipulation of the device tree +after the driver model has been initialized. While migrating to a live device +tree (at least after the relocation) would greatly simplify the solution of +this problem, it is a non-negligible task to implement it, an a interim +solution is needed to address the problem at least in the medium-term. + +Hence, we propose a solution to this problem by offering a board-specific +call-back function, which is passed a writeable pointer to the device tree. +This function is called before the device tree is relocated, and specifically +before the main U-Boot's driver model is instantiated, hence the main U-Boot +"sees" all modifications to the device tree made in this function. Furthermore, +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. + +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: + +.. 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 +include/fdt_support.h. The return value should either be 0 in case of +successful execution of the device tree manipulation or something else for a +failure. Note that returning a non-null value from the function will +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:: + + Device Tree Control + -> [*] Board-specific manipulation of Device Tree + ++----------------------------------------------------------+ +| WARNING: The actual manipulation of the device tree has | +| to be the _last_ set of operations in board_fix_fdt! | +| Since the pre-relocation driver model does not adapt to | +| changes made to the device tree either, its references | +| into the device tree will be invalid after manipulating | +| it, and unpredictable behavior might occur when | +| functions that rely on them are executed! | ++----------------------------------------------------------+ + +Hence, the recommended layout of the board_fixup_fdt call-back function is the +following: + +.. 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 */ + + /* 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. + +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 +not, since they are on daughter boards) on a I2C bus are queried for, and +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. + +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. diff --git a/doc/driver-model/fdt-fixup.txt b/doc/driver-model/fdt-fixup.txt deleted file mode 100644 index 70344bd2c3..0000000000 --- a/doc/driver-model/fdt-fixup.txt +++ /dev/null @@ -1,132 +0,0 @@ -Pre-relocation device tree manipulation -======================================= - -Contents: - -1. Purpose -2. Implementation -3. Example -4. Work to be done - -1. 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 -one series either don't differ greatly from another, or can be thought of as -"extensions" of each other, where one device only differs from another in the -addition of a small number of features (e.g. an additional output connector). - -To realize this in hardware, one method is to have a motherboard, and several -possible daughter boards that can be attached to this mother board. Different -daughter boards then either offer the slightly different functionality, or the -addition of the daughter board to the device realizes the "extension" of -functionality to the device described previously. - -For the software, we obviously want to reuse components for all these -variations of the device. This means that the software somehow needs to cope -with the situation that certain ICs may or may not be present on any given -system, depending on which daughter boards are connected to the motherboard. - -In the Linux kernel, one possible solution to this problem is to employ the -device tree overlay mechanism: There exists one "base" device tree, which -features only the components guaranteed to exist in all varieties of the -device. At the start of the kernel, the presence and type of the daughter -boards is then detected, and the corresponding device tree overlays are applied -to support the components on the daughter boards. - -Note that the components present on every variety of the board must, of course, -provide a way to find out if and which daughter boards are installed for this -mechanism to work. - -In the U-Boot boot loader, support for device tree overlays has recently been -integrated, and is used on some boards to alter the device tree that is later -passed to Linux. But since U-Boot's driver model, which is device tree-based as -well, is being used in more and more drivers, the same problem of altering the -device tree starts cropping up in U-Boot itself as well. - -An additional problem with the device tree in U-Boot is that it is read-only, -and the current mechanisms don't allow easy manipulation of the device tree -after the driver model has been initialized. While migrating to a live device -tree (at least after the relocation) would greatly simplify the solution of -this problem, it is a non-negligible task to implement it, an a interim -solution is needed to address the problem at least in the medium-term. - -Hence, we propose a solution to this problem by offering a board-specific -call-back function, which is passed a writeable pointer to the device tree. -This function is called before the device tree is relocated, and specifically -before the main U-Boot's driver model is instantiated, hence the main U-Boot -"sees" all modifications to the device tree made in this function. Furthermore, -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 ------------------ - -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) - -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 -include/fdt_support.h. The return value should either be 0 in case of -successful execution of the device tree manipulation or something else for a -failure. Note that returning a non-null value from the function will -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: - -Device Tree Control --> [*] Board-specific manipulation of Device Tree - -+----------------------------------------------------------+ -| WARNING: The actual manipulation of the device tree has | -| to be the _last_ set of operations in board_fix_fdt! | -| Since the pre-relocation driver model does not adapt to | -| changes made to the device tree either, its references | -| into the device tree will be invalid after manipulating | -| it, and unpredictable behavior might occur when | -| functions that rely on them are executed! | -+----------------------------------------------------------+ - -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 */ - - /* 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 ----------- - -The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a -board_fix_fdt function, in which six GPIO expanders (which might be present or -not, since they are on daughter boards) on a I2C bus are queried for, and -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 ------------------- - -* 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