1.. SPDX-License-Identifier: GPL-2.0 2 3================================= 4Open Firmware Devicetree Unittest 5================================= 6 7Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> 8 91. Introduction 10=============== 11 12This document explains how the test data required for executing OF unittest 13is attached to the live tree dynamically, independent of the machine's 14architecture. 15 16It is recommended to read the following documents before moving ahead. 17 18(1) Documentation/devicetree/usage-model.rst 19(2) http://www.devicetree.org/Device_Tree_Usage 20 21OF Selftest has been designed to test the interface (include/linux/of.h) 22provided to device driver developers to fetch the device information..etc. 23from the unflattened device tree data structure. This interface is used by 24most of the device drivers in various use cases. 25 26 272. Test-data 28============ 29 30The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains 31the test data required for executing the unit tests automated in 32drivers/of/unittest.c. Currently, following Device Tree Source Include files 33(.dtsi) are included in testcases.dts:: 34 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 39 40When the kernel is build with OF_SELFTEST enabled, then the following make 41rule:: 42 43 $(obj)/%.dtb: $(src)/%.dts FORCE 44 $(call if_changed_dep, dtc) 45 46is used to compile the DT source file (testcases.dts) into a binary blob 47(testcases.dtb), also referred as flattened DT. 48 49After that, using the following rule the binary blob above is wrapped as an 50assembly file (testcases.dtb.S):: 51 52 $(obj)/%.dtb.S: $(obj)/%.dtb 53 $(call cmd, dt_S_dtb) 54 55The assembly file is compiled into an object file (testcases.dtb.o), and is 56linked into the kernel image. 57 58 592.1. Adding the test data 60------------------------- 61 62Un-flattened device tree structure: 63 64Un-flattened device tree consists of connected device_node(s) in form of a tree 65structure described below:: 66 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 }; 75 76Figure 1, describes a generic structure of machine's un-flattened device tree 77considering only child and sibling pointers. There exists another pointer, 78``*parent``, that is used to traverse the tree in the reverse direction. So, at 79a particular level the child node and all the sibling nodes will have a parent 80pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's 81parent points to root node):: 82 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 104 105Figure 1: Generic structure of un-flattened device tree 106 107 108Before executing OF unittest, 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 123in Figure 2 is attached to the live tree described in Figure 1:: 124 125 root ('/') 126 | 127 testcase-data 128 | 129 test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null 130 | | | | 131 test-child01 null null null 132 133 134Figure 2: Example test data tree to be attached to live tree. 135 136According to the scenario above, the live tree is already present so it isn't 137required to attach the root('/') node. All other nodes are attached by calling 138of_attach_node() on each node. 139 140In the function of_attach_node(), the new node is attached as the child of the 141given parent in live tree. But, if parent already has a child then the new node 142replaces the current child and turns it into its sibling. So, when the testcase 143data node is attached to the live tree above (Figure 1), the final structure is 144as shown in Figure 3:: 145 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 ----------------------------------------------------------------------- 167 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 177 178 179Figure 3: Live device tree structure after attaching the testcase-data. 180 181 182Astute readers would have noticed that test-child0 node becomes the last 183sibling compared to the earlier structure (Figure 2). After attaching first 184test-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, 186as mentioned above. 187 188If a duplicate node is found (i.e. if a node with same full_name property is 189already present in the live tree), then the node isn't attached rather its 190properties are updated to the live tree's node by calling the function 191update_node_properties(). 192 193 1942.2. Removing the test data 195--------------------------- 196 197Once the test case execution is complete, selftest_data_remove is called in 198order to remove the device nodes attached initially (first the leaf nodes are 199detached and then moving up the parent nodes are removed, and eventually the 200whole tree). selftest_data_remove() calls detach_node_and_children() that uses 201of_detach_node() to detach the nodes from the live device tree. 202 203To detach a node, of_detach_node() either updates the child pointer of given 204node's parent to its sibling or attaches the previous sibling to the given 205node's sibling, as appropriate. That is it :) 206