Documentation/devicetree/of_unittest.rst

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