Documentation/devicetree/of_unittest.rst

1 .. SPDX-License-Identifier: GPL-2.0
12 This document explains how the test data required for executing OF unittest
13 is attached to the live tree dynamically, independent of the machine's
18 (1) Documentation/devicetree/usage-model.rst
23 from the unflattened device tree data structure. This interface is used by
32 kernel code as a result of intentionally bad unittest data.  This has led
34 of a test or whether there is a real problem that is independent of unittest.
45 from 'scripts/dtc/of_unittest_expect --help'.
48 3. Test-data
51 The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
52 the test data required for executing the unit tests automated in
56     drivers/of/unittest-data/tests-interrupts.dtsi
57     drivers/of/unittest-data/tests-platform.dtsi
58     drivers/of/unittest-data/tests-phandle.dtsi
59     drivers/of/unittest-data/tests-match.dtsi
80 3.1. Adding the test data
81 -------------------------
83 Un-flattened device tree structure:
85 Un-flattened device tree consists of connected device_node(s) in form of a tree
97 Figure 1, describes a generic structure of machine's un-flattened device tree
106     child1 -> sibling2 -> sibling3 -> sibling4 -> null
110     |         |        child31 -> sibling32 -> null
114     |      child21 -> sibling22 -> sibling23 -> null
118     child11 -> sibling12 -> sibling13 -> sibling14 -> null
122     null        null       child131 -> null
126 Figure 1: Generic structure of un-flattened device tree
129 Before executing OF unittest, it is required to attach the test data to
131 at first it reads the flattened device tree data linked into the kernel image
134     __dtb_testcases_begin - address marking the start of test data blob
135     __dtb_testcases_end   - address marking the end of test data blob
139 then it attaches the unflattened test data tree to the live tree, else it
143 live tree as explained below. To explain the same, the test data tree described
148     testcase-data
150     test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
152     test-child01      null             null             null
155 Figure 2: Example test data tree to be attached to live tree.
164 data node is attached to the live tree above (Figure 1), the final structure is
169     testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
172 		    |          |         child31 -> sibling32 -> null
176 		    |        child21 -> sibling22 -> sibling23 -> null
180 		    child11 -> sibling12 -> sibling13 -> sibling14 -> null
184 					    child131 -> null
187     -----------------------------------------------------------------------
191     testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
195     test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
197     null             null                null         test-child01
200 Figure 3: Live device tree structure after attaching the testcase-data.
203 Astute readers would have noticed that test-child0 node becomes the last
205 test-child0 the test-sibling1 is attached that pushes the child node
206 (i.e. test-child0) to become a sibling and makes itself a child node,
215 3.2. Removing the test data
216 ---------------------------