Based on kernel version 4.0. Page generated on 2015-04-14 21:23 EST.
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 ... 67 }; 68 69 Figure 1, describes a generic structure of machine's un-flattened device tree 70 considering only child and sibling pointers. There exists another pointer, 71 *parent, that is used to traverse the tree in the reverse direction. So, at 72 a particular level the child node and all the sibling nodes will have a parent 73 pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's 74 parent points to root node) 75 76 root ('/') 77 | 78 child1 -> sibling2 -> sibling3 -> sibling4 -> null 79 | | | | 80 | | | null 81 | | | 82 | | child31 -> sibling32 -> null 83 | | | | 84 | | null null 85 | | 86 | child21 -> sibling22 -> sibling23 -> null 87 | | | | 88 | null null null 89 | 90 child11 -> sibling12 -> sibling13 -> sibling14 -> null 91 | | | | 92 | | | null 93 | | | 94 null null child131 -> null 95 | 96 null 97 98 Figure 1: Generic structure of un-flattened device tree 99 100 101 Before executing OF selftest, it is required to attach the test data to 102 machine's device tree (if present). So, when selftest_data_add() is called, 103 at first it reads the flattened device tree data linked into the kernel image 104 via the following kernel symbols: 105 106 __dtb_testcases_begin - address marking the start of test data blob 107 __dtb_testcases_end - address marking the end of test data blob 108 109 Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened 110 blob. And finally, if the machine's device tree (i.e live tree) is present, 111 then it attaches the unflattened test data tree to the live tree, else it 112 attaches itself as a live device tree. 113 114 attach_node_and_children() uses of_attach_node() to attach the nodes into the 115 live tree as explained below. To explain the same, the test data tree described 116 in Figure 2 is attached to the live tree described in Figure 1. 117 118 root ('/') 119 | 120 testcase-data 121 | 122 test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null 123 | | | | 124 test-child01 null null null 125 126 127 Figure 2: Example test data tree to be attached to live tree. 128 129 According to the scenario above, the live tree is already present so it isn't 130 required to attach the root('/') node. All other nodes are attached by calling 131 of_attach_node() on each node. 132 133 In the function of_attach_node(), the new node is attached as the child of the 134 given parent in live tree. But, if parent already has a child then the new node 135 replaces the current child and turns it into its sibling. So, when the testcase 136 data node is attached to the live tree above (Figure 1), the final structure is 137 as shown in Figure 3. 138 139 root ('/') 140 | 141 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null 142 | | | | | 143 (...) | | | null 144 | | child31 -> sibling32 -> null 145 | | | | 146 | | null null 147 | | 148 | child21 -> sibling22 -> sibling23 -> null 149 | | | | 150 | null null null 151 | 152 child11 -> sibling12 -> sibling13 -> sibling14 -> null 153 | | | | 154 null null | null 155 | 156 child131 -> null 157 | 158 null 159 ----------------------------------------------------------------------- 160 161 root ('/') 162 | 163 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null 164 | | | | | 165 | (...) (...) (...) null 166 | 167 test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null 168 | | | | 169 null null null test-child01 170 171 172 Figure 3: Live device tree structure after attaching the testcase-data. 173 174 175 Astute readers would have noticed that test-child0 node becomes the last 176 sibling compared to the earlier structure (Figure 2). After attaching first 177 test-child0 the test-sibling1 is attached that pushes the child node 178 (i.e. test-child0) to become a sibling and makes itself a child node, 179 as mentioned above. 180 181 If a duplicate node is found (i.e. if a node with same full_name property is 182 already present in the live tree), then the node isn't attached rather its 183 properties are updated to the live tree's node by calling the function 184 update_node_properties(). 185 186 187 2.2. Removing the test data 188 189 Once the test case execution is complete, selftest_data_remove is called in 190 order to remove the device nodes attached initially (first the leaf nodes are 191 detached and then moving up the parent nodes are removed, and eventually the 192 whole tree). selftest_data_remove() calls detach_node_and_children() that uses 193 of_detach_node() to detach the nodes from the live device tree. 194 195 To detach a node, of_detach_node() either updates the child pointer of given 196 node's parent to its sibling or attaches the previous sibling to the given 197 node's sibling, as appropriate. That is it :)