1.. SPDX-License-Identifier: GPL-2.0
2
3=================================
4Open Firmware Devicetree 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. Verbose Output (EXPECT)
28==========================
29
30If unittest detects a problem it will print a warning or error message to
31the console.  Unittest also triggers warning and error messages from other
32kernel code as a result of intentionally bad unittest data.  This has led
33to confusion as to whether the triggered messages are an expected result
34of a test or whether there is a real problem that is independent of unittest.
35
36'EXPECT \ : text' (begin) and 'EXPECT / : text' (end) messages have been
37added to unittest to report that a warning or error is expected.  The
38begin is printed before triggering the warning or error, and the end is
39printed after triggering the warning or error.
40
41The EXPECT messages result in very noisy console messages that are difficult
42to read.  The script scripts/dtc/of_unittest_expect was created to filter
43this verbosity and highlight mismatches between triggered warnings and
44errors vs expected warnings and errors.  More information is available
45from 'scripts/dtc/of_unittest_expect --help'.
46
47
483. Test-data
49============
50
51The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
52the test data required for executing the unit tests automated in
53drivers/of/unittest.c. Currently, following Device Tree Source Include files
54(.dtsi) are included in testcases.dts::
55
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
60
61When the kernel is build with OF_SELFTEST enabled, then the following make
62rule::
63
64    $(obj)/%.dtb: $(src)/%.dts FORCE
65	    $(call if_changed_dep, dtc)
66
67is used to compile the DT source file (testcases.dts) into a binary blob
68(testcases.dtb), also referred as flattened DT.
69
70After that, using the following rule the binary blob above is wrapped as an
71assembly file (testcases.dtb.S)::
72
73    $(obj)/%.dtb.S: $(obj)/%.dtb
74	    $(call cmd, dt_S_dtb)
75
76The assembly file is compiled into an object file (testcases.dtb.o), and is
77linked into the kernel image.
78
79
803.1. Adding the test data
81-------------------------
82
83Un-flattened device tree structure:
84
85Un-flattened device tree consists of connected device_node(s) in form of a tree
86structure described below::
87
88    // following struct members are used to construct the tree
89    struct device_node {
90	...
91	struct  device_node *parent;
92	struct  device_node *child;
93	struct  device_node *sibling;
94	...
95    };
96
97Figure 1, describes a generic structure of machine's un-flattened device tree
98considering only child and sibling pointers. There exists another pointer,
99``*parent``, that is used to traverse the tree in the reverse direction. So, at
100a particular level the child node and all the sibling nodes will have a parent
101pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
102parent points to root node)::
103
104    root ('/')
105    |
106    child1 -> sibling2 -> sibling3 -> sibling4 -> null
107    |         |           |           |
108    |         |           |          null
109    |         |           |
110    |         |        child31 -> sibling32 -> null
111    |         |           |          |
112    |         |          null       null
113    |         |
114    |      child21 -> sibling22 -> sibling23 -> null
115    |         |          |            |
116    |        null       null         null
117    |
118    child11 -> sibling12 -> sibling13 -> sibling14 -> null
119    |           |           |            |
120    |           |           |           null
121    |           |           |
122    null        null       child131 -> null
123			    |
124			    null
125
126Figure 1: Generic structure of un-flattened device tree
127
128
129Before executing OF unittest, it is required to attach the test data to
130machine's device tree (if present). So, when selftest_data_add() is called,
131at first it reads the flattened device tree data linked into the kernel image
132via the following kernel symbols::
133
134    __dtb_testcases_begin - address marking the start of test data blob
135    __dtb_testcases_end   - address marking the end of test data blob
136
137Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened
138blob. And finally, if the machine's device tree (i.e live tree) is present,
139then it attaches the unflattened test data tree to the live tree, else it
140attaches itself as a live device tree.
141
142attach_node_and_children() uses of_attach_node() to attach the nodes into the
143live tree as explained below. To explain the same, the test data tree described
144in Figure 2 is attached to the live tree described in Figure 1::
145
146    root ('/')
147	|
148    testcase-data
149	|
150    test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
151	|               |                |                |
152    test-child01      null             null             null
153
154
155Figure 2: Example test data tree to be attached to live tree.
156
157According to the scenario above, the live tree is already present so it isn't
158required to attach the root('/') node. All other nodes are attached by calling
159of_attach_node() on each node.
160
161In the function of_attach_node(), the new node is attached as the child of the
162given parent in live tree. But, if parent already has a child then the new node
163replaces the current child and turns it into its sibling. So, when the testcase
164data node is attached to the live tree above (Figure 1), the final structure is
165as shown in Figure 3::
166
167    root ('/')
168    |
169    testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
170    |               |          |           |           |
171    (...)             |          |           |          null
172		    |          |         child31 -> sibling32 -> null
173		    |          |           |           |
174		    |          |          null        null
175		    |          |
176		    |        child21 -> sibling22 -> sibling23 -> null
177		    |          |           |            |
178		    |         null        null         null
179		    |
180		    child11 -> sibling12 -> sibling13 -> sibling14 -> null
181		    |          |            |            |
182		    null       null          |           null
183					    |
184					    child131 -> null
185					    |
186					    null
187    -----------------------------------------------------------------------
188
189    root ('/')
190    |
191    testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
192    |               |          |           |           |
193    |             (...)      (...)       (...)        null
194    |
195    test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
196    |                |                   |                |
197    null             null                null         test-child01
198
199
200Figure 3: Live device tree structure after attaching the testcase-data.
201
202
203Astute readers would have noticed that test-child0 node becomes the last
204sibling compared to the earlier structure (Figure 2). After attaching first
205test-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,
207as mentioned above.
208
209If a duplicate node is found (i.e. if a node with same full_name property is
210already present in the live tree), then the node isn't attached rather its
211properties are updated to the live tree's node by calling the function
212update_node_properties().
213
214
2153.2. Removing the test data
216---------------------------
217
218Once the test case execution is complete, selftest_data_remove is called in
219order to remove the device nodes attached initially (first the leaf nodes are
220detached and then moving up the parent nodes are removed, and eventually the
221whole tree). selftest_data_remove() calls detach_node_and_children() that uses
222of_detach_node() to detach the nodes from the live device tree.
223
224To detach a node, of_detach_node() either updates the child pointer of given
225node's parent to its sibling or attaches the previous sibling to the given
226node's sibling, as appropriate. That is it :)
227