]>
Commit | Line | Data |
---|---|---|
b9c74fd7 GM |
1 | Open Firmware Device Tree Selftest |
2 | ---------------------------------- | |
3 | ||
4 | Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> | |
5 | ||
6 | 1. Introduction | |
7 | ||
8 | This document explains how the test data required for executing OF selftest | |
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 | ||
25 | The Device Tree Source file (drivers/of/testcase-data/testcases.dts) contains | |
26 | the test data required for executing the unit tests automated in | |
27 | drivers/of/selftests.c. Currently, following Device Tree Source Include files | |
28 | (.dtsi) are included in testcase.dts: | |
29 | ||
30 | drivers/of/testcase-data/tests-interrupts.dtsi | |
31 | drivers/of/testcase-data/tests-platform.dtsi | |
32 | drivers/of/testcase-data/tests-phandle.dtsi | |
33 | drivers/of/testcase-data/tests-match.dtsi | |
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 | ||
40 | is used to compile the DT source file (testcase.dts) into a binary blob | |
41 | (testcase.dtb), also referred as flattened DT. | |
42 | ||
43 | After that, using the following rule the binary blob above is wrapped as an | |
44 | assembly file (testcase.dtb.S). | |
45 | ||
46 | $(obj)/%.dtb.S: $(obj)/%.dtb | |
47 | $(call cmd, dt_S_dtb) | |
48 | ||
49 | The assembly file is compiled into an object file (testcase.dtb.o), and is | |
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; | |
66 | struct device_node *allnext; /* next in list of all nodes */ | |
67 | ... | |
68 | }; | |
69 | ||
70 | Figure 1, describes a generic structure of machine’s un-flattened device tree | |
71 | considering only child and sibling pointers. There exists another pointer, | |
72 | *parent, that is used to traverse the tree in the reverse direction. So, at | |
73 | a particular level the child node and all the sibling nodes will have a parent | |
74 | pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4’s | |
75 | parent points to root node) | |
76 | ||
77 | root (‘/’) | |
78 | | | |
79 | child1 -> sibling2 -> sibling3 -> sibling4 -> null | |
80 | | | | | | |
81 | | | | null | |
82 | | | | | |
83 | | | child31 -> sibling32 -> null | |
84 | | | | | | |
85 | | | null null | |
86 | | | | |
87 | | child21 -> sibling22 -> sibling23 -> null | |
88 | | | | | | |
89 | | null null null | |
90 | | | |
91 | child11 -> sibling12 -> sibling13 -> sibling14 -> null | |
92 | | | | | | |
93 | | | | null | |
94 | | | | | |
95 | null null child131 -> null | |
96 | | | |
97 | null | |
98 | ||
99 | Figure 1: Generic structure of un-flattened device tree | |
100 | ||
101 | ||
102 | *allnext: it is used to link all the nodes of DT into a list. So, for the | |
103 | above tree the list would be as follows: | |
104 | ||
105 | root->child1->child11->sibling12->sibling13->child131->sibling14->sibling2-> | |
106 | child21->sibling22->sibling23->sibling3->child31->sibling32->sibling4->null | |
107 | ||
108 | Before executing OF selftest, it is required to attach the test data to | |
109 | machine's device tree (if present). So, when selftest_data_add() is called, | |
110 | at first it reads the flattened device tree data linked into the kernel image | |
111 | via 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 | ||
116 | Secondly, it calls of_fdt_unflatten_device_tree() to unflatten the flattened | |
117 | blob. And finally, if the machine’s device tree (i.e live tree) is present, | |
118 | then it attaches the unflattened test data tree to the live tree, else it | |
119 | attaches itself as a live device tree. | |
120 | ||
121 | attach_node_and_children() uses of_attach_node() to attach the nodes into the | |
122 | live tree as explained below. To explain the same, the test data tree described | |
123 | in 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 | ||
134 | allnext list: | |
135 | ||
136 | root->testcase-data->test-child0->test-child01->test-sibling1->test-sibling2 | |
137 | ->test-sibling3->null | |
138 | ||
139 | Figure 2: Example test data tree to be attached to live tree. | |
140 | ||
141 | According to the scenario above, the live tree is already present so it isn’t | |
142 | required to attach the root(‘/’) node. All other nodes are attached by calling | |
143 | of_attach_node() on each node. | |
144 | ||
145 | In the function of_attach_node(), the new node is attached as the child of the | |
146 | given parent in live tree. But, if parent already has a child then the new node | |
147 | replaces the current child and turns it into its sibling. So, when the testcase | |
148 | data node is attached to the live tree above (Figure 1), the final structure is | |
149 | as shown in Figure 3. | |
150 | ||
151 | root (‘/’) | |
152 | | | |
153 | testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null | |
154 | | | | | | | |
155 | (...) | | | null | |
156 | | | child31 -> sibling32 -> null | |
157 | | | | | | |
158 | | | null null | |
159 | | | | |
160 | | child21 -> sibling22 -> sibling23 -> null | |
161 | | | | | | |
162 | | null null null | |
163 | | | |
164 | child11 -> sibling12 -> sibling13 -> sibling14 -> null | |
165 | | | | | | |
166 | null null | null | |
167 | | | |
168 | child131 -> null | |
169 | | | |
170 | null | |
171 | ----------------------------------------------------------------------- | |
172 | ||
173 | root (‘/’) | |
174 | | | |
175 | testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null | |
176 | | | | | | | |
177 | | (...) (...) (...) null | |
178 | | | |
179 | test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null | |
180 | | | | | | |
181 | null null null test-child01 | |
182 | ||
183 | ||
184 | Figure 3: Live device tree structure after attaching the testcase-data. | |
185 | ||
186 | ||
187 | Astute readers would have noticed that test-child0 node becomes the last | |
188 | sibling compared to the earlier structure (Figure 2). After attaching first | |
189 | test-child0 the test-sibling1 is attached that pushes the child node | |
190 | (i.e. test-child0) to become a sibling and makes itself a child node, | |
191 | as mentioned above. | |
192 | ||
193 | If a duplicate node is found (i.e. if a node with same full_name property is | |
194 | already present in the live tree), then the node isn’t attached rather its | |
195 | properties are updated to the live tree’s node by calling the function | |
196 | update_node_properties(). | |
197 | ||
198 | ||
199 | 2.2. Removing the test data | |
200 | ||
201 | Once the test case execution is complete, selftest_data_remove is called in | |
202 | order to remove the device nodes attached initially (first the leaf nodes are | |
203 | detached and then moving up the parent nodes are removed, and eventually the | |
204 | whole tree). selftest_data_remove() calls detach_node_and_children() that uses | |
205 | of_detach_node() to detach the nodes from the live device tree. | |
206 | ||
207 | To detach a node, of_detach_node() first updates all_next linked list, by | |
208 | attaching the previous node’s allnext to current node’s allnext pointer. And | |
209 | then, it either updates the child pointer of given node’s parent to its | |
210 | sibling or attaches the previous sibling to the given node’s sibling, as | |
211 | appropriate. That is it :) |