docs: dt: convert of_unittest.txt to ReST

   writing-schema

   changesets

   dynamic-resolution-notes

   of_unittest

.. 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

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

OF Selftest has been designed to test the interface (include/linux/of.h)

provided to device driver developers to fetch the device information..etc.

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

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)

(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)

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 {

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 ('/')

    |

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

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 ('/')

	|

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 ('/')

    |

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