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