227 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=================================4Open Firmware Devicetree Unittest5=================================6 7Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>8 91. Introduction10===============11 12This document explains how the test data required for executing OF unittest13is attached to the live tree dynamically, independent of the machine's14architecture.15 16It is recommended to read the following documents before moving ahead.17 18(1) Documentation/devicetree/usage-model.rst19(2) http://www.devicetree.org/Device_Tree_Usage20 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 by24most 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 to31the console. Unittest also triggers warning and error messages from other32kernel code as a result of intentionally bad unittest data. This has led33to confusion as to whether the triggered messages are an expected result34of 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 been37added to unittest to report that a warning or error is expected. The38begin is printed before triggering the warning or error, and the end is39printed after triggering the warning or error.40 41The EXPECT messages result in very noisy console messages that are difficult42to read. The script scripts/dtc/of_unittest_expect was created to filter43this verbosity and highlight mismatches between triggered warnings and44errors vs expected warnings and errors. More information is available45from 'scripts/dtc/of_unittest_expect --help'.46 47 483. Test-data49============50 51The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains52the test data required for executing the unit tests automated in53drivers/of/unittest.c. Currently, following Device Tree Source Include files54(.dtsi) are included in testcases.dts::55 56 drivers/of/unittest-data/tests-interrupts.dtsi57 drivers/of/unittest-data/tests-platform.dtsi58 drivers/of/unittest-data/tests-phandle.dtsi59 drivers/of/unittest-data/tests-match.dtsi60 61When the kernel is build with OF_SELFTEST enabled, then the following make62rule::63 64 $(obj)/%.dtb: $(src)/%.dts FORCE65 $(call if_changed_dep, dtc)66 67is used to compile the DT source file (testcases.dts) into a binary blob68(testcases.dtb), also referred as flattened DT.69 70After that, using the following rule the binary blob above is wrapped as an71assembly file (testcases.dtb.S)::72 73 $(obj)/%.dtb.S: $(obj)/%.dtb74 $(call cmd, dt_S_dtb)75 76The assembly file is compiled into an object file (testcases.dtb.o), and is77linked into the kernel image.78 79 803.1. Adding the test data81-------------------------82 83Un-flattened device tree structure:84 85Un-flattened device tree consists of connected device_node(s) in form of a tree86structure described below::87 88 // following struct members are used to construct the tree89 struct device_node {90 ...91 struct device_node *parent;92 struct device_node *child;93 struct device_node *sibling;94 ...95 };96 97Figure 1, describes a generic structure of machine's un-flattened device tree98considering only child and sibling pointers. There exists another pointer,99``*parent``, that is used to traverse the tree in the reverse direction. So, at100a particular level the child node and all the sibling nodes will have a parent101pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's102parent points to root node)::103 104 root ('/')105 |106 child1 -> sibling2 -> sibling3 -> sibling4 -> null107 | | | |108 | | | null109 | | |110 | | child31 -> sibling32 -> null111 | | | |112 | | null null113 | |114 | child21 -> sibling22 -> sibling23 -> null115 | | | |116 | null null null117 |118 child11 -> sibling12 -> sibling13 -> sibling14 -> null119 | | | |120 | | | null121 | | |122 null null child131 -> null123 |124 null125 126Figure 1: Generic structure of un-flattened device tree127 128 129Before executing OF unittest, it is required to attach the test data to130machine's device tree (if present). So, when selftest_data_add() is called,131at first it reads the flattened device tree data linked into the kernel image132via the following kernel symbols::133 134 __dtb_testcases_begin - address marking the start of test data blob135 __dtb_testcases_end - address marking the end of test data blob136 137Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened138blob. And finally, if the machine's device tree (i.e live tree) is present,139then it attaches the unflattened test data tree to the live tree, else it140attaches itself as a live device tree.141 142attach_node_and_children() uses of_attach_node() to attach the nodes into the143live tree as explained below. To explain the same, the test data tree described144in Figure 2 is attached to the live tree described in Figure 1::145 146 root ('/')147 |148 testcase-data149 |150 test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null151 | | | |152 test-child01 null null null153 154 155Figure 2: Example test data tree to be attached to live tree.156 157According to the scenario above, the live tree is already present so it isn't158required to attach the root('/') node. All other nodes are attached by calling159of_attach_node() on each node.160 161In the function of_attach_node(), the new node is attached as the child of the162given parent in live tree. But, if parent already has a child then the new node163replaces the current child and turns it into its sibling. So, when the testcase164data node is attached to the live tree above (Figure 1), the final structure is165as shown in Figure 3::166 167 root ('/')168 |169 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null170 | | | | |171 (...) | | | null172 | | child31 -> sibling32 -> null173 | | | |174 | | null null175 | |176 | child21 -> sibling22 -> sibling23 -> null177 | | | |178 | null null null179 |180 child11 -> sibling12 -> sibling13 -> sibling14 -> null181 | | | |182 null null | null183 |184 child131 -> null185 |186 null187 -----------------------------------------------------------------------188 189 root ('/')190 |191 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null192 | | | | |193 | (...) (...) (...) null194 |195 test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null196 | | | |197 null null null test-child01198 199 200Figure 3: Live device tree structure after attaching the testcase-data.201 202 203Astute readers would have noticed that test-child0 node becomes the last204sibling compared to the earlier structure (Figure 2). After attaching first205test-child0 the test-sibling1 is attached that pushes the child node206(i.e. test-child0) to become a sibling and makes itself a child node,207as mentioned above.208 209If a duplicate node is found (i.e. if a node with same full_name property is210already present in the live tree), then the node isn't attached rather its211properties are updated to the live tree's node by calling the function212update_node_properties().213 214 2153.2. Removing the test data216---------------------------217 218Once the test case execution is complete, selftest_data_remove is called in219order to remove the device nodes attached initially (first the leaf nodes are220detached and then moving up the parent nodes are removed, and eventually the221whole tree). selftest_data_remove() calls detach_node_and_children() that uses222of_detach_node() to detach the nodes from the live device tree.223 224To detach a node, of_detach_node() either updates the child pointer of given225node's parent to its sibling or attaches the previous sibling to the given226node's sibling, as appropriate. That is it :)227