Commit | Line | Data |
---|---|---|
218e1b3d MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ================================== | |
7a39086d | 4 | Open Firmware Device Tree Unittest |
218e1b3d | 5 | ================================== |
b9c74fd7 GM |
6 | |
7 | Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> | |
8 | ||
9 | 1. Introduction | |
218e1b3d | 10 | =============== |
b9c74fd7 | 11 | |
7a39086d | 12 | This document explains how the test data required for executing OF unittest |
b9c74fd7 GM |
13 | is attached to the live tree dynamically, independent of the machine's |
14 | architecture. | |
15 | ||
16 | It is recommended to read the following documents before moving ahead. | |
17 | ||
218e1b3d MCC |
18 | (1) Documentation/devicetree/usage-model.rst |
19 | (2) http://www.devicetree.org/Device_Tree_Usage | |
b9c74fd7 GM |
20 | |
21 | OF Selftest has been designed to test the interface (include/linux/of.h) | |
22 | provided to device driver developers to fetch the device information..etc. | |
23 | from the unflattened device tree data structure. This interface is used by | |
24 | most of the device drivers in various use cases. | |
25 | ||
26 | ||
27 | 2. Test-data | |
218e1b3d | 28 | ============ |
b9c74fd7 | 29 | |
7a39086d | 30 | The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains |
b9c74fd7 | 31 | the test data required for executing the unit tests automated in |
7a39086d | 32 | drivers/of/unittest.c. Currently, following Device Tree Source Include files |
218e1b3d | 33 | (.dtsi) are included in testcases.dts:: |
b9c74fd7 | 34 | |
218e1b3d MCC |
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 | |
b9c74fd7 | 39 | |
218e1b3d MCC |
40 | When the kernel is build with OF_SELFTEST enabled, then the following make |
41 | rule:: | |
b9c74fd7 | 42 | |
218e1b3d MCC |
43 | $(obj)/%.dtb: $(src)/%.dts FORCE |
44 | $(call if_changed_dep, dtc) | |
b9c74fd7 | 45 | |
7a39086d WL |
46 | is used to compile the DT source file (testcases.dts) into a binary blob |
47 | (testcases.dtb), also referred as flattened DT. | |
b9c74fd7 GM |
48 | |
49 | After that, using the following rule the binary blob above is wrapped as an | |
218e1b3d | 50 | assembly file (testcases.dtb.S):: |
b9c74fd7 | 51 | |
218e1b3d MCC |
52 | $(obj)/%.dtb.S: $(obj)/%.dtb |
53 | $(call cmd, dt_S_dtb) | |
b9c74fd7 | 54 | |
7a39086d | 55 | The assembly file is compiled into an object file (testcases.dtb.o), and is |
b9c74fd7 GM |
56 | linked into the kernel image. |
57 | ||
58 | ||
59 | 2.1. Adding the test data | |
218e1b3d | 60 | ------------------------- |
b9c74fd7 GM |
61 | |
62 | Un-flattened device tree structure: | |
63 | ||
64 | Un-flattened device tree consists of connected device_node(s) in form of a tree | |
218e1b3d | 65 | structure described below:: |
b9c74fd7 | 66 | |
218e1b3d MCC |
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 | }; | |
b9c74fd7 | 75 | |
669a3630 | 76 | Figure 1, describes a generic structure of machine's un-flattened device tree |
b9c74fd7 | 77 | considering only child and sibling pointers. There exists another pointer, |
218e1b3d | 78 | ``*parent``, that is used to traverse the tree in the reverse direction. So, at |
b9c74fd7 | 79 | a particular level the child node and all the sibling nodes will have a parent |
669a3630 | 80 | pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's |
218e1b3d MCC |
81 | parent 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 | |
b9c74fd7 GM |
104 | |
105 | Figure 1: Generic structure of un-flattened device tree | |
106 | ||
107 | ||
7a39086d | 108 | Before executing OF unittest, it is required to attach the test data to |
b9c74fd7 GM |
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 | |
218e1b3d | 111 | via the following kernel symbols:: |
b9c74fd7 | 112 | |
218e1b3d MCC |
113 | __dtb_testcases_begin - address marking the start of test data blob |
114 | __dtb_testcases_end - address marking the end of test data blob | |
b9c74fd7 | 115 | |
669a3630 GM |
116 | Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened |
117 | blob. And finally, if the machine's device tree (i.e live tree) is present, | |
b9c74fd7 GM |
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 | |
218e1b3d | 123 | in Figure 2 is attached to the live tree described in Figure 1:: |
b9c74fd7 | 124 | |
218e1b3d MCC |
125 | root ('/') |
126 | | | |
127 | testcase-data | |
128 | | | |
129 | test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null | |
130 | | | | | | |
131 | test-child01 null null null | |
b9c74fd7 GM |
132 | |
133 | ||
b9c74fd7 GM |
134 | Figure 2: Example test data tree to be attached to live tree. |
135 | ||
669a3630 GM |
136 | According to the scenario above, the live tree is already present so it isn't |
137 | required to attach the root('/') node. All other nodes are attached by calling | |
b9c74fd7 GM |
138 | of_attach_node() on each node. |
139 | ||
140 | In the function of_attach_node(), the new node is attached as the child of the | |
141 | given parent in live tree. But, if parent already has a child then the new node | |
142 | replaces the current child and turns it into its sibling. So, when the testcase | |
143 | data node is attached to the live tree above (Figure 1), the final structure is | |
218e1b3d MCC |
144 | as 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 | |
b9c74fd7 GM |
177 | |
178 | ||
179 | Figure 3: Live device tree structure after attaching the testcase-data. | |
180 | ||
181 | ||
182 | Astute readers would have noticed that test-child0 node becomes the last | |
183 | sibling compared to the earlier structure (Figure 2). After attaching first | |
184 | test-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, | |
218e1b3d | 186 | as mentioned above. |
b9c74fd7 GM |
187 | |
188 | If a duplicate node is found (i.e. if a node with same full_name property is | |
669a3630 GM |
189 | already present in the live tree), then the node isn't attached rather its |
190 | properties are updated to the live tree's node by calling the function | |
b9c74fd7 GM |
191 | update_node_properties(). |
192 | ||
193 | ||
194 | 2.2. Removing the test data | |
218e1b3d | 195 | --------------------------- |
b9c74fd7 GM |
196 | |
197 | Once the test case execution is complete, selftest_data_remove is called in | |
198 | order to remove the device nodes attached initially (first the leaf nodes are | |
199 | detached and then moving up the parent nodes are removed, and eventually the | |
200 | whole tree). selftest_data_remove() calls detach_node_and_children() that uses | |
201 | of_detach_node() to detach the nodes from the live device tree. | |
202 | ||
5063e25a GL |
203 | To detach a node, of_detach_node() either updates the child pointer of given |
204 | node's parent to its sibling or attaches the previous sibling to the given | |
205 | node's sibling, as appropriate. That is it :) |