| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <CA+rpMbKBa+8=sbwDFDMYcTkDHYZpkdiwejGN0r1+46uj==_upg@mail.gmail.com>
Date: Tue, 10 Mar 2015 21:26:41 -0700
From: Gaurav Minocha <gaurav.minocha.os@...il.com>
To: Wang Long <long.wanglong@...wei.com>
Cc: Rob Herring <robherring2@...il.com>,
Rob Herring <robh+dt@...nel.org>,
pantelis.antoniou@...sulko.com,
Grant Likely <grant.likely@...aro.org>,
Pawel Moll <pawel.moll@....com>,
Mark Rutland <mark.rutland@....com>,
Kumar Gala <galak@...eaurora.org>,
"devicetree@...r.kernel.org" <devicetree@...r.kernel.org>,
"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
peifeiyue@...wei.com, Ian Campbell <ijc+devicetree@...lion.org.uk>
Subject: Re: [PATCH 4/5] Documentation: rename of_selftest.txt to of_unittest.txt
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@...wei.com> 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@...wei.com>
> ---
> 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@...il.com>
> -
> -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@...il.com>
> +
> +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@...r.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Powered by blists - more mailing lists