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     struct  device_node *allnext;   /* next in list of all nodes */
  67     ...
  68  };
  69
  70 Figure 1, describes a generic structure of machine's un-flattened device tree
  71 considering only child and sibling pointers. There exists another pointer,
  72 *parent, that is used to traverse the tree in the reverse direction. So, at
  73 a particular level the child node and all the sibling nodes will have a parent
  74 pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
  75 parent points to root node)
  76
  77 root ('/')
  78    |
  79 child1 -> sibling2 -> sibling3 -> sibling4 -> null
  80    |         |           |           |
  81    |         |           |          null
  82    |         |           |
  83    |         |        child31 -> sibling32 -> null
  84    |         |           |          |
  85    |         |          null       null
  86    |         |
  87    |      child21 -> sibling22 -> sibling23 -> null
  88    |         |          |            |
  89    |        null       null         null
  90    |
  91 child11 -> sibling12 -> sibling13 -> sibling14 -> null
  92    |           |           |            |
  93    |           |           |           null
  94    |           |           |
  95   null        null       child131 -> null
  96                            |
  97                           null
  98
  99 Figure 1: Generic structure of un-flattened device tree
 100
 101
 102 *allnext: it is used to link all the nodes of DT into a list. So, for the
 103  above tree the list would be as follows:
 104
 105 root->child1->child11->sibling12->sibling13->child131->sibling14->sibling2->
 106 child21->sibling22->sibling23->sibling3->child31->sibling32->sibling4->null
 107
 108 Before executing OF selftest, it is required to attach the test data to
 109 machine's device tree (if present). So, when selftest_data_add() is called,
 110 at first it reads the flattened device tree data linked into the kernel image
 111 via 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
 116 Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened
 117 blob. And finally, if the machine's device tree (i.e live tree) is present,
 118 then it attaches the unflattened test data tree to the live tree, else it
 119 attaches itself as a live device tree.
 120
 121 attach_node_and_children() uses of_attach_node() to attach the nodes into the
 122 live tree as explained below. To explain the same, the test data tree described
 123  in 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
 134 allnext list:
 135
 136 root->testcase-data->test-child0->test-child01->test-sibling1->test-sibling2
 137 ->test-sibling3->null
 138
 139 Figure 2: Example test data tree to be attached to live tree.
 140
 141 According to the scenario above, the live tree is already present so it isn't
 142 required to attach the root('/') node. All other nodes are attached by calling
 143 of_attach_node() on each node.
 144
 145 In the function of_attach_node(), the new node is attached as the child of the
 146 given parent in live tree. But, if parent already has a child then the new node
 147 replaces the current child and turns it into its sibling. So, when the testcase
 148 data node is attached to the live tree above (Figure 1), the final structure is
 149  as shown in Figure 3.
 150
 151 root ('/')
 152    |
 153 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
 154    |               |          |           |           |
 155  (...)             |          |           |          null
 156                    |          |         child31 -> sibling32 -> null
 157                    |          |           |           |
 158                    |          |          null        null
 159                    |          |
 160                    |        child21 -> sibling22 -> sibling23 -> null
 161                    |          |           |            |
 162                    |         null        null         null
 163                    |
 164                 child11 -> sibling12 -> sibling13 -> sibling14 -> null
 165                    |          |            |            |
 166                   null       null          |           null
 167                                            |
 168                                         child131 -> null
 169                                            |
 170                                           null
 171 -----------------------------------------------------------------------
 172
 173 root ('/')
 174    |
 175 testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
 176    |               |          |           |           |
 177    |             (...)      (...)       (...)        null
 178    |
 179 test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
 180    |                |                   |                |
 181   null             null                null         test-child01
 182
 183
 184 Figure 3: Live device tree structure after attaching the testcase-data.
 185
 186
 187 Astute readers would have noticed that test-child0 node becomes the last
 188 sibling compared to the earlier structure (Figure 2). After attaching first
 189 test-child0 the test-sibling1 is attached that pushes the child node
 190 (i.e. test-child0) to become a sibling and makes itself a child node,
 191  as mentioned above.
 192
 193 If a duplicate node is found (i.e. if a node with same full_name property is
 194 already present in the live tree), then the node isn't attached rather its
 195 properties are updated to the live tree's node by calling the function
 196 update_node_properties().
 197
 198
 199 2.2. Removing the test data
 200
 201 Once the test case execution is complete, selftest_data_remove is called in
 202 order to remove the device nodes attached initially (first the leaf nodes are
 203 detached and then moving up the parent nodes are removed, and eventually the
 204 whole tree). selftest_data_remove() calls detach_node_and_children() that uses
 205 of_detach_node() to detach the nodes from the live device tree.
 206
 207 To detach a node, of_detach_node() first updates all_next linked list, by
 208 attaching the previous node's allnext to current node's allnext pointer. And
 209 then, it either updates the child pointer of given node's parent to its
 210 sibling or attaches the previous sibling to the given node's sibling, as
 211 appropriate. That is it :)