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