Commit | Line | Data |
---|---|---|
7a39086d | 1 | Open Firmware Device Tree Unittest |
b9c74fd7 GM |
2 | ---------------------------------- |
3 | ||
4 | Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> | |
5 | ||
6 | 1. Introduction | |
7 | ||
7a39086d | 8 | This document explains how the test data required for executing OF unittest |
b9c74fd7 GM |
9 | is attached to the live tree dynamically, independent of the machine's |
10 | architecture. | |
11 | ||
12 | It 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 | ||
17 | OF Selftest has been designed to test the interface (include/linux/of.h) | |
18 | provided to device driver developers to fetch the device information..etc. | |
19 | from the unflattened device tree data structure. This interface is used by | |
20 | most of the device drivers in various use cases. | |
21 | ||
22 | ||
23 | 2. Test-data | |
24 | ||
7a39086d | 25 | The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains |
b9c74fd7 | 26 | the test data required for executing the unit tests automated in |
7a39086d WL |
27 | drivers/of/unittest.c. Currently, following Device Tree Source Include files |
28 | (.dtsi) are included in testcases.dts: | |
b9c74fd7 | 29 | |
7a39086d WL |
30 | drivers/of/unittest-data/tests-interrupts.dtsi |
31 | drivers/of/unittest-data/tests-platform.dtsi | |
32 | drivers/of/unittest-data/tests-phandle.dtsi | |
33 | drivers/of/unittest-data/tests-match.dtsi | |
b9c74fd7 GM |
34 | |
35 | When 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 | ||
7a39086d WL |
40 | is used to compile the DT source file (testcases.dts) into a binary blob |
41 | (testcases.dtb), also referred as flattened DT. | |
b9c74fd7 GM |
42 | |
43 | After that, using the following rule the binary blob above is wrapped as an | |
7a39086d | 44 | assembly file (testcases.dtb.S). |
b9c74fd7 GM |
45 | |
46 | $(obj)/%.dtb.S: $(obj)/%.dtb | |
47 | $(call cmd, dt_S_dtb) | |
48 | ||
7a39086d | 49 | The assembly file is compiled into an object file (testcases.dtb.o), and is |
b9c74fd7 GM |
50 | linked into the kernel image. |
51 | ||
52 | ||
53 | 2.1. Adding the test data | |
54 | ||
55 | Un-flattened device tree structure: | |
56 | ||
57 | Un-flattened device tree consists of connected device_node(s) in form of a tree | |
58 | structure described below. | |
59 | ||
60 | // following struct members are used to construct the tree | |
61 | struct device_node { | |
62 | ... | |
63 | struct device_node *parent; | |
64 | struct device_node *child; | |
65 | struct device_node *sibling; | |
b9c74fd7 GM |
66 | ... |
67 | }; | |
68 | ||
669a3630 | 69 | Figure 1, describes a generic structure of machine's un-flattened device tree |
b9c74fd7 GM |
70 | considering only child and sibling pointers. There exists another pointer, |
71 | *parent, that is used to traverse the tree in the reverse direction. So, at | |
72 | a particular level the child node and all the sibling nodes will have a parent | |
669a3630 | 73 | pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's |
b9c74fd7 GM |
74 | parent points to root node) |
75 | ||
669a3630 | 76 | root ('/') |
b9c74fd7 GM |
77 | | |
78 | child1 -> 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 | | | |
90 | child11 -> sibling12 -> sibling13 -> sibling14 -> null | |
91 | | | | | | |
92 | | | | null | |
93 | | | | | |
94 | null null child131 -> null | |
95 | | | |
96 | null | |
97 | ||
98 | Figure 1: Generic structure of un-flattened device tree | |
99 | ||
100 | ||
7a39086d | 101 | Before executing OF unittest, it is required to attach the test data to |
b9c74fd7 GM |
102 | machine's device tree (if present). So, when selftest_data_add() is called, |
103 | at first it reads the flattened device tree data linked into the kernel image | |
104 | via 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 | ||
669a3630 GM |
109 | Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened |
110 | blob. And finally, if the machine's device tree (i.e live tree) is present, | |
b9c74fd7 GM |
111 | then it attaches the unflattened test data tree to the live tree, else it |
112 | attaches itself as a live device tree. | |
113 | ||
114 | attach_node_and_children() uses of_attach_node() to attach the nodes into the | |
115 | live 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 | ||
669a3630 | 118 | root ('/') |
b9c74fd7 GM |
119 | | |
120 | testcase-data | |
121 | | | |
122 | test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null | |
123 | | | | | | |
124 | test-child01 null null null | |
125 | ||
126 | ||
b9c74fd7 GM |
127 | Figure 2: Example test data tree to be attached to live tree. |
128 | ||
669a3630 GM |
129 | According to the scenario above, the live tree is already present so it isn't |
130 | required to attach the root('/') node. All other nodes are attached by calling | |
b9c74fd7 GM |
131 | of_attach_node() on each node. |
132 | ||
133 | In the function of_attach_node(), the new node is attached as the child of the | |
134 | given parent in live tree. But, if parent already has a child then the new node | |
135 | replaces the current child and turns it into its sibling. So, when the testcase | |
136 | data node is attached to the live tree above (Figure 1), the final structure is | |
137 | as shown in Figure 3. | |
138 | ||
669a3630 | 139 | root ('/') |
b9c74fd7 GM |
140 | | |
141 | testcase-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 | ||
669a3630 | 161 | root ('/') |
b9c74fd7 GM |
162 | | |
163 | testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null | |
164 | | | | | | | |
165 | | (...) (...) (...) null | |
166 | | | |
167 | test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null | |
168 | | | | | | |
169 | null null null test-child01 | |
170 | ||
171 | ||
172 | Figure 3: Live device tree structure after attaching the testcase-data. | |
173 | ||
174 | ||
175 | Astute readers would have noticed that test-child0 node becomes the last | |
176 | sibling compared to the earlier structure (Figure 2). After attaching first | |
177 | test-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 | ||
181 | If a duplicate node is found (i.e. if a node with same full_name property is | |
669a3630 GM |
182 | already present in the live tree), then the node isn't attached rather its |
183 | properties are updated to the live tree's node by calling the function | |
b9c74fd7 GM |
184 | update_node_properties(). |
185 | ||
186 | ||
187 | 2.2. Removing the test data | |
188 | ||
189 | Once the test case execution is complete, selftest_data_remove is called in | |
190 | order to remove the device nodes attached initially (first the leaf nodes are | |
191 | detached and then moving up the parent nodes are removed, and eventually the | |
192 | whole tree). selftest_data_remove() calls detach_node_and_children() that uses | |
193 | of_detach_node() to detach the nodes from the live device tree. | |
194 | ||
5063e25a GL |
195 | To detach a node, of_detach_node() either updates the child pointer of given |
196 | node's parent to its sibling or attaches the previous sibling to the given | |
197 | node's sibling, as appropriate. That is it :) |