WIP FPC-III support
[linux/fpc-iii.git] / Documentation / devicetree / of_unittest.rst
blobdea05214f3ad2e31eaf8a5128f951eb569709dc1
1 .. SPDX-License-Identifier: GPL-2.0
3 ==================================
4 Open Firmware Device Tree Unittest
5 ==================================
7 Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>
9 1. Introduction
10 ===============
12 This document explains how the test data required for executing OF unittest
13 is attached to the live tree dynamically, independent of the machine's
14 architecture.
16 It is recommended to read the following documents before moving ahead.
18 (1) Documentation/devicetree/usage-model.rst
19 (2) http://www.devicetree.org/Device_Tree_Usage
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.
27 2. Test-data
28 ============
30 The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
31 the test data required for executing the unit tests automated in
32 drivers/of/unittest.c. Currently, following Device Tree Source Include files
33 (.dtsi) are included in testcases.dts::
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
40 When the kernel is build with OF_SELFTEST enabled, then the following make
41 rule::
43     $(obj)/%.dtb: $(src)/%.dts FORCE
44             $(call if_changed_dep, dtc)
46 is used to compile the DT source file (testcases.dts) into a binary blob
47 (testcases.dtb), also referred as flattened DT.
49 After that, using the following rule the binary blob above is wrapped as an
50 assembly file (testcases.dtb.S)::
52     $(obj)/%.dtb.S: $(obj)/%.dtb
53             $(call cmd, dt_S_dtb)
55 The assembly file is compiled into an object file (testcases.dtb.o), and is
56 linked into the kernel image.
59 2.1. Adding the test data
60 -------------------------
62 Un-flattened device tree structure:
64 Un-flattened device tree consists of connected device_node(s) in form of a tree
65 structure described below::
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     };
76 Figure 1, describes a generic structure of machine's un-flattened device tree
77 considering only child and sibling pointers. There exists another pointer,
78 ``*parent``, that is used to traverse the tree in the reverse direction. So, at
79 a particular level the child node and all the sibling nodes will have a parent
80 pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
81 parent points to root node)::
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
105 Figure 1: Generic structure of un-flattened device tree
108 Before executing OF unittest, 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::
113     __dtb_testcases_begin - address marking the start of test data blob
114     __dtb_testcases_end   - address marking the end of test data blob
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,
118 then it attaches the unflattened test data tree to the live tree, else it
119 attaches itself as a live device tree.
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::
125     root ('/')
126         |
127     testcase-data
128         |
129     test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
130         |               |                |                |
131     test-child01      null             null             null
134 Figure 2: Example test data tree to be attached to live tree.
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
138 of_attach_node() on each node.
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
144 as shown in Figure 3::
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     -----------------------------------------------------------------------
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
179 Figure 3: Live device tree structure after attaching the testcase-data.
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,
186 as mentioned above.
188 If a duplicate node is found (i.e. if a node with same full_name property is
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
191 update_node_properties().
194 2.2. Removing the test data
195 ---------------------------
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.
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 :)