Please use -M flag while sending rename patch, as mentioned in my other mail. On Tue, Mar 10, 2015 at 8:37 PM, Wang Long <long.wanglong@xxxxxxxxxx> wrote: > Since the test of the devicetree's OF api use unittest as > its name. so we should rename of_selftest.txt to of_unittest.txt. > > Signed-off-by: Wang Long <long.wanglong@xxxxxxxxxx> > --- > Documentation/devicetree/of_selftest.txt | 198 ------------------------------- > Documentation/devicetree/of_unittest.txt | 198 +++++++++++++++++++++++++++++++ > 2 files changed, 198 insertions(+), 198 deletions(-) > delete mode 100644 Documentation/devicetree/of_selftest.txt > create mode 100644 Documentation/devicetree/of_unittest.txt > > diff --git a/Documentation/devicetree/of_selftest.txt b/Documentation/devicetree/of_selftest.txt > deleted file mode 100644 > index d79a6bc..0000000 > --- a/Documentation/devicetree/of_selftest.txt > +++ /dev/null > @@ -1,198 +0,0 @@ > -Open Firmware Device Tree Unittest > ----------------------------------- > - > -Author: Gaurav Minocha <gaurav.minocha.os@xxxxxxxxx> > - > -1. Introduction > - > -This document explains how the test data required for executing OF unittest > -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/unittest-data/testcases.dts) contains > -the test data required for executing the unit tests automated in > -drivers/of/unittest.c. Currently, following Device Tree Source Include files > -(.dtsi) are included in testcases.dts: > - > -drivers/of/unittest-data/tests-interrupts.dtsi > -drivers/of/unittest-data/tests-platform.dtsi > -drivers/of/unittest-data/tests-phandle.dtsi > -drivers/of/unittest-data/tests-match.dtsi > -drivers/of/unittest-data/tests-overlay.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 (testcases.dts) into a binary blob > -(testcases.dtb), also referred as flattened DT. > - > -After that, using the following rule the binary blob above is wrapped as an > -assembly file (testcases.dtb.S). > - > -$(obj)/%.dtb.S: $(obj)/%.dtb > - $(call cmd, dt_S_dtb) > - > -The assembly file is compiled into an object file (testcases.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; > - ... > - }; > - > -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 > - > - > -Before executing OF unittest, it is required to attach the test data to > -machine's device tree (if present). So, when unittest_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_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 > - > - > -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, unittest_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). unittest_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() 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 :) > diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt > new file mode 100644 > index 0000000..d79a6bc > --- /dev/null > +++ b/Documentation/devicetree/of_unittest.txt > @@ -0,0 +1,198 @@ > +Open Firmware Device Tree Unittest > +---------------------------------- > + > +Author: Gaurav Minocha <gaurav.minocha.os@xxxxxxxxx> > + > +1. Introduction > + > +This document explains how the test data required for executing OF unittest > +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/unittest-data/testcases.dts) contains > +the test data required for executing the unit tests automated in > +drivers/of/unittest.c. Currently, following Device Tree Source Include files > +(.dtsi) are included in testcases.dts: > + > +drivers/of/unittest-data/tests-interrupts.dtsi > +drivers/of/unittest-data/tests-platform.dtsi > +drivers/of/unittest-data/tests-phandle.dtsi > +drivers/of/unittest-data/tests-match.dtsi > +drivers/of/unittest-data/tests-overlay.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 (testcases.dts) into a binary blob > +(testcases.dtb), also referred as flattened DT. > + > +After that, using the following rule the binary blob above is wrapped as an > +assembly file (testcases.dtb.S). > + > +$(obj)/%.dtb.S: $(obj)/%.dtb > + $(call cmd, dt_S_dtb) > + > +The assembly file is compiled into an object file (testcases.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; > + ... > + }; > + > +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 > + > + > +Before executing OF unittest, it is required to attach the test data to > +machine's device tree (if present). So, when unittest_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_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 > + > + > +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, unittest_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). unittest_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() 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 :) > -- > 1.8.3.4 > -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
