linux/Documentation/devicetree/of_unittest.rst
<<
>>
Prefs
   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