[v2] docs: dt: Make references and mention kernel abstractions

  This document is named "Linux and Devicetree" so I think we
should write a bit more about how the device tree fits into
the Linux kernel frameworks these days after we have created
the fwnode and swnode.

Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
These docs are old and outdated and need to be edited to
reflect the current situation.
---
ChangeLog v1->v2:
- Spelling mistakes
- Resend because nothing happens
---
 Documentation/devicetree/usage-model.rst | 45 +++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 4 deletions(-)


---
base-commit: 457391b0380335d5e9a5babdec90ac53928b23b4
change-id: 20230505-dt-docs-refresh-515edbdbbd01

Best regards,
  

On Fri, May 05, 2023 at 02:43:53PM +0200, Linus Walleij wrote:
> This document is named "Linux and Devicetree" so I think we
> should write a bit more about how the device tree fits into
> the Linux kernel frameworks these days after we have created
> the fwnode and swnode.
> 

Also Cc: linux-doc list.

> +The Linux kernel supports several different hardware description
> +frameworks and DT is just one of them. The closest sibling is the
> +:ref:`Documentation/firmware-guide/acpi/index.rst ACPI`
> +DSDT (Differentiated System Description Table).
> <snipped>...
> +Further, when the DT core register devices these need to fold into the
> +Linux device driver model, which essentially means that some kind of
> +``struct device`` has to be created to match a corresponding
> +``struct device_driver``. This API can be explored in
> +detail in :ref:`Documentation/driver-api/driver-model/index.rst the driver API documentation`
> +but what you need to know is that the Linux DT parser code will on its
> +own mostly spawn platform devices and AMBA devices on the platform
> +and AMBA bus respectively, and apart from that it will augment devices
> +spawn on other buses where applicable.
> +

Anchor text for :ref: links above don't mix well, so I have to override
them (also specifying intended doc target - correct me if these are wrong):

diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
index 37605cb549cf59..87f522d5feba81 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -80,8 +80,7 @@ then go read it now.  It's okay, I'll wait....
 
 The Linux kernel supports several different hardware description
 frameworks and DT is just one of them. The closest sibling is the
-:ref:`Documentation/firmware-guide/acpi/index.rst ACPI`
-DSDT (Differentiated System Description Table).
+:doc:`DSDT (Differentiated System Description Table) from ACPI </firmware-guide/acpi/namespace>`.
 
 To make it possible to write a device driver that will adapt to DT
 or other hardware description models, the kernel has grown some
@@ -101,7 +100,7 @@ Further, when the DT core register devices these need to fold into the
 Linux device driver model, which essentially means that some kind of
 ``struct device`` has to be created to match a corresponding
 ``struct device_driver``. This API can be explored in
-detail in :ref:`Documentation/driver-api/driver-model/index.rst the driver API documentation`
+detail in :doc:`the driver API documentation </driver-api/driver-model/overview>`
 but what you need to know is that the Linux DT parser code will on its
 own mostly spawn platform devices and AMBA devices on the platform
 and AMBA bus respectively, and apart from that it will augment devices

Thanks.
  

Hi Linus,

I am noting a few grammar nits below...

[and + linux-doc]

On 5/5/23 05:43, Linus Walleij wrote:
> This document is named "Linux and Devicetree" so I think we
> should write a bit more about how the device tree fits into
> the Linux kernel frameworks these days after we have created
> the fwnode and swnode.
> 
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> ---
> These docs are old and outdated and need to be edited to
> reflect the current situation.
> ---
> ChangeLog v1->v2:
> - Spelling mistakes
> - Resend because nothing happens
> ---
>  Documentation/devicetree/usage-model.rst | 45 +++++++++++++++++++++++++++++---
>  1 file changed, 41 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
> index b6a287955ee5..37605cb549cf 100644
> --- a/Documentation/devicetree/usage-model.rst
> +++ b/Documentation/devicetree/usage-model.rst
> @@ -75,7 +75,44 @@ out of mainline (nios) have some level of DT support.
>  If you haven't already read the Device Tree Usage\ [1]_ page,
>  then go read it now.  It's okay, I'll wait....
>  
> -2.1 High Level View
> +2.1 Linux Kernel Firmware Abstractions
> +--------------------------------------
> +
> +The Linux kernel supports several different hardware description
> +frameworks and DT is just one of them. The closest sibling is the
> +:ref:`Documentation/firmware-guide/acpi/index.rst ACPI`
> +DSDT (Differentiated System Description Table).
> +
> +To make it possible to write a device driver that will adapt to DT
> +or other hardware description models, the kernel has grown some
> +abstractions, first and foremost the firmware node API, exposing
> +device properties. The firmware node "fwnode" internals can be found
> +in ``<linux/fwnode.h>`` while the device driver-facing API can be
> +found in ``<linux/property.h>``. The idea is that if a driver is using
> +the firmware node API, it should be trivial to support DT and ACPI
> +DSDT alike in the same driver.
> +
> +The fwnode framework also makes it possible to modify and extend the
> +Linux in-kernel model with software-managed nodes "swnodes" to apply
> +quirks or manage registration of devices that cannot be handled any
> +other way. This API can also be found in ``<linux/property.h>``.
> +
> +Further, when the DT core register devices these need to fold into the

                        core registers

> +Linux device driver model, which essentially means that some kind of
> +``struct device`` has to be created to match a corresponding
> +``struct device_driver``. This API can be explored in
> +detail in :ref:`Documentation/driver-api/driver-model/index.rst the driver API documentation`
> +but what you need to know is that the Linux DT parser code will on its
> +own mostly spawn platform devices and AMBA devices on the platform
> +and AMBA bus respectively, and apart from that it will augment devices
> +spawn on other buses where applicable.

   spawned

> +
> +Every Linux kernel subsystem that want to supply additional data to

                                that wants

> +detected devices using the device tree, or that want to provide

                                              that wants

> +resources to other devices in the DT, will need to implement calls into
> +the DT abstractions.
> +
> +2.2 High Level View
>  -------------------
>  The most important thing to understand is that the DT is simply a data
>  structure that describes the hardware.  There is nothing magical about
> @@ -97,7 +134,7 @@ Linux uses DT data for three major purposes:
>  2) runtime configuration, and
>  3) device population.
>  
> -2.2 Platform Identification
> +2.3 Platform Identification
>  ---------------------------
>  First and foremost, the kernel will use data in the DT to identify the
>  specific machine.  In a perfect world, the specific platform shouldn't
> @@ -180,7 +217,7 @@ However, this approach does not take into account the priority of the
>  compatible list, and probably should be avoided for new architecture
>  support.
>  
> -2.3 Runtime configuration
> +2.4 Runtime configuration
>  -------------------------
>  In most cases, a DT will be the sole method of communicating data from
>  firmware to the kernel, so also gets used to pass in runtime and
> @@ -217,7 +254,7 @@ On ARM, the function setup_machine_fdt() is responsible for early
>  scanning of the device tree after selecting the correct machine_desc
>  that supports the board.
>  
> -2.4 Device population
> +2.5 Device population
>  ---------------------
>  After the board has been identified, and after the early configuration data
>  has been parsed, then kernel initialization can proceed in the normal
> 
> ---
> base-commit: 457391b0380335d5e9a5babdec90ac53928b23b4
> change-id: 20230505-dt-docs-refresh-515edbdbbd01
> 
> Best regards,

For @linux-doc: Is there something in ReST that does auto section numbering
so that this renumbering does not have to be repeated in the future?


Thanks for the additional documentation.
  

On Sat, May 06, 2023 at 03:09:11PM -0700, Randy Dunlap wrote:
> For @linux-doc: Is there something in ReST that does auto section numbering
> so that this renumbering does not have to be repeated in the future?
> 

There is sectnum:: directive which does the job. In the kernel docs,
however, it is customarily used together with contents:: directive to
generate toctree for current doc. In order for this to work as expected,
you need also to rearrange section heading levels, like:

---- >8 ----
diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
index 87f522d5feba81..890dde293540f9 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -1,5 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. contents::
+.. sectnum::
+
 ========================
 Linux and the Devicetree
 ========================
@@ -76,7 +79,7 @@ If you haven't already read the Device Tree Usage\ [1]_ page,
 then go read it now.  It's okay, I'll wait....
 
 2.1 Linux Kernel Firmware Abstractions
---------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Linux kernel supports several different hardware description
 frameworks and DT is just one of them. The closest sibling is the
@@ -112,7 +115,8 @@ resources to other devices in the DT, will need to implement calls into
 the DT abstractions.
 
 2.2 High Level View
--------------------
+~~~~~~~~~~~~~~~~~~~
+
 The most important thing to understand is that the DT is simply a data
 structure that describes the hardware.  There is nothing magical about
 it, and it doesn't magically make all hardware configuration problems
@@ -134,7 +138,8 @@ Linux uses DT data for three major purposes:
 3) device population.
 
 2.3 Platform Identification
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 First and foremost, the kernel will use data in the DT to identify the
 specific machine.  In a perfect world, the specific platform shouldn't
 matter to the kernel because all platform details would be described
@@ -217,7 +222,8 @@ compatible list, and probably should be avoided for new architecture
 support.
 
 2.4 Runtime configuration
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 In most cases, a DT will be the sole method of communicating data from
 firmware to the kernel, so also gets used to pass in runtime and
 configuration data like the kernel parameters string and the location
@@ -254,7 +260,8 @@ scanning of the device tree after selecting the correct machine_desc
 that supports the board.
 
 2.5 Device population
----------------------
+~~~~~~~~~~~~~~~~~~~~~
+
 After the board has been identified, and after the early configuration data
 has been parsed, then kernel initialization can proceed in the normal
 way.  At some point in this process, unflatten_device_tree() is called

The caveat is the title heading also get numbered, making it top-level
section. Hence, it is more appropriate if the directory toctree:: also
have :numbered: option to do the job instead:

---- >8 ----
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 1a2fc80149966e..b5297dd511ef31 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -8,6 +8,7 @@ Kernel Devicetree Usage
 =======================
 .. toctree::
    :maxdepth: 1
+   :numbered:
 
    usage-model
    of_unittest

Anyway, if you use auto section numbering, you need to also remove the manual
numbers:

---- >8 ----
diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
index 0ff62cdb3cc51c..e2dfbcc38c2f03 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -42,8 +42,8 @@ incompatible, bindings for i2c busses that came about because the new
 binding was created without first investigating how i2c devices were
 already being enumerated in existing systems.
 
-1. History
-----------
+History
+-------
 The DT was originally created by Open Firmware as part of the
 communication method for passing data from Open Firmware to a client
 program (like to an operating system).  An operating system used the
@@ -72,13 +72,13 @@ all architectures.  At the time of this writing, 6 mainlined
 architectures (arm, microblaze, mips, powerpc, sparc, and x86) and 1
 out of mainline (nios) have some level of DT support.
 
-2. Data Model
--------------
+Data Model
+----------
 If you haven't already read the Device Tree Usage\ [1]_ page,
 then go read it now.  It's okay, I'll wait....
 
-2.1 Linux Kernel Firmware Abstractions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Linux Kernel Firmware Abstractions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Linux kernel supports several different hardware description
 frameworks and DT is just one of them. The closest sibling is the
@@ -113,8 +113,8 @@ detected devices using the device tree, or that want to provide
 resources to other devices in the DT, will need to implement calls into
 the DT abstractions.
 
-2.2 High Level View
-~~~~~~~~~~~~~~~~~~~
+High Level View
+~~~~~~~~~~~~~~~
 
 The most important thing to understand is that the DT is simply a data
 structure that describes the hardware.  There is nothing magical about
@@ -136,8 +136,8 @@ Linux uses DT data for three major purposes:
 2) runtime configuration, and
 3) device population.
 
-2.3 Platform Identification
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Platform Identification
+~~~~~~~~~~~~~~~~~~~~~~~
 
 First and foremost, the kernel will use data in the DT to identify the
 specific machine.  In a perfect world, the specific platform shouldn't
@@ -220,8 +220,8 @@ However, this approach does not take into account the priority of the
 compatible list, and probably should be avoided for new architecture
 support.
 
-2.4 Runtime configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Runtime configuration
+~~~~~~~~~~~~~~~~~~~~~
 
 In most cases, a DT will be the sole method of communicating data from
 firmware to the kernel, so also gets used to pass in runtime and
@@ -258,8 +258,8 @@ On ARM, the function setup_machine_fdt() is responsible for early
 scanning of the device tree after selecting the correct machine_desc
 that supports the board.
 
-2.5 Device population
-~~~~~~~~~~~~~~~~~~~~~
+Device population
+~~~~~~~~~~~~~~~~~
 
 After the board has been identified, and after the early configuration data
 has been parsed, then kernel initialization can proceed in the normal

Thanks.
  

Hi,

On Date: Mon, 8 May 2023 21:13:05 +0700, Bagas Sanjaya wrote:
> On Sat, May 06, 2023 at 03:09:11PM -0700, Randy Dunlap wrote:
>> For @linux-doc: Is there something in ReST that does auto section numbering
>> so that this renumbering does not have to be repeated in the future?
>> 
> 
> There is sectnum:: directive which does the job. In the kernel docs,

Just for you info:

In Sphinx documentation at:
    https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

has a warning which reads:

    Warning
    Do not use the directives sectnum, header and footer. 

Sphinx prefers the the :numbered: option of the toctree:: directive.
See https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree

This directive applies to the documentation as a whole, not to each .rst
file.

An example is at:
    https://www.kernel.org/doc/html/latest/process/development-process.html

Just my two cents.

        Thanks, Akira

> however, it is customarily used together with contents:: directive to
> generate toctree for current doc. In order for this to work as expected,
> you need also to rearrange section heading levels, like:
> 
> ---- >8 ----
> diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
> index 87f522d5feba81..890dde293540f9 100644
> --- a/Documentation/devicetree/usage-model.rst
> +++ b/Documentation/devicetree/usage-model.rst
> @@ -1,5 +1,8 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> +.. contents::
> +.. sectnum::
> +
>  ========================
>  Linux and the Devicetree
>  ========================