Documentation/devicetree/of_unittest.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 Open Firmware Device Tree Unittest
13 is attached to the live tree dynamically, independent of the machine's
18 (1) Documentation/devicetree/usage-model.rst
22 provided to device driver developers to fetch the device information..etc.
23 from the unflattened device tree data structure. This interface is used by
24 most of the device drivers in various use cases.
27 2. Test-data
30 The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
32 drivers/of/unittest.c. Currently, following Device Tree Source Include files
35     drivers/of/unittest-data/tests-interrupts.dtsi
36     drivers/of/unittest-data/tests-platform.dtsi
37     drivers/of/unittest-data/tests-phandle.dtsi
38     drivers/of/unittest-data/tests-match.dtsi
60 -------------------------
62 Un-flattened device tree structure:
64 Un-flattened device tree consists of connected device_node(s) in form of a tree
67     // following struct members are used to construct the tree
76 Figure 1, describes a generic structure of machine's un-flattened device tree
78 ``*parent``, that is used to traverse the tree in the reverse direction. So, at
85     child1 -> sibling2 -> sibling3 -> sibling4 -> null
89     |         |        child31 -> sibling32 -> null
93     |      child21 -> sibling22 -> sibling23 -> null
97     child11 -> sibling12 -> sibling13 -> sibling14 -> null
101     null        null       child131 -> null
105 Figure 1: Generic structure of un-flattened device tree
109 machine's device tree (if present). So, when selftest_data_add() is called,
110 at first it reads the flattened device tree data linked into the kernel image
113     __dtb_testcases_begin - address marking the start of test data blob
114     __dtb_testcases_end   - address marking the end of test data blob
117 blob. And finally, if the machine's device tree (i.e live tree) is present,
118 then it attaches the unflattened test data tree to the live tree, else it
119 attaches itself as a live device tree.
122 live tree as explained below. To explain the same, the test data tree described
123 in Figure 2 is attached to the live tree described in Figure 1::
127     testcase-data
129     test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
131     test-child01      null             null             null
134 Figure 2: Example test data tree to be attached to live tree.
136 According to the scenario above, the live tree is already present so it isn't
141 given parent in live tree. But, if parent already has a child then the new node
143 data node is attached to the live tree above (Figure 1), the final structure is
148     testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
151 		    |          |         child31 -> sibling32 -> null
155 		    |        child21 -> sibling22 -> sibling23 -> null
159 		    child11 -> sibling12 -> sibling13 -> sibling14 -> null
163 					    child131 -> null
166     -----------------------------------------------------------------------
170     testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
174     test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
176     null             null                null         test-child01
179 Figure 3: Live device tree structure after attaching the testcase-data.
182 Astute readers would have noticed that test-child0 node becomes the last
184 test-child0 the test-sibling1 is attached that pushes the child node
185 (i.e. test-child0) to become a sibling and makes itself a child node,
189 already present in the live tree), then the node isn't attached rather its
190 properties are updated to the live tree's node by calling the function
195 ---------------------------
198 order to remove the device nodes attached initially (first the leaf nodes are
200 whole tree). selftest_data_remove() calls detach_node_and_children() that uses
201 of_detach_node() to detach the nodes from the live device tree.