Blame view
Documentation/devicetree/of_unittest.txt
7.54 KB
7a39086d2 Documentation: up... |
1 |
Open Firmware Device Tree Unittest |
b9c74fd7d of: Documentation... |
2 3 4 5 6 |
---------------------------------- Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> 1. Introduction |
7a39086d2 Documentation: up... |
7 |
This document explains how the test data required for executing OF unittest |
b9c74fd7d of: Documentation... |
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
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 |
7a39086d2 Documentation: up... |
23 |
The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains |
b9c74fd7d of: Documentation... |
24 |
the test data required for executing the unit tests automated in |
7a39086d2 Documentation: up... |
25 26 |
drivers/of/unittest.c. Currently, following Device Tree Source Include files (.dtsi) are included in testcases.dts: |
b9c74fd7d of: Documentation... |
27 |
|
7a39086d2 Documentation: up... |
28 29 30 31 |
drivers/of/unittest-data/tests-interrupts.dtsi drivers/of/unittest-data/tests-platform.dtsi drivers/of/unittest-data/tests-phandle.dtsi drivers/of/unittest-data/tests-match.dtsi |
b9c74fd7d of: Documentation... |
32 33 34 35 36 |
When the kernel is build with OF_SELFTEST enabled, then the following make rule $(obj)/%.dtb: $(src)/%.dts FORCE $(call if_changed_dep, dtc) |
7a39086d2 Documentation: up... |
37 38 |
is used to compile the DT source file (testcases.dts) into a binary blob (testcases.dtb), also referred as flattened DT. |
b9c74fd7d of: Documentation... |
39 40 |
After that, using the following rule the binary blob above is wrapped as an |
7a39086d2 Documentation: up... |
41 |
assembly file (testcases.dtb.S). |
b9c74fd7d of: Documentation... |
42 43 44 |
$(obj)/%.dtb.S: $(obj)/%.dtb $(call cmd, dt_S_dtb) |
7a39086d2 Documentation: up... |
45 |
The assembly file is compiled into an object file (testcases.dtb.o), and is |
b9c74fd7d of: Documentation... |
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
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; |
b9c74fd7d of: Documentation... |
62 63 |
... }; |
669a36302 To remove non-asc... |
64 |
Figure 1, describes a generic structure of machine's un-flattened device tree |
b9c74fd7d of: Documentation... |
65 66 67 |
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 |
669a36302 To remove non-asc... |
68 |
pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's |
b9c74fd7d of: Documentation... |
69 |
parent points to root node) |
669a36302 To remove non-asc... |
70 |
root ('/') |
b9c74fd7d of: Documentation... |
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 |
| 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 |
7a39086d2 Documentation: up... |
93 |
Before executing OF unittest, it is required to attach the test data to |
b9c74fd7d of: Documentation... |
94 95 96 97 98 99 |
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 |
669a36302 To remove non-asc... |
100 101 |
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, |
b9c74fd7d of: Documentation... |
102 103 104 105 106 107 |
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. |
669a36302 To remove non-asc... |
108 |
root ('/') |
b9c74fd7d of: Documentation... |
109 110 111 112 113 114 |
| testcase-data | test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null | | | | test-child01 null null null |
b9c74fd7d of: Documentation... |
115 |
Figure 2: Example test data tree to be attached to live tree. |
669a36302 To remove non-asc... |
116 117 |
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 |
b9c74fd7d of: Documentation... |
118 119 120 121 122 123 124 |
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. |
669a36302 To remove non-asc... |
125 |
root ('/') |
b9c74fd7d of: Documentation... |
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 |
| 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 ----------------------------------------------------------------------- |
669a36302 To remove non-asc... |
146 |
root ('/') |
b9c74fd7d of: Documentation... |
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 |
| 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 |
669a36302 To remove non-asc... |
167 168 |
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 |
b9c74fd7d of: Documentation... |
169 170 171 172 173 174 175 176 177 178 |
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. |
5063e25a3 of: Eliminate of_... |
179 180 181 |
To detach a node, of_detach_node() 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 :) |