3.1. Adding the test data¶

Un-flattened device tree structure:

Un-flattened device tree consists of connected device_node(s) in form of a treestructure described below:

// following struct members are used to construct the treestruct device_node {    ...    struct  device_node *parent;    struct  device_node *child;    struct  device_node *sibling;    ...};

Figure 1, describes a generic structure of machine’s un-flattened device treeconsidering only child and sibling pointers. There exists another pointer,*parent, that is used to traverse the tree in the reverse direction. So, ata particular level the child node and all the sibling nodes will have a parentpointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4’sparent points to root node):

root ('/')|child1 -> sibling2 -> sibling3 -> sibling4 -> null|         |           |           ||         |           |          null|         |           ||         |        child31 -> sibling32 -> null|         |           |          ||         |          null       null|         ||      child21 -> sibling22 -> sibling23 -> null|         |          |            ||        null       null         null|child11 -> sibling12 -> sibling13 -> sibling14 -> null|           |           |            ||           |           |           null|           |           |null        null       child131 -> null                        |                        null

Figure 1: Generic structure of un-flattened device tree

Before executing OF unittest, it is required to attach the test data tomachine’s device tree (if present). So, whenselftest_data_add() is called,at first it reads the flattened device tree data linked into the kernel imagevia the following kernel symbols:

__dtb_testcases_begin - address marking the start of test data blob__dtb_testcases_end   - address marking the end of test data blob

Secondly, it callsof_fdt_unflatten_tree() to unflatten the flattenedblob. And finally, if the machine’s device tree (i.e. live tree) is present,then it attaches the unflattened test data tree to the live tree, else itattaches itself as a live device tree.

attach_node_and_children() usesof_attach_node() to attach the nodes into thelive tree as explained below. To explain the same, the test data tree describedin Figure 2 is attached to the live tree described in Figure 1:

root ('/')    |testcase-data    |test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null    |               |                |                |test-child01      null             null             null

Figure 2: Example test data tree to be attached to live tree.

According to the scenario above, the live tree is already present so it isn’trequired to attach the root(‘/’) node. All other nodes are attached by callingof_attach_node() on each node.

In the functionof_attach_node(), the new node is attached as the child of thegiven parent in live tree. But, if parent already has a child then the new nodereplaces the current child and turns it into its sibling. So, when the testcasedata node is attached to the live tree above (Figure 1), the final structure isas shown in Figure 3:

root ('/')|testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null|               |          |           |           |(...)             |          |           |          null                |          |         child31 -> sibling32 -> null                |          |           |           |                |          |          null        null                |          |                |        child21 -> sibling22 -> sibling23 -> null                |          |           |            |                |         null        null         null                |                child11 -> sibling12 -> sibling13 -> sibling14 -> null                |          |            |            |                null       null          |           null                                        |                                        child131 -> null                                        |                                        null-----------------------------------------------------------------------root ('/')|testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null|               |          |           |           ||             (...)      (...)       (...)        null|test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null|                |                   |                |null             null                null         test-child01

Figure 3: Live device tree structure after attaching the testcase-data.

Astute readers would have noticed that test-child0 node becomes the lastsibling compared to the earlier structure (Figure 2). After attaching firsttest-child0 the test-sibling1 is attached that pushes the child node(i.e. test-child0) to become a sibling and makes itself a child node,as mentioned above.

If a duplicate node is found (i.e. if a node with same full_name property isalready present in the live tree), then the node isn’t attached rather itsproperties are updated to the live tree’s node by calling the functionupdate_node_properties().

3.2. Removing the test data¶

Once the test case execution is complete, selftest_data_remove is called inorder to remove the device nodes attached initially (first the leaf nodes aredetached and then moving up the parent nodes are removed, and eventually thewhole tree).selftest_data_remove() callsdetach_node_and_children() that usesof_detach_node() to detach the nodes from the live device tree.

To detach a node,of_detach_node() either updates the child pointer of givennode’s parent to its sibling or attaches the previous sibling to the givennode’s sibling, as appropriate. That is it :)