mirror of
https://github.com/torvalds/linux.git
synced 2024-12-07 19:41:31 +00:00
b9c74fd7d2
This patch add a document that explains how the selftest test data is dynamically attached into the live device tree irrespective of the machine's architecture. Signed-off-by: Gaurav Minocha <gaurav.minocha.os@gmail.com> Signed-off-by: Grant Likely <grant.likely@linaro.org>
212 lines
8.1 KiB
Plaintext
212 lines
8.1 KiB
Plaintext
Open Firmware Device Tree Selftest
|
||
----------------------------------
|
||
|
||
Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>
|
||
|
||
1. Introduction
|
||
|
||
This document explains how the test data required for executing OF selftest
|
||
is attached to the live tree dynamically, independent of the machine's
|
||
architecture.
|
||
|
||
It is recommended to read the following documents before moving ahead.
|
||
|
||
[1] Documentation/devicetree/usage-model.txt
|
||
[2] http://www.devicetree.org/Device_Tree_Usage
|
||
|
||
OF Selftest has been designed to test the interface (include/linux/of.h)
|
||
provided to device driver developers to fetch the device information..etc.
|
||
from the unflattened device tree data structure. This interface is used by
|
||
most of the device drivers in various use cases.
|
||
|
||
|
||
2. Test-data
|
||
|
||
The Device Tree Source file (drivers/of/testcase-data/testcases.dts) contains
|
||
the test data required for executing the unit tests automated in
|
||
drivers/of/selftests.c. Currently, following Device Tree Source Include files
|
||
(.dtsi) are included in testcase.dts:
|
||
|
||
drivers/of/testcase-data/tests-interrupts.dtsi
|
||
drivers/of/testcase-data/tests-platform.dtsi
|
||
drivers/of/testcase-data/tests-phandle.dtsi
|
||
drivers/of/testcase-data/tests-match.dtsi
|
||
|
||
When the kernel is build with OF_SELFTEST enabled, then the following make rule
|
||
|
||
$(obj)/%.dtb: $(src)/%.dts FORCE
|
||
$(call if_changed_dep, dtc)
|
||
|
||
is used to compile the DT source file (testcase.dts) into a binary blob
|
||
(testcase.dtb), also referred as flattened DT.
|
||
|
||
After that, using the following rule the binary blob above is wrapped as an
|
||
assembly file (testcase.dtb.S).
|
||
|
||
$(obj)/%.dtb.S: $(obj)/%.dtb
|
||
$(call cmd, dt_S_dtb)
|
||
|
||
The assembly file is compiled into an object file (testcase.dtb.o), and is
|
||
linked into the kernel image.
|
||
|
||
|
||
2.1. Adding the test data
|
||
|
||
Un-flattened device tree structure:
|
||
|
||
Un-flattened device tree consists of connected device_node(s) in form of a tree
|
||
structure described below.
|
||
|
||
// following struct members are used to construct the tree
|
||
struct device_node {
|
||
...
|
||
struct device_node *parent;
|
||
struct device_node *child;
|
||
struct device_node *sibling;
|
||
struct device_node *allnext; /* next in list of all nodes */
|
||
...
|
||
};
|
||
|
||
Figure 1, describes a generic structure of machine’s un-flattened device tree
|
||
considering only child and sibling pointers. There exists another pointer,
|
||
*parent, that is used to traverse the tree in the reverse direction. So, at
|
||
a particular level the child node and all the sibling nodes will have a parent
|
||
pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4’s
|
||
parent 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
|
||
|
||
|
||
*allnext: it is used to link all the nodes of DT into a list. So, for the
|
||
above tree the list would be as follows:
|
||
|
||
root->child1->child11->sibling12->sibling13->child131->sibling14->sibling2->
|
||
child21->sibling22->sibling23->sibling3->child31->sibling32->sibling4->null
|
||
|
||
Before executing OF selftest, it is required to attach the test data to
|
||
machine's device tree (if present). So, when selftest_data_add() is called,
|
||
at first it reads the flattened device tree data linked into the kernel image
|
||
via 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 calls of_fdt_unflatten_device_tree() to unflatten the flattened
|
||
blob. 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 it
|
||
attaches itself as a live device tree.
|
||
|
||
attach_node_and_children() uses of_attach_node() to attach the nodes into the
|
||
live tree as explained below. To explain the same, the test data tree described
|
||
in 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
|
||
|
||
|
||
allnext list:
|
||
|
||
root->testcase-data->test-child0->test-child01->test-sibling1->test-sibling2
|
||
->test-sibling3->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’t
|
||
required to attach the root(‘/’) node. All other nodes are attached by calling
|
||
of_attach_node() on each node.
|
||
|
||
In the function of_attach_node(), the new node is attached as the child of the
|
||
given parent in live tree. But, if parent already has a child then the new node
|
||
replaces the current child and turns it into its sibling. So, when the testcase
|
||
data node is attached to the live tree above (Figure 1), the final structure is
|
||
as 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 last
|
||
sibling compared to the earlier structure (Figure 2). After attaching first
|
||
test-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 is
|
||
already present in the live tree), then the node isn’t attached rather its
|
||
properties are updated to the live tree’s node by calling the function
|
||
update_node_properties().
|
||
|
||
|
||
2.2. Removing the test data
|
||
|
||
Once the test case execution is complete, selftest_data_remove is called in
|
||
order to remove the device nodes attached initially (first the leaf nodes are
|
||
detached and then moving up the parent nodes are removed, and eventually the
|
||
whole tree). selftest_data_remove() calls detach_node_and_children() that uses
|
||
of_detach_node() to detach the nodes from the live device tree.
|
||
|
||
To detach a node, of_detach_node() first updates all_next linked list, by
|
||
attaching the previous node’s allnext to current node’s allnext pointer. And
|
||
then, it either updates the child pointer of given node’s parent to its
|
||
sibling or attaches the previous sibling to the given node’s sibling, as
|
||
appropriate. That is it :)
|