Documentation/devicetree/of_unittest.rst

1 .. SPDX-License-Identifier: GPL-2.0
18 (1) Documentation/devicetree/usage-model.rst
45 from 'scripts/dtc/of_unittest_expect --help'.
48 3. Test-data
51 The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
54 (.dtsi) are included in testcases.dts::
56     drivers/of/unittest-data/tests-interrupts.dtsi
57     drivers/of/unittest-data/tests-platform.dtsi
58     drivers/of/unittest-data/tests-phandle.dtsi
59     drivers/of/unittest-data/tests-match.dtsi
64     $(obj)/%.dtb: $(src)/%.dts FORCE
67 is used to compile the DT source file (testcases.dts) into a binary blob
81 -------------------------
83 Un-flattened device tree structure:
85 Un-flattened device tree consists of connected device_node(s) in form of a tree
97 Figure 1, describes a generic structure of machine's un-flattened device tree
100 a particular level the child node and all the sibling nodes will have a parent
101 pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
102 parent points to root node)::
106     child1 -> sibling2 -> sibling3 -> sibling4 -> null
110     |         |        child31 -> sibling32 -> null
114     |      child21 -> sibling22 -> sibling23 -> null
118     child11 -> sibling12 -> sibling13 -> sibling14 -> null
122     null        null       child131 -> null
126 Figure 1: Generic structure of un-flattened device tree
134     __dtb_testcases_begin - address marking the start of test data blob
135     __dtb_testcases_end   - address marking the end of test data blob
148     testcase-data
150     test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
152     test-child01      null             null             null
158 required to attach the root('/') node. All other nodes are attached by calling
159 of_attach_node() on each node.
161 In the function of_attach_node(), the new node is attached as the child of the
162 given parent in live tree. But, if parent already has a child then the new node
164 data node is attached to the live tree above (Figure 1), the final structure is
169     testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
172 		    |          |         child31 -> sibling32 -> null
176 		    |        child21 -> sibling22 -> sibling23 -> null
180 		    child11 -> sibling12 -> sibling13 -> sibling14 -> null
184 					    child131 -> null
187     -----------------------------------------------------------------------
191     testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
195     test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
197     null             null                null         test-child01
200 Figure 3: Live device tree structure after attaching the testcase-data.
203 Astute readers would have noticed that test-child0 node becomes the last
205 test-child0 the test-sibling1 is attached that pushes the child node
206 (i.e. test-child0) to become a sibling and makes itself a child node,
209 If a duplicate node is found (i.e. if a node with same full_name property is
210 already present in the live tree), then the node isn't attached rather its
211 properties are updated to the live tree's node by calling the function
216 ---------------------------
224 To detach a node, of_detach_node() either updates the child pointer of given
225 node's parent to its sibling or attaches the previous sibling to the given
226 node's sibling, as appropriate. That is it :)