On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> - Add a SPDX header;
> - Adjust document and section titles;
> - Adjust numerated list markups;
> - Some whitespace fixes and new line breaks;
> - Mark literal blocks as such;
> - Add it to devicetree/index.rst.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
> Documentation/devicetree/index.rst | 1 +
> .../{of_unittest.txt => of_unittest.rst} | 186 +++++++++---------
> 2 files changed, 98 insertions(+), 89 deletions(-)
> rename Documentation/devicetree/{of_unittest.txt => of_unittest.rst} (54%)
>
> diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> index 308cac9d7021..ca83258fbba5 100644
> --- a/Documentation/devicetree/index.rst
> +++ b/Documentation/devicetree/index.rst
> @@ -12,3 +12,4 @@ Open Firmware and Device Tree
> booting-without-of
> changesets
> dynamic-resolution-notes
> + of_unittest
> diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.rst
> similarity index 54%
> rename from Documentation/devicetree/of_unittest.txt
> rename to Documentation/devicetree/of_unittest.rst
> index 9fdd2de9b770..dea05214f3ad 100644
> --- a/Documentation/devicetree/of_unittest.txt
> +++ b/Documentation/devicetree/of_unittest.rst
> @@ -1,9 +1,13 @@
> +.. SPDX-License-Identifier: GPL-2.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
> @@ -11,8 +15,8 @@ architecture.
>
> It is recommended to read the following documents before moving ahead.
>
> -[1] Documentation/devicetree/usage-model.rst
> -[2] http://www.devicetree.org/Device_Tree_Usage
> +(1) Documentation/devicetree/usage-model.rst
> +(2) http://www.devicetree.org/Device_Tree_Usage
You caught this in 03/13. The file has moved to:
https://elinux.org/Device_Tree_Usage
-Frank
>
> OF Selftest has been designed to test the interface (include/linux/of.h)
> provided to device driver developers to fetch the device information..etc.
> @@ -21,79 +25,82 @@ 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:
> +(.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-interrupts.dtsi
> + drivers/of/unittest-data/tests-platform.dtsi
> + drivers/of/unittest-data/tests-phandle.dtsi
> + drivers/of/unittest-data/tests-match.dtsi
>
> -When the kernel is build with OF_SELFTEST enabled, then the following make rule
> +When the kernel is build with OF_SELFTEST enabled, then the following make
> +rule::
>
> -$(obj)/%.dtb: $(src)/%.dts FORCE
> - $(call if_changed_dep, dtc)
> + $(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).
> +assembly file (testcases.dtb.S)::
>
> -$(obj)/%.dtb.S: $(obj)/%.dtb
> - $(call cmd, dt_S_dtb)
> + $(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.
> +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;
> - ...
> - };
> + // 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
> +``*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)
> +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
> + 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
>
> @@ -101,10 +108,10 @@ 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 selftest_data_add() is called,
> at first it reads the flattened device tree data linked into the kernel image
> -via the following kernel symbols:
> +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
> + __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,
> @@ -113,15 +120,15 @@ 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.
> +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
> + 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.
> @@ -134,39 +141,39 @@ 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.
> +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
> + | | 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
> + 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.
> @@ -176,7 +183,7 @@ 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.
> +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
> @@ -185,6 +192,7 @@ 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
>
