From: Frank Rowand <frowand.list@gmail.com>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
Rob Herring <robh+dt@kernel.org>,
devicetree@vger.kernel.org
Subject: Re: [PATCH v2 07/12] docs: dt: convert of_unittest.txt to ReST
Date: Mon, 2 Mar 2020 15:11:42 -0600 [thread overview]
Message-ID: <13c4a1d3-9d12-9085-8e05-218a7ab511c1@gmail.com> (raw)
In-Reply-To: <09f0a0877184ecdff1df1f6f6d38c164c6bdd8f6.1583135507.git.mchehab+huawei@kernel.org>
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@kernel.org>
> ---
> 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@gmail.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
> @@ -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
>
next prev parent reply other threads:[~2020-03-02 21:11 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-02 7:59 [PATCH v2 00/12] Convert some DT documentation files to ReST Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 01/12] docs: dt: add an index.rst file for devicetree Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST Mauro Carvalho Chehab
2020-03-02 11:54 ` Lee Jones
2020-03-02 21:11 ` Frank Rowand
2020-03-03 7:13 ` Mauro Carvalho Chehab
2020-03-02 21:18 ` Frank Rowand
2020-03-03 7:25 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage Mauro Carvalho Chehab
2020-03-02 21:11 ` Frank Rowand
2020-03-02 21:40 ` Rob Herring
2020-03-03 7:31 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format Mauro Carvalho Chehab
2020-03-04 18:25 ` Rob Herring
2020-03-05 1:45 ` Alex Shi
2020-03-02 7:59 ` [PATCH v2 05/12] docs: dt: convert changesets to ReST Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 06/12] docs: dt: convert dynamic-resolution-notes.txt " Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 07/12] docs: dt: convert of_unittest.txt " Mauro Carvalho Chehab
2020-03-02 21:11 ` Frank Rowand [this message]
2020-03-03 7:15 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format Mauro Carvalho Chehab
2020-03-02 21:13 ` Frank Rowand
2020-03-03 7:17 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 09/12] docs: dt: minor adjustments at writing-schema.rst Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 10/12] docs: dt: convert ABI.txt to ReST format Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 11/12] docs: dt: convert submitting-patches.txt " Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 12/12] docs: dt: convert writing-bindings.txt to ReST Mauro Carvalho Chehab
2020-03-02 19:35 ` [PATCH v2 00/12] Convert some DT documentation files " Jonathan Corbet
2020-03-03 7:09 ` Mauro Carvalho Chehab
2020-03-03 16:20 ` Rob Herring
2020-03-03 17:01 ` Mauro Carvalho Chehab
2020-03-03 17:07 ` Mauro Carvalho Chehab
2020-03-02 21:10 ` Frank Rowand
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=13c4a1d3-9d12-9085-8e05-218a7ab511c1@gmail.com \
--to=frowand.list@gmail.com \
--cc=corbet@lwn.net \
--cc=devicetree@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab+huawei@kernel.org \
--cc=robh+dt@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).