Re: [PATCH 4/5] Documentation: rename of_selftest.txt to of_unittest.txt

[Gaurav Minocha]

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 linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/