1.. SPDX-License-Identifier: GPL-2.0 2 3================================= 4Open Firmware Devicetree Unittest 5================================= 6 7Author: Gaurav Minocha <[email protected]> 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. Verbose Output (EXPECT) 28========================== 29 30If unittest detects a problem it will print a warning or error message to 31the console. Unittest also triggers warning and error messages from other 32kernel code as a result of intentionally bad unittest data. This has led 33to confusion as to whether the triggered messages are an expected result 34of a test or whether there is a real problem that is independent of unittest. 35 36'EXPECT \ : text' (begin) and 'EXPECT / : text' (end) messages have been 37added to unittest to report that a warning or error is expected. The 38begin is printed before triggering the warning or error, and the end is 39printed after triggering the warning or error. 40 41The EXPECT messages result in very noisy console messages that are difficult 42to read. The script scripts/dtc/of_unittest_expect was created to filter 43this verbosity and highlight mismatches between triggered warnings and 44errors vs expected warnings and errors. More information is available 45from 'scripts/dtc/of_unittest_expect --help'. 46 47 483. Test-data 49============ 50 51The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains 52the test data required for executing the unit tests automated in 53drivers/of/unittest.c. See the content of the folder:: 54 55 drivers/of/unittest-data/tests-*.dtsi 56 57for the Device Tree Source Include files (.dtsi) included in testcases.dts. 58 59When the kernel is build with CONFIG_OF_UNITTEST enabled, then the following make 60rule:: 61 62 $(obj)/%.dtb: $(src)/%.dts FORCE 63 $(call if_changed_dep, dtc) 64 65is used to compile the DT source file (testcases.dts) into a binary blob 66(testcases.dtb), also referred as flattened DT. 67 68After that, using the following rule the binary blob above is wrapped as an 69assembly file (testcases.dtb.S):: 70 71 $(obj)/%.dtb.S: $(obj)/%.dtb 72 $(call cmd, dt_S_dtb) 73 74The assembly file is compiled into an object file (testcases.dtb.o), and is 75linked into the kernel image. 76 77 783.1. Adding the test data 79------------------------- 80 81Un-flattened device tree structure: 82 83Un-flattened device tree consists of connected device_node(s) in form of a tree 84structure described below:: 85 86 // following struct members are used to construct the tree 87 struct device_node { 88 ... 89 struct device_node *parent; 90 struct device_node *child; 91 struct device_node *sibling; 92 ... 93 }; 94 95Figure 1, describes a generic structure of machine's un-flattened device tree 96considering only child and sibling pointers. There exists another pointer, 97``*parent``, that is used to traverse the tree in the reverse direction. So, at 98a particular level the child node and all the sibling nodes will have a parent 99pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's 100parent points to root node):: 101 102 root ('/') 103 | 104 child1 -> sibling2 -> sibling3 -> sibling4 -> null 105 | | | | 106 | | | null 107 | | | 108 | | child31 -> sibling32 -> null 109 | | | | 110 | | null null 111 | | 112 | child21 -> sibling22 -> sibling23 -> null 113 | | | | 114 | null null null 115 | 116 child11 -> sibling12 -> sibling13 -> sibling14 -> null 117 | | | | 118 | | | null 119 | | | 120 null null child131 -> null 121 | 122 null 123 124Figure 1: Generic structure of un-flattened device tree 125 126 127Before executing OF unittest, it is required to attach the test data to 128machine's device tree (if present). So, when selftest_data_add() is called, 129at first it reads the flattened device tree data linked into the kernel image 130via the following kernel symbols:: 131 132 __dtb_testcases_begin - address marking the start of test data blob 133 __dtb_testcases_end - address marking the end of test data blob 134 135Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened 136blob. And finally, if the machine's device tree (i.e live tree) is present, 137then it attaches the unflattened test data tree to the live tree, else it 138attaches itself as a live device tree. 139 140attach_node_and_children() uses of_attach_node() to attach the nodes into the 141live tree as explained below. To explain the same, the test data tree described 142in Figure 2 is attached to the live tree described in Figure 1:: 143 144 root ('/') 145 | 146 testcase-data 147 | 148 test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null 149 | | | | 150 test-child01 null null null 151 152 153Figure 2: Example test data tree to be attached to live tree. 154 155According to the scenario above, the live tree is already present so it isn't 156required to attach the root('/') node. All other nodes are attached by calling 157of_attach_node() on each node. 158 159In the function of_attach_node(), the new node is attached as the child of the 160given parent in live tree. But, if parent already has a child then the new node 161replaces the current child and turns it into its sibling. So, when the testcase 162data node is attached to the live tree above (Figure 1), the final structure is 163as shown in Figure 3:: 164 165 root ('/') 166 | 167 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null 168 | | | | | 169 (...) | | | null 170 | | child31 -> sibling32 -> null 171 | | | | 172 | | null null 173 | | 174 | child21 -> sibling22 -> sibling23 -> null 175 | | | | 176 | null null null 177 | 178 child11 -> sibling12 -> sibling13 -> sibling14 -> null 179 | | | | 180 null null | null 181 | 182 child131 -> null 183 | 184 null 185 ----------------------------------------------------------------------- 186 187 root ('/') 188 | 189 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null 190 | | | | | 191 | (...) (...) (...) null 192 | 193 test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null 194 | | | | 195 null null null test-child01 196 197 198Figure 3: Live device tree structure after attaching the testcase-data. 199 200 201Astute readers would have noticed that test-child0 node becomes the last 202sibling compared to the earlier structure (Figure 2). After attaching first 203test-child0 the test-sibling1 is attached that pushes the child node 204(i.e. test-child0) to become a sibling and makes itself a child node, 205as mentioned above. 206 207If a duplicate node is found (i.e. if a node with same full_name property is 208already present in the live tree), then the node isn't attached rather its 209properties are updated to the live tree's node by calling the function 210update_node_properties(). 211 212 2133.2. Removing the test data 214--------------------------- 215 216Once the test case execution is complete, selftest_data_remove is called in 217order to remove the device nodes attached initially (first the leaf nodes are 218detached and then moving up the parent nodes are removed, and eventually the 219whole tree). selftest_data_remove() calls detach_node_and_children() that uses 220of_detach_node() to detach the nodes from the live device tree. 221 222To detach a node, of_detach_node() either updates the child pointer of given 223node's parent to its sibling or attaches the previous sibling to the given 224node's sibling, as appropriate. That is it :) 225