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