|
@@ -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>
|