hollalinux
/
linux-sg2042
mirror of https://github.com/sophgo/linux-riscv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: dt: convert of_unittest.txt to ReST 

- 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>
Signed-off-by: Rob Herring <robh@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab 2020-04-15 16:45:21 +02:00 committed by Rob Herring
parent 26853a2420
commit 218e1b3d10
2 changed files with 98 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/devicetree/index.rst
View File

@ -11,3 +11,4 @@ Open Firmware and Device Tree
writing-schema writing-schema
changesets changesets
dynamic-resolution-notes dynamic-resolution-notes
of_unittest

186
Documentation/devicetree/of_unittest.txt → Documentation/devicetree/of_unittest.rst
View File

@ -1,9 +1,13 @@
.. SPDX-License-Identifier: GPL-2.0
==================================
Open Firmware Device Tree Unittest Open Firmware Device Tree Unittest
---------------------------------- ==================================
Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>
1. Introduction 1. Introduction
===============
This document explains how the test data required for executing OF unittest This document explains how the test data required for executing OF unittest
is attached to the live tree dynamically, independent of the machine's 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. It is recommended to read the following documents before moving ahead.
[1] Documentation/devicetree/usage-model.rst (1) Documentation/devicetree/usage-model.rst
[2] http://www.devicetree.org/Device_Tree_Usage (2) http://www.devicetree.org/Device_Tree_Usage
OF Selftest has been designed to test the interface (include/linux/of.h) OF Selftest has been designed to test the interface (include/linux/of.h)
provided to device driver developers to fetch the device information..etc. 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 2. Test-data
============
The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains
the test data required for executing the unit tests automated in the test data required for executing the unit tests automated in
drivers/of/unittest.c. Currently, following Device Tree Source Include files 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-interrupts.dtsi
drivers/of/unittest-data/tests-platform.dtsi drivers/of/unittest-data/tests-platform.dtsi
drivers/of/unittest-data/tests-phandle.dtsi drivers/of/unittest-data/tests-phandle.dtsi
drivers/of/unittest-data/tests-match.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 $(obj)/%.dtb: $(src)/%.dts FORCE
$(call if_changed_dep, dtc) $(call if_changed_dep, dtc)
is used to compile the DT source file (testcases.dts) into a binary blob is used to compile the DT source file (testcases.dts) into a binary blob
(testcases.dtb), also referred as flattened DT. (testcases.dtb), also referred as flattened DT.
After that, using the following rule the binary blob above is wrapped as an 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 $(obj)/%.dtb.S: $(obj)/%.dtb
$(call cmd, dt_S_dtb) $(call cmd, dt_S_dtb)
The assembly file is compiled into an object file (testcases.dtb.o), and is The assembly file is compiled into an object file (testcases.dtb.o), and is
linked into the kernel image. linked into the kernel image.
2.1. Adding the test data 2.1. Adding the test data
-------------------------
Un-flattened device tree structure: Un-flattened device tree structure:
Un-flattened device tree consists of connected device_node(s) in form of a tree 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 // following struct members are used to construct the tree
struct device_node { struct device_node {
... ...
struct device_node *parent; struct device_node *parent;
struct device_node *child; struct device_node *child;
struct device_node *sibling; struct device_node *sibling;
... ...
}; };
Figure 1, describes a generic structure of machine's un-flattened device tree Figure 1, describes a generic structure of machine's un-flattened device tree
considering only child and sibling pointers. There exists another pointer, 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 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 pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's
parent points to root node) parent points to root node)::
root ('/') root ('/')
| |
child1 -> sibling2 -> sibling3 -> sibling4 -> null child1 -> sibling2 -> sibling3 -> sibling4 -> null
| | | | | | | |
| | | null | | | null
| | | | | |
| | child31 -> sibling32 -> null | | child31 -> sibling32 -> null
| | | | | | | |
| | null null | | null null
| | | |
| child21 -> sibling22 -> sibling23 -> null | child21 -> sibling22 -> sibling23 -> null
| | | | | | | |
| null null null | null null null
| |
child11 -> sibling12 -> sibling13 -> sibling14 -> null child11 -> sibling12 -> sibling13 -> sibling14 -> null
| | | | | | | |
| | | null | | | null
| | | | | |
null null child131 -> null null null child131 -> null
| |
null null
Figure 1: Generic structure of un-flattened device tree 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 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, 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 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_begin - address marking the start of test data blob
__dtb_testcases_end - address marking the end 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 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, 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 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 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 ('/') root ('/')
| |
testcase-data testcase-data
| |
test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
| | | | | | | |
test-child01 null null null test-child01 null null null
Figure 2: Example test data tree to be attached to live tree. 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 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 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 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 ('/') root ('/')
| |
testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
| | | | | | | | | |
(...) | | | null (...) | | | null
| | child31 -> sibling32 -> null | | child31 -> sibling32 -> null
| | | | | | | |
| | null null | | null null
| | | |
| child21 -> sibling22 -> sibling23 -> null | child21 -> sibling22 -> sibling23 -> null
| | | | | | | |
| null null null | null null null
| |
child11 -> sibling12 -> sibling13 -> sibling14 -> null child11 -> sibling12 -> sibling13 -> sibling14 -> null
| | | | | | | |
null null | null null null | null
| |
child131 -> null child131 -> null
| |
null null
----------------------------------------------------------------------- -----------------------------------------------------------------------
root ('/') root ('/')
| |
testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
| | | | | | | | | |
| (...) (...) (...) null | (...) (...) (...) null
| |
test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
| | | | | | | |
null null null test-child01 null null null test-child01
Figure 3: Live device tree structure after attaching the testcase-data. 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 sibling compared to the earlier structure (Figure 2). After attaching first
test-child0 the test-sibling1 is attached that pushes the child node 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, (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 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 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 2.2. Removing the test data
---------------------------
Once the test case execution is complete, selftest_data_remove is called in 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 order to remove the device nodes attached initially (first the leaf nodes are