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.
--
An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
