Documentation/devicetree/of_selftest.txt

   1 Open Firmware Device Tree Selftest
   2 ----------------------------------
   3
   4 Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>
   5
   6 1. Introduction
   7
   8 This document explains how the test data required for executing OF selftest
   9 is attached to the live tree dynamically, independent of the machine's
  10 architecture.
  11
  12 It is recommended to read the following documents before moving ahead.
  13
  14 [1] Documentation/devicetree/usage-model.txt
  15 [2] http://www.devicetree.org/Device_Tree_Usage
  16
  17 OF Selftest has been designed to test the interface (include/linux/of.h)
  18 provided to device driver developers to fetch the device information..etc.
  19 from the unflattened device tree data structure. This interface is used by
  20 most of the device drivers in various use cases.
  21
  22
  23 2. Test-data
  24
  25 The Device Tree Source file (drivers/of/testcase-data/testcases.dts) contains
  26 the test data required for executing the unit tests automated in
  27 drivers/of/selftests.c. Currently, following Device Tree Source Include files
  28 (.dtsi) are included in testcase.dts:
  29
  30 drivers/of/testcase-data/tests-interrupts.dtsi
  31 drivers/of/testcase-data/tests-platform.dtsi
  32 drivers/of/testcase-data/tests-phandle.dtsi
  33 drivers/of/testcase-data/tests-match.dtsi
  34
  35 When the kernel is build with OF_SELFTEST enabled, then the following make rule
  36
  37 $(obj)/%.dtb: $(src)/%.dts FORCE
  38         $(call if_changed_dep, dtc)
  39
  40 is used to compile the DT source file (testcase.dts) into a binary blob
  41 (testcase.dtb), also referred as flattened DT.
  42
  43 After that, using the following rule the binary blob above is wrapped as an
  44 assembly file (testcase.dtb.S).
  45
  46 $(obj)/%.dtb.S: $(obj)/%.dtb
  47         $(call cmd, dt_S_dtb)
  48
  49 The assembly file is compiled into an object file (testcase.dtb.o), and is
  50 linked into the kernel image.
  51
  52
  53 2.1. Adding the test data
  54
  55 Un-flattened device tree structure:
  56
  57 Un-flattened device tree consists of connected device_node(s) in form of a tree
  58 structure described below.
  59
  60 // following struct members are used to construct the tree
  61 struct device_node {
  62     ...
  63     struct  device_node *parent;
  64     struct  device_node *child;
  65     struct  device_node *sibling;
  66     ...
  67  };
  68
  69 Figure 1, describes a generic structure of machine's un-flattened device tree
  70 considering only child and sibling pointers. There exists another pointer,
  71 *parent, that is used to traverse the tree in the reverse direction. So, at
  72 a particular level the child node and all the sibling nodes will have a parent
  73 pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
  74 parent points to root node)
  75
  76 root ('/')
  77    |
  78 child1 -> sibling2 -> sibling3 -> sibling4 -> null
  79    |         |           |           |
  80    |         |           |          null
  81    |         |           |
  82    |         |        child31 -> sibling32 -> null
  83    |         |           |          |
  84    |         |          null       null
  85    |         |
  86    |      child21 -> sibling22 -> sibling23 -> null
  87    |         |          |            |
  88    |        null       null         null
  89    |
  90 child11 -> sibling12 -> sibling13 -> sibling14 -> null
  91    |           |           |            |
  92    |           |           |           null
  93    |           |           |
  94   null        null       child131 -> null
  95                            |
  96                           null
  97
  98 Figure 1: Generic structure of un-flattened device tree
  99
 100
 101 Before executing OF selftest, it is required to attach the test data to
 102 machine's device tree (if present). So, when selftest_data_add() is called,
 103 at first it reads the flattened device tree data linked into the kernel image
 104 via the following kernel symbols:
 105
 106 __dtb_testcases_begin - address marking the start of test data blob
 107 __dtb_testcases_end   - address marking the end of test data blob
 108
 109 Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened
 110 blob. And finally, if the machine's device tree (i.e live tree) is present,
 111 then it attaches the unflattened test data tree to the live tree, else it
 112 attaches itself as a live device tree.
 113
 114 attach_node_and_children() uses of_attach_node() to attach the nodes into the
 115 live tree as explained below. To explain the same, the test data tree described
 116  in Figure 2 is attached to the live tree described in Figure 1.
 117
 118 root ('/')
 119     |
 120  testcase-data
 121     |
 122  test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
 123     |               |                |                |
 124  test-child01      null             null             null
 125
 126
 127 Figure 2: Example test data tree to be attached to live tree.
 128
 129 According to the scenario above, the live tree is already present so it isn't
 130 required to attach the root('/') node. All other nodes are attached by calling
 131 of_attach_node() on each node.
 132
 133 In the function of_attach_node(), the new node is attached as the child of the
 134 given parent in live tree. But, if parent already has a child then the new node
 135 replaces the current child and turns it into its sibling. So, when the testcase
 136 data node is attached to the live tree above (Figure 1), the final structure is
 137  as shown in Figure 3.
 138
 139 root ('/')
 140    |
 141 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
 142    |               |          |           |           |
 143  (...)             |          |           |          null
 144                    |          |         child31 -> sibling32 -> null
 145                    |          |           |           |
 146                    |          |          null        null
 147                    |          |
 148                    |        child21 -> sibling22 -> sibling23 -> null
 149                    |          |           |            |
 150                    |         null        null         null
 151                    |
 152                 child11 -> sibling12 -> sibling13 -> sibling14 -> null
 153                    |          |            |            |
 154                   null       null          |           null
 155                                            |
 156                                         child131 -> null
 157                                            |
 158                                           null
 159 -----------------------------------------------------------------------
 160
 161 root ('/')
 162    |
 163 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
 164    |               |          |           |           |
 165    |             (...)      (...)       (...)        null
 166    |
 167 test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
 168    |                |                   |                |
 169   null             null                null         test-child01
 170
 171
 172 Figure 3: Live device tree structure after attaching the testcase-data.
 173
 174
 175 Astute readers would have noticed that test-child0 node becomes the last
 176 sibling compared to the earlier structure (Figure 2). After attaching first
 177 test-child0 the test-sibling1 is attached that pushes the child node
 178 (i.e. test-child0) to become a sibling and makes itself a child node,
 179  as mentioned above.
 180
 181 If a duplicate node is found (i.e. if a node with same full_name property is
 182 already present in the live tree), then the node isn't attached rather its
 183 properties are updated to the live tree's node by calling the function
 184 update_node_properties().
 185
 186
 187 2.2. Removing the test data
 188
 189 Once the test case execution is complete, selftest_data_remove is called in
 190 order to remove the device nodes attached initially (first the leaf nodes are
 191 detached and then moving up the parent nodes are removed, and eventually the
 192 whole tree). selftest_data_remove() calls detach_node_and_children() that uses
 193 of_detach_node() to detach the nodes from the live device tree.
 194
 195 To detach a node, of_detach_node() either updates the child pointer of given
 196 node's parent to its sibling or attaches the previous sibling to the given
 197 node's sibling, as appropriate. That is it :)