Documentation/devicetree/of_unittest.rst

1 .. SPDX-License-Identifier: GPL-2.0
18 (1) Documentation/devicetree/usage-model.rst
27 2. Test-data
30 The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
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
71 	struct  device_node *child;
76 Figure 1, describes a generic structure of machine's un-flattened device tree
77 considering only child and sibling pointers. There exists another pointer,
79 a particular level the child node and all the sibling nodes will have a parent
80 pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
81 parent points to root node)::
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
113     __dtb_testcases_begin - address marking the start of test data blob
114     __dtb_testcases_end   - address marking the end of test data blob
127     testcase-data
129     test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
131     test-child01      null             null             null
137 required to attach the root('/') node. All other nodes are attached by calling
138 of_attach_node() on each node.
140 In the function of_attach_node(), the new node is attached as the child of the
141 given parent in live tree. But, if parent already has a child then the new node
142 replaces the current child and turns it into its sibling. So, when the testcase
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,
188 If a duplicate node is found (i.e. if a node with same full_name property is
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 ---------------------------
203 To detach a node, of_detach_node() either updates the child pointer of given
204 node's parent to its sibling or attaches the previous sibling to the given
205 node's sibling, as appropriate. That is it :)