doc/driver-model/fdt-fixup.txt

1 Pre-relocation device tree manipulation
12 ----------
17 "extensions" of each other, where one device only differs from another in the
23 addition of the daughter board to the device realizes the "extension" of
24 functionality to the device described previously.
27 variations of the device. This means that the software somehow needs to cope
32 device tree overlay mechanism: There exists one "base" device tree, which
34 device. At the start of the kernel, the presence and type of the daughter
35 boards is then detected, and the corresponding device tree overlays are applied
42 In the U-Boot boot loader, support for device tree overlays has recently been
43 integrated, and is used on some boards to alter the device tree that is later
44 passed to Linux. But since U-Boot's driver model, which is device tree-based as
46 device tree starts cropping up in U-Boot itself as well.
48 An additional problem with the device tree in U-Boot is that it is read-only,
49 and the current mechanisms don't allow easy manipulation of the device tree
50 after the driver model has been initialized. While migrating to a live device
51 tree (at least after the relocation) would greatly simplify the solution of
52 this problem, it is a non-negligible task to implement it, an a interim
53 solution is needed to address the problem at least in the medium-term.
55 Hence, we propose a solution to this problem by offering a board-specific
56 call-back function, which is passed a writeable pointer to the device tree.
57 This function is called before the device tree is relocated, and specifically
58 before the main U-Boot's driver model is instantiated, hence the main U-Boot
59 "sees" all modifications to the device tree made in this function. Furthermore,
60 we have the pre-relocation driver model at our disposal at this stage, which
65 -----------------
67 To take advantage of the pre-relocation device tree manipulation mechanism,
73 The passed-in void pointer is a writeable pointer to the device tree, which can
74 be used to manipulate the device tree using e.g. functions from
76 successful execution of the device tree manipulation or something else for a
77 failure. Note that returning a non-null value from the function will
84 Device Tree Control
85 -> [*] Board-specific manipulation of Device Tree
87 +----------------------------------------------------------+
88 | WARNING: The actual manipulation of the device tree has  |
90 | Since the pre-relocation driver model does not adapt to  |
91 | changes made to the device tree either, its references   |
92 | into the device tree will be invalid after manipulating  |
95 +----------------------------------------------------------+
97 Hence, the recommended layout of the board_fixup_fdt call-back function is the
102 	/* Collect information about device's hardware and store them in e.g.
105 	/* Do device tree manipulation using the values previously collected */
107 	/* Return 0 on successful manipulation and non-zero otherwise */
111 detected components are added to the device tree, as well as a "subtractive"
112 approach, meaning that nodes for absent components are removed from the tree,
116 ----------
121 subsequently deactivated in the device tree if they are not present.
123 Note that the dm_i2c_simple_probe function does not use the device tree, hence
124 it is safe to call it after the tree has already been manipulated.
127 ------------------
129 * The application of device tree overlay should be possible in board_fixup_fdt,
132 2017-01-06, Mario Six <mario.six@gdsys.cc>