* [PATCH] Documentation regarding attaching OF Selftest testdata
@ 2014-09-03 7:16 Gaurav Minocha
[not found] ` <1409728589-9019-1-git-send-email-gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: Gaurav Minocha @ 2014-09-03 7:16 UTC (permalink / raw)
To: devicetree-u79uwXL29TY76Z2rM5mHXA
Cc: grant.likely-QSEj5FYQhm4dnm+yROfE0A,
rob.herring-QSEj5FYQhm4dnm+yROfE0A, Gaurav Minocha
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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
Documentation/devicetree/of_selftest.txt | 204 ++++++++++++++++++++++++++++++
1 file changed, 204 insertions(+)
create mode 100644 Documentation/devicetree/of_selftest.txt
diff --git a/Documentation/devicetree/of_selftest.txt b/Documentation/devicetree/of_selftest.txt
new file mode 100644
index 0000000..b1d9250
--- /dev/null
+++ b/Documentation/devicetree/of_selftest.txt
@@ -0,0 +1,204 @@
+Open Firmware Device Tree Selftest
+-----------------------------------
+
+Author: Gaurav Minocha <gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
+
+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 :)
--
1.7.9.5
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation regarding attaching OF Selftest testdata
[not found] ` <1409728589-9019-1-git-send-email-gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
@ 2014-09-08 13:20 ` Grant Likely
[not found] ` <20140908132007.02837C40AE5-WNowdnHR2B42iJbIjFUEsiwD8/FfD2ys@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: Grant Likely @ 2014-09-08 13:20 UTC (permalink / raw)
To: devicetree-u79uwXL29TY76Z2rM5mHXA
Cc: rob.herring-QSEj5FYQhm4dnm+yROfE0A, Gaurav Minocha
On Wed, 3 Sep 2014 00:16:29 -0700, Gaurav Minocha <gaurav.minocha.os@gmail.com> wrote:
> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
Applied, thanks.
Watch out for trailing whitespace. I had to tidy up many lines.
g.
> ---
> Documentation/devicetree/of_selftest.txt | 204 ++++++++++++++++++++++++++++++
> 1 file changed, 204 insertions(+)
> create mode 100644 Documentation/devicetree/of_selftest.txt
>
> diff --git a/Documentation/devicetree/of_selftest.txt b/Documentation/devicetree/of_selftest.txt
> new file mode 100644
> index 0000000..b1d9250
> --- /dev/null
> +++ b/Documentation/devicetree/of_selftest.txt
> @@ -0,0 +1,204 @@
> +Open Firmware Device Tree Selftest
> +-----------------------------------
> +
> +Author: Gaurav Minocha <gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> +
> +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 :)
> --
> 1.7.9.5
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation regarding attaching OF Selftest testdata
[not found] ` <20140908132007.02837C40AE5-WNowdnHR2B42iJbIjFUEsiwD8/FfD2ys@public.gmane.org>
@ 2014-09-23 1:09 ` Frank Rowand
[not found] ` <5420C852.5010905-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: Frank Rowand @ 2014-09-23 1:09 UTC (permalink / raw)
To: Grant Likely
Cc: Gaurav Minocha, devicetree-u79uwXL29TY76Z2rM5mHXA,
rob.herring-QSEj5FYQhm4dnm+yROfE0A
On 9/8/2014 6:20 AM, Grant Likely wrote:
> On Wed, 3 Sep 2014 00:16:29 -0700, Gaurav Minocha <gaurav.minocha.os@gmail.com> wrote:
>> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>
> Applied, thanks.
>
> Watch out for trailing whitespace. I had to tidy up many lines.
Is it ok to use UTF-8 characters outside the ascii range in Documentation .txt
files? If not, there are a few below (I'll point out at least a few inline).
The characters are all various forms of a quote or apostrophe.
I do not know what the characters in this reply will look like in anyone else's email
client. In thunderbird, the non-ascii UTF-8 characters in the original patch displayed
properly. In thunderbird, the same text in Grant's reply, prefixed with '> ' to indicate
an email reply the non-ascii UTF-8 is mangled. In thunderbird, if I reply to Grant's
reply, the same mangling occurs.
-Frank
>
> g.
>
>> ---
>> Documentation/devicetree/of_selftest.txt | 204 ++++++++++++++++++++++++++++++
>> 1 file changed, 204 insertions(+)
>> create mode 100644 Documentation/devicetree/of_selftest.txt
>>
>> diff --git a/Documentation/devicetree/of_selftest.txt b/Documentation/devicetree/of_selftest.txt
>> new file mode 100644
>> index 0000000..b1d9250
>> --- /dev/null
>> +++ b/Documentation/devicetree/of_selftest.txt
>> @@ -0,0 +1,204 @@
>> +Open Firmware Device Tree Selftest
>> +-----------------------------------
>> +
>> +Author: Gaurav Minocha <gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>> +
>> +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
^^^
non-ascii UTF-8
>> +parent points to root node)
>> +
>> +root (‘/’)
^^^ ^^^
non-ascii UTF-8
>> + |
>> +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 (‘/’)
^^^ ^^^
non-ascii UTF-8
>> + |
>> + 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 (‘/’)
^^^ ^^^
non-ascii UTF-8
>> + |
>> +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 (‘/’)
^^^ ^^^
non-ascii UTF-8
>> + |
>> +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
^^^
non-ascii UTF-8
>> +properties are updated to the live tree’s node by calling the function
^^^
non-ascii UTF-8
>> +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
^^^ ^^^
non-ascii UTF-8 non-ascii UTF-8
>> +then, it either updates the child pointer of given node’s parent to its
^^^
non-ascii UTF-8
>> +sibling or attaches the previous sibling to the given node’s sibling, as
^^^
non-ascii UTF-8
>> +appropriate. That is it :)
>> --
>> 1.7.9.5
>>
>
> --
> To unsubscribe from this list: send the line "unsubscribe devicetree" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation regarding attaching OF Selftest testdata
[not found] ` <5420C852.5010905-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
@ 2014-09-24 14:41 ` Grant Likely
[not found] ` <20140924144135.78D69C40738-WNowdnHR2B42iJbIjFUEsiwD8/FfD2ys@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: Grant Likely @ 2014-09-24 14:41 UTC (permalink / raw)
To: frowand.list-Re5JQEeQqe8AvxtiuMwx3w
Cc: Gaurav Minocha, devicetree-u79uwXL29TY76Z2rM5mHXA,
rob.herring-QSEj5FYQhm4dnm+yROfE0A
On Mon, 22 Sep 2014 18:09:38 -0700, Frank Rowand <frowand.list-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 9/8/2014 6:20 AM, Grant Likely wrote:
> > On Wed, 3 Sep 2014 00:16:29 -0700, Gaurav Minocha <gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> >> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> >
> > Applied, thanks.
> >
> > Watch out for trailing whitespace. I had to tidy up many lines.
>
> Is it ok to use UTF-8 characters outside the ascii range in Documentation .txt
> files? If not, there are a few below (I'll point out at least a few inline).
>
> The characters are all various forms of a quote or apostrophe.
>
> I do not know what the characters in this reply will look like in anyone else's email
> client. In thunderbird, the non-ascii UTF-8 characters in the original patch displayed
> properly. In thunderbird, the same text in Grant's reply, prefixed with '> ' to indicate
> an email reply the non-ascii UTF-8 is mangled. In thunderbird, if I reply to Grant's
> reply, the same mangling occurs.
Yeah, those should be fixed up. There is no reason to use non-ascii
UTF-8 quote characters in those places.
g.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation regarding attaching OF Selftest testdata
[not found] ` <20140924144135.78D69C40738-WNowdnHR2B42iJbIjFUEsiwD8/FfD2ys@public.gmane.org>
@ 2014-09-24 18:01 ` Gaurav Minocha
0 siblings, 0 replies; 5+ messages in thread
From: Gaurav Minocha @ 2014-09-24 18:01 UTC (permalink / raw)
To: Grant Likely
Cc: frowand.list-Re5JQEeQqe8AvxtiuMwx3w,
devicetree-u79uwXL29TY76Z2rM5mHXA, Rob Herring
On Wed, Sep 24, 2014 at 7:41 AM, Grant Likely <grant.likely-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:
> On Mon, 22 Sep 2014 18:09:38 -0700, Frank Rowand <frowand.list-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On 9/8/2014 6:20 AM, Grant Likely wrote:
>> > On Wed, 3 Sep 2014 00:16:29 -0700, Gaurav Minocha <gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> >> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>> >
>> > Applied, thanks.
>> >
>> > Watch out for trailing whitespace. I had to tidy up many lines.
>>
>> Is it ok to use UTF-8 characters outside the ascii range in Documentation .txt
>> files? If not, there are a few below (I'll point out at least a few inline).
>>
>> The characters are all various forms of a quote or apostrophe.
>>
>> I do not know what the characters in this reply will look like in anyone else's email
>> client. In thunderbird, the non-ascii UTF-8 characters in the original patch displayed
>> properly. In thunderbird, the same text in Grant's reply, prefixed with '> ' to indicate
>> an email reply the non-ascii UTF-8 is mangled. In thunderbird, if I reply to Grant's
>> reply, the same mangling occurs.
>
> Yeah, those should be fixed up. There is no reason to use non-ascii
> UTF-8 quote characters in those places.
Okay, I will fix it. Thanks!
>
> g.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2014-09-24 18:01 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-09-03 7:16 [PATCH] Documentation regarding attaching OF Selftest testdata Gaurav Minocha
[not found] ` <1409728589-9019-1-git-send-email-gaurav.minocha.os-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2014-09-08 13:20 ` Grant Likely
[not found] ` <20140908132007.02837C40AE5-WNowdnHR2B42iJbIjFUEsiwD8/FfD2ys@public.gmane.org>
2014-09-23 1:09 ` Frank Rowand
[not found] ` <5420C852.5010905-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2014-09-24 14:41 ` Grant Likely
[not found] ` <20140924144135.78D69C40738-WNowdnHR2B42iJbIjFUEsiwD8/FfD2ys@public.gmane.org>
2014-09-24 18:01 ` Gaurav Minocha
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.