1.. SPDX-License-Identifier: GPL-2.0
2
3==================================
4Open Firmware Device Tree Unittest
5==================================
6
7Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>
8
91. Introduction
10===============
11
12This document explains how the test data required for executing OF unittest
13is attached to the live tree dynamically, independent of the machine's
14architecture.
15
16It is recommended to read the following documents before moving ahead.
17
18(1) Documentation/devicetree/usage-model.rst
19(2) http://www.devicetree.org/Device_Tree_Usage
20
21OF Selftest has been designed to test the interface (include/linux/of.h)
22provided to device driver developers to fetch the device information..etc.
23from the unflattened device tree data structure. This interface is used by
24most of the device drivers in various use cases.
25
26
272. Test-data
28============
29
30The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
31the test data required for executing the unit tests automated in
32drivers/of/unittest.c. Currently, following Device Tree Source Include files
33(.dtsi) are included in testcases.dts::
34
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
39
40When the kernel is build with OF_SELFTEST enabled, then the following make
41rule::
42
43    $(obj)/%.dtb: $(src)/%.dts FORCE
44	    $(call if_changed_dep, dtc)
45
46is used to compile the DT source file (testcases.dts) into a binary blob
47(testcases.dtb), also referred as flattened DT.
48
49After that, using the following rule the binary blob above is wrapped as an
50assembly file (testcases.dtb.S)::
51
52    $(obj)/%.dtb.S: $(obj)/%.dtb
53	    $(call cmd, dt_S_dtb)
54
55The assembly file is compiled into an object file (testcases.dtb.o), and is
56linked into the kernel image.
57
58
592.1. Adding the test data
60-------------------------
61
62Un-flattened device tree structure:
63
64Un-flattened device tree consists of connected device_node(s) in form of a tree
65structure described below::
66
67    // following struct members are used to construct the tree
68    struct device_node {
69	...
70	struct  device_node *parent;
71	struct  device_node *child;
72	struct  device_node *sibling;
73	...
74    };
75
76Figure 1, describes a generic structure of machine's un-flattened device tree
77considering only child and sibling pointers. There exists another pointer,
78``*parent``, that is used to traverse the tree in the reverse direction. So, at
79a particular level the child node and all the sibling nodes will have a parent
80pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
81parent points to root node)::
82
83    root ('/')
84    |
85    child1 -> sibling2 -> sibling3 -> sibling4 -> null
86    |         |           |           |
87    |         |           |          null
88    |         |           |
89    |         |        child31 -> sibling32 -> null
90    |         |           |          |
91    |         |          null       null
92    |         |
93    |      child21 -> sibling22 -> sibling23 -> null
94    |         |          |            |
95    |        null       null         null
96    |
97    child11 -> sibling12 -> sibling13 -> sibling14 -> null
98    |           |           |            |
99    |           |           |           null
100    |           |           |
101    null        null       child131 -> null
102			    |
103			    null
104
105Figure 1: Generic structure of un-flattened device tree
106
107
108Before executing OF unittest, it is required to attach the test data to
109machine's device tree (if present). So, when selftest_data_add() is called,
110at first it reads the flattened device tree data linked into the kernel image
111via the following kernel symbols::
112
113    __dtb_testcases_begin - address marking the start of test data blob
114    __dtb_testcases_end   - address marking the end of test data blob
115
116Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened
117blob. And finally, if the machine's device tree (i.e live tree) is present,
118then it attaches the unflattened test data tree to the live tree, else it
119attaches itself as a live device tree.
120
121attach_node_and_children() uses of_attach_node() to attach the nodes into the
122live tree as explained below. To explain the same, the test data tree described
123in Figure 2 is attached to the live tree described in Figure 1::
124
125    root ('/')
126	|
127    testcase-data
128	|
129    test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
130	|               |                |                |
131    test-child01      null             null             null
132
133
134Figure 2: Example test data tree to be attached to live tree.
135
136According to the scenario above, the live tree is already present so it isn't
137required to attach the root('/') node. All other nodes are attached by calling
138of_attach_node() on each node.
139
140In the function of_attach_node(), the new node is attached as the child of the
141given parent in live tree. But, if parent already has a child then the new node
142replaces the current child and turns it into its sibling. So, when the testcase
143data node is attached to the live tree above (Figure 1), the final structure is
144as shown in Figure 3::
145
146    root ('/')
147    |
148    testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
149    |               |          |           |           |
150    (...)             |          |           |          null
151		    |          |         child31 -> sibling32 -> null
152		    |          |           |           |
153		    |          |          null        null
154		    |          |
155		    |        child21 -> sibling22 -> sibling23 -> null
156		    |          |           |            |
157		    |         null        null         null
158		    |
159		    child11 -> sibling12 -> sibling13 -> sibling14 -> null
160		    |          |            |            |
161		    null       null          |           null
162					    |
163					    child131 -> null
164					    |
165					    null
166    -----------------------------------------------------------------------
167
168    root ('/')
169    |
170    testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
171    |               |          |           |           |
172    |             (...)      (...)       (...)        null
173    |
174    test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
175    |                |                   |                |
176    null             null                null         test-child01
177
178
179Figure 3: Live device tree structure after attaching the testcase-data.
180
181
182Astute readers would have noticed that test-child0 node becomes the last
183sibling compared to the earlier structure (Figure 2). After attaching first
184test-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,
186as mentioned above.
187
188If a duplicate node is found (i.e. if a node with same full_name property is
189already present in the live tree), then the node isn't attached rather its
190properties are updated to the live tree's node by calling the function
191update_node_properties().
192
193
1942.2. Removing the test data
195---------------------------
196
197Once the test case execution is complete, selftest_data_remove is called in
198order to remove the device nodes attached initially (first the leaf nodes are
199detached and then moving up the parent nodes are removed, and eventually the
200whole tree). selftest_data_remove() calls detach_node_and_children() that uses
201of_detach_node() to detach the nodes from the live device tree.
202
203To detach a node, of_detach_node() either updates the child pointer of given
204node's parent to its sibling or attaches the previous sibling to the given
205node's sibling, as appropriate. That is it :)
206