Re: [PATCH] Documentation regarding attaching OF Selftest testdata

[Frank Rowand <frowand.list-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

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