[PATCH v2 01/12] docs: dt: add an index.rst file for devicetree

[PATCH v2 01/12] docs: dt: add an index.rst file for devicetree

[Mauro Carvalho Chehab]

There are some device tree documentation under
Documentation/devicetree. Add a top index file for it and
add the already-existing ReST file on it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/devicetree/index.rst | 10 ++++++++++
 Documentation/index.rst            |  3 +++
 2 files changed, 13 insertions(+)
 create mode 100644 Documentation/devicetree/index.rst

diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
new file mode 100644
index 000000000000..a11efe26f205
--- /dev/null
+++ b/Documentation/devicetree/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+Open Firmware and Device Tree
+=============================
+
+.. toctree::
+   :maxdepth: 1
+
+   writing-schema
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e99d0bd2589d..b63d117aea15 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
 
 .. The Linux Kernel documentation master file, created by
    sphinx-quickstart on Fri Feb 12 13:51:46 2016.
@@ -46,6 +48,7 @@ platform firmwares.
    :maxdepth: 2
 
    firmware-guide/index
+   devicetree/index
 
 Application-developer documentation
 -----------------------------------
-- 
2.21.1

[PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Adjust document title;
- Use footnoote 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 +
 Documentation/devicetree/of_unittest.txt      |  2 +-
 .../{usage-model.txt => usage-model.rst}      | 35 +++++++++++--------
 include/linux/mfd/core.h                      |  2 +-
 4 files changed, 23 insertions(+), 17 deletions(-)
 rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)

diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index a11efe26f205..7a6aad7d384a 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -7,4 +7,5 @@ Open Firmware and Device Tree
 .. toctree::
    :maxdepth: 1
 
+   usage-model
    writing-schema
diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt
index 3e4e7d48ae93..9fdd2de9b770 100644
--- a/Documentation/devicetree/of_unittest.txt
+++ b/Documentation/devicetree/of_unittest.txt
@@ -11,7 +11,7 @@ architecture.
 
 It is recommended to read the following documents before moving ahead.
 
-[1] Documentation/devicetree/usage-model.txt
+[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)
diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.rst
similarity index 97%
rename from Documentation/devicetree/usage-model.txt
rename to Documentation/devicetree/usage-model.rst
index 33a8aaac02a8..326d7af10c5b 100644
--- a/Documentation/devicetree/usage-model.txt
+++ b/Documentation/devicetree/usage-model.rst
@@ -1,14 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
 Linux and the Device Tree
--------------------------
+=========================
+
 The Linux usage model for device tree data
 
-Author: Grant Likely <grant.likely@secretlab.ca>
+:Author: Grant Likely <grant.likely@secretlab.ca>
 
 This article describes how Linux uses the device tree.  An overview of
 the device tree data format can be found on the device tree usage page
-at devicetree.org[1].
+at devicetree.org\ [1]_.
 
-[1] http://devicetree.org/Device_Tree_Usage
+.. [1] http://devicetree.org/Device_Tree_Usage
 
 The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
 structure and language for describing hardware.  More specifically, it
@@ -57,7 +61,7 @@ Tree (FDT) was created which could be passed to the kernel as a binary
 blob without requiring a real Open Firmware implementation.  U-Boot,
 kexec, and other bootloaders were modified to support both passing a
 Device Tree Binary (dtb) and to modify a dtb at boot time.  DT was
-also added to the PowerPC boot wrapper (arch/powerpc/boot/*) so that
+also added to the PowerPC boot wrapper (``arch/powerpc/boot/*``) so that
 a dtb could be wrapped up with the kernel image to support booting
 existing non-DT aware firmware.
 
@@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support.
 
 2. Data Model
 -------------
-If you haven't already read the Device Tree Usage[1] page,
+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
@@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware
 with a single kernel image.
 
 Linux uses DT data for three major purposes:
+
 1) platform identification,
 2) runtime configuration, and
 3) device population.
@@ -117,7 +122,7 @@ The 'compatible' property contains a sorted list of strings starting
 with the exact name of the machine, followed by an optional list of
 boards it is compatible with sorted from most compatible to least.  For
 example, the root compatible properties for the TI BeagleBoard and its
-successor, the BeagleBoard xM board might look like, respectively:
+successor, the BeagleBoard xM board might look like, respectively::
 
 	compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
 	compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";
@@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location
 of an initrd image.
 
 Most of this data is contained in the /chosen node, and when booting
-Linux it will look something like this:
+Linux it will look something like this::
 
 	chosen {
 		bootargs = "console=ttyS0,115200 loglevel=8";
@@ -251,9 +256,9 @@ platform devices roughly correspond to device nodes at the root of the
 tree and children of simple memory mapped bus nodes.
 
 About now is a good time to lay out an example.  Here is part of the
-device tree for the NVIDIA Tegra board.
+device tree for the NVIDIA Tegra board::
 
-/{
+  /{
 	compatible = "nvidia,harmony", "nvidia,tegra20";
 	#address-cells = <1>;
 	#size-cells = <1>;
@@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board.
 		i2s-controller = <&i2s1>;
 		i2s-codec = <&wm8903>;
 	};
-};
+  };
 
 At .init_machine() time, Tegra board support code will need to look at
 this DT and decide which nodes to create platform_devices for.
@@ -379,13 +384,13 @@ device tree support code reflects that and makes the above example
 simpler.  The second argument to of_platform_populate() is an
 of_device_id table, and any node that matches an entry in that table
 will also get its child nodes registered.  In the Tegra case, the code
-can look something like this:
+can look something like this::
 
-static void __init harmony_init_machine(void)
-{
+  static void __init harmony_init_machine(void)
+  {
 	/* ... */
 	of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL);
-}
+  }
 
 "simple-bus" is defined in the Devicetree Specification as a property
 meaning a simple memory mapped bus, so the of_platform_populate() code
diff --git a/include/linux/mfd/core.h b/include/linux/mfd/core.h
index d01d1299e49d..21718c8b2b48 100644
--- a/include/linux/mfd/core.h
+++ b/include/linux/mfd/core.h
@@ -74,7 +74,7 @@ struct mfd_cell {
 
 	/*
 	 * Device Tree compatible string
-	 * See: Documentation/devicetree/usage-model.txt Chapter 2.2 for details
+	 * See: Documentation/devicetree/usage-model.rst Chapter 2.2 for details
 	 */
 	const char		*of_compatible;
 
-- 
2.21.1

Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST

[Lee Jones]

On Mon, 02 Mar 2020, Mauro Carvalho Chehab wrote:

> - Add a SPDX header;
> - Adjust document title;
> - Use footnoote 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 +
>  Documentation/devicetree/of_unittest.txt      |  2 +-
>  .../{usage-model.txt => usage-model.rst}      | 35 +++++++++++--------

>  include/linux/mfd/core.h                      |  2 +-

Acked-by: Lee Jones <lee.jones@linaro.org>

>  4 files changed, 23 insertions(+), 17 deletions(-)
>  rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)

-- 
Lee Jones [李琼斯]
Linaro Services Technical Lead
Linaro.org │ Open source software for ARM SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST

[Frank Rowand]

On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> - Add a SPDX header;
> - Adjust document title;
> - Use footnoote 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 +
>  Documentation/devicetree/of_unittest.txt      |  2 +-
>  .../{usage-model.txt => usage-model.rst}      | 35 +++++++++++--------
>  include/linux/mfd/core.h                      |  2 +-
>  4 files changed, 23 insertions(+), 17 deletions(-)
>  rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)
> 
> diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> index a11efe26f205..7a6aad7d384a 100644
> --- a/Documentation/devicetree/index.rst
> +++ b/Documentation/devicetree/index.rst
> @@ -7,4 +7,5 @@ Open Firmware and Device Tree
>  .. toctree::
>     :maxdepth: 1
>  
> +   usage-model
>     writing-schema
> diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt
> index 3e4e7d48ae93..9fdd2de9b770 100644
> --- a/Documentation/devicetree/of_unittest.txt
> +++ b/Documentation/devicetree/of_unittest.txt
> @@ -11,7 +11,7 @@ architecture.
>  
>  It is recommended to read the following documents before moving ahead.
>  
> -[1] Documentation/devicetree/usage-model.txt
> +[1] Documentation/devicetree/usage-model.rst
>  [2] http://www.devicetree.org/Device_Tree_Usage

You caught this in 03/12.  The file has moved to:

   https://elinux.org/Device_Tree_Usage

>  
>  OF Selftest has been designed to test the interface (include/linux/of.h)
> diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.rst
> similarity index 97%
> rename from Documentation/devicetree/usage-model.txt
> rename to Documentation/devicetree/usage-model.rst
> index 33a8aaac02a8..326d7af10c5b 100644
> --- a/Documentation/devicetree/usage-model.txt
> +++ b/Documentation/devicetree/usage-model.rst
> @@ -1,14 +1,18 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=========================
>  Linux and the Device Tree
> --------------------------
> +=========================
> +
>  The Linux usage model for device tree data
>  
> -Author: Grant Likely <grant.likely@secretlab.ca>
> +:Author: Grant Likely <grant.likely@secretlab.ca>
>  
>  This article describes how Linux uses the device tree.  An overview of
>  the device tree data format can be found on the device tree usage page
> -at devicetree.org[1].
> +at devicetree.org\ [1]_.
>  
> -[1] http://devicetree.org/Device_Tree_Usage
> +.. [1] http://devicetree.org/Device_Tree_Usage

And same moved location here.

-Frank


>  
>  The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
>  structure and language for describing hardware.  More specifically, it
> @@ -57,7 +61,7 @@ Tree (FDT) was created which could be passed to the kernel as a binary
>  blob without requiring a real Open Firmware implementation.  U-Boot,
>  kexec, and other bootloaders were modified to support both passing a
>  Device Tree Binary (dtb) and to modify a dtb at boot time.  DT was
> -also added to the PowerPC boot wrapper (arch/powerpc/boot/*) so that
> +also added to the PowerPC boot wrapper (``arch/powerpc/boot/*``) so that
>  a dtb could be wrapped up with the kernel image to support booting
>  existing non-DT aware firmware.
>  
> @@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support.
>  
>  2. Data Model
>  -------------
> -If you haven't already read the Device Tree Usage[1] page,
> +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
> @@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware
>  with a single kernel image.
>  
>  Linux uses DT data for three major purposes:
> +
>  1) platform identification,
>  2) runtime configuration, and
>  3) device population.
> @@ -117,7 +122,7 @@ The 'compatible' property contains a sorted list of strings starting
>  with the exact name of the machine, followed by an optional list of
>  boards it is compatible with sorted from most compatible to least.  For
>  example, the root compatible properties for the TI BeagleBoard and its
> -successor, the BeagleBoard xM board might look like, respectively:
> +successor, the BeagleBoard xM board might look like, respectively::
>  
>  	compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
>  	compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";
> @@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location
>  of an initrd image.
>  
>  Most of this data is contained in the /chosen node, and when booting
> -Linux it will look something like this:
> +Linux it will look something like this::
>  
>  	chosen {
>  		bootargs = "console=ttyS0,115200 loglevel=8";
> @@ -251,9 +256,9 @@ platform devices roughly correspond to device nodes at the root of the
>  tree and children of simple memory mapped bus nodes.
>  
>  About now is a good time to lay out an example.  Here is part of the
> -device tree for the NVIDIA Tegra board.
> +device tree for the NVIDIA Tegra board::
>  
> -/{
> +  /{
>  	compatible = "nvidia,harmony", "nvidia,tegra20";
>  	#address-cells = <1>;
>  	#size-cells = <1>;
> @@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board.
>  		i2s-controller = <&i2s1>;
>  		i2s-codec = <&wm8903>;
>  	};
> -};
> +  };
>  
>  At .init_machine() time, Tegra board support code will need to look at
>  this DT and decide which nodes to create platform_devices for.
> @@ -379,13 +384,13 @@ device tree support code reflects that and makes the above example
>  simpler.  The second argument to of_platform_populate() is an
>  of_device_id table, and any node that matches an entry in that table
>  will also get its child nodes registered.  In the Tegra case, the code
> -can look something like this:
> +can look something like this::
>  
> -static void __init harmony_init_machine(void)
> -{
> +  static void __init harmony_init_machine(void)
> +  {
>  	/* ... */
>  	of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL);
> -}
> +  }
>  
>  "simple-bus" is defined in the Devicetree Specification as a property
>  meaning a simple memory mapped bus, so the of_platform_populate() code
> diff --git a/include/linux/mfd/core.h b/include/linux/mfd/core.h
> index d01d1299e49d..21718c8b2b48 100644
> --- a/include/linux/mfd/core.h
> +++ b/include/linux/mfd/core.h
> @@ -74,7 +74,7 @@ struct mfd_cell {
>  
>  	/*
>  	 * Device Tree compatible string
> -	 * See: Documentation/devicetree/usage-model.txt Chapter 2.2 for details
> +	 * See: Documentation/devicetree/usage-model.rst Chapter 2.2 for details
>  	 */
>  	const char		*of_compatible;
>  
> 

Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST

[Mauro Carvalho Chehab]

Em Mon, 2 Mar 2020 15:11:07 -0600
Frank Rowand <frowand.list@gmail.com> escreveu:

> On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> > - Add a SPDX header;
> > - Adjust document title;
> > - Use footnoote 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 +
> >  Documentation/devicetree/of_unittest.txt      |  2 +-
> >  .../{usage-model.txt => usage-model.rst}      | 35 +++++++++++--------
> >  include/linux/mfd/core.h                      |  2 +-
> >  4 files changed, 23 insertions(+), 17 deletions(-)
> >  rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)
> > 
> > diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> > index a11efe26f205..7a6aad7d384a 100644
> > --- a/Documentation/devicetree/index.rst
> > +++ b/Documentation/devicetree/index.rst
> > @@ -7,4 +7,5 @@ Open Firmware and Device Tree
> >  .. toctree::
> >     :maxdepth: 1
> >  
> > +   usage-model
> >     writing-schema
> > diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt
> > index 3e4e7d48ae93..9fdd2de9b770 100644
> > --- a/Documentation/devicetree/of_unittest.txt
> > +++ b/Documentation/devicetree/of_unittest.txt
> > @@ -11,7 +11,7 @@ architecture.
> >  
> >  It is recommended to read the following documents before moving ahead.
> >  
> > -[1] Documentation/devicetree/usage-model.txt
> > +[1] Documentation/devicetree/usage-model.rst
> >  [2] http://www.devicetree.org/Device_Tree_Usage  
> 
> You caught this in 03/12.  The file has moved to:
> 
>    https://elinux.org/Device_Tree_Usage

Thanks for noticing it!

In order to make the changelogs clearer, instead of modifying this
patch, I'll add an extra hook on patch 03/12 also changing this one. 

> 
> >  
> >  OF Selftest has been designed to test the interface (include/linux/of.h)
> > diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.rst
> > similarity index 97%
> > rename from Documentation/devicetree/usage-model.txt
> > rename to Documentation/devicetree/usage-model.rst
> > index 33a8aaac02a8..326d7af10c5b 100644
> > --- a/Documentation/devicetree/usage-model.txt
> > +++ b/Documentation/devicetree/usage-model.rst
> > @@ -1,14 +1,18 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=========================
> >  Linux and the Device Tree
> > --------------------------
> > +=========================
> > +
> >  The Linux usage model for device tree data
> >  
> > -Author: Grant Likely <grant.likely@secretlab.ca>
> > +:Author: Grant Likely <grant.likely@secretlab.ca>
> >  
> >  This article describes how Linux uses the device tree.  An overview of
> >  the device tree data format can be found on the device tree usage page
> > -at devicetree.org[1].
> > +at devicetree.org\ [1]_.
> >  
> > -[1] http://devicetree.org/Device_Tree_Usage
> > +.. [1] http://devicetree.org/Device_Tree_Usage  
> 
> And same moved location here.

And this one too.

> 
> -Frank

Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST

[Frank Rowand]

On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> - Add a SPDX header;
> - Adjust document title;
> - Use footnoote 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 +
>  Documentation/devicetree/of_unittest.txt      |  2 +-
>  .../{usage-model.txt => usage-model.rst}      | 35 +++++++++++--------
>  include/linux/mfd/core.h                      |  2 +-
>  4 files changed, 23 insertions(+), 17 deletions(-)
>  rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)
> 
> diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> index a11efe26f205..7a6aad7d384a 100644
> --- a/Documentation/devicetree/index.rst
> +++ b/Documentation/devicetree/index.rst
> @@ -7,4 +7,5 @@ Open Firmware and Device Tree
>  .. toctree::
>     :maxdepth: 1
>  
> +   usage-model
>     writing-schema
> diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt
> index 3e4e7d48ae93..9fdd2de9b770 100644
> --- a/Documentation/devicetree/of_unittest.txt
> +++ b/Documentation/devicetree/of_unittest.txt
> @@ -11,7 +11,7 @@ architecture.
>  
>  It is recommended to read the following documents before moving ahead.
>  
> -[1] Documentation/devicetree/usage-model.txt
> +[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)
> diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.rst
> similarity index 97%
> rename from Documentation/devicetree/usage-model.txt
> rename to Documentation/devicetree/usage-model.rst
> index 33a8aaac02a8..326d7af10c5b 100644
> --- a/Documentation/devicetree/usage-model.txt
> +++ b/Documentation/devicetree/usage-model.rst
> @@ -1,14 +1,18 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=========================
>  Linux and the Device Tree
> --------------------------
> +=========================
> +
>  The Linux usage model for device tree data
>  
> -Author: Grant Likely <grant.likely@secretlab.ca>
> +:Author: Grant Likely <grant.likely@secretlab.ca>
>  
>  This article describes how Linux uses the device tree.  An overview of
>  the device tree data format can be found on the device tree usage page
> -at devicetree.org[1].
> +at devicetree.org\ [1]_.
>  
> -[1] http://devicetree.org/Device_Tree_Usage
> +.. [1] http://devicetree.org/Device_Tree_Usage

I don't know the proper ReST syntax for footnotes, but on the html page
you kindly provided in 00/12, '.. [1]' is shown as '1(1,2)'.

-Frank


>  
>  The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
>  structure and language for describing hardware.  More specifically, it
> @@ -57,7 +61,7 @@ Tree (FDT) was created which could be passed to the kernel as a binary
>  blob without requiring a real Open Firmware implementation.  U-Boot,
>  kexec, and other bootloaders were modified to support both passing a
>  Device Tree Binary (dtb) and to modify a dtb at boot time.  DT was
> -also added to the PowerPC boot wrapper (arch/powerpc/boot/*) so that
> +also added to the PowerPC boot wrapper (``arch/powerpc/boot/*``) so that
>  a dtb could be wrapped up with the kernel image to support booting
>  existing non-DT aware firmware.
>  
> @@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support.
>  
>  2. Data Model
>  -------------
> -If you haven't already read the Device Tree Usage[1] page,
> +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
> @@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware
>  with a single kernel image.
>  
>  Linux uses DT data for three major purposes:
> +
>  1) platform identification,
>  2) runtime configuration, and
>  3) device population.
> @@ -117,7 +122,7 @@ The 'compatible' property contains a sorted list of strings starting
>  with the exact name of the machine, followed by an optional list of
>  boards it is compatible with sorted from most compatible to least.  For
>  example, the root compatible properties for the TI BeagleBoard and its
> -successor, the BeagleBoard xM board might look like, respectively:
> +successor, the BeagleBoard xM board might look like, respectively::
>  
>  	compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
>  	compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";
> @@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location
>  of an initrd image.
>  
>  Most of this data is contained in the /chosen node, and when booting
> -Linux it will look something like this:
> +Linux it will look something like this::
>  
>  	chosen {
>  		bootargs = "console=ttyS0,115200 loglevel=8";
> @@ -251,9 +256,9 @@ platform devices roughly correspond to device nodes at the root of the
>  tree and children of simple memory mapped bus nodes.
>  
>  About now is a good time to lay out an example.  Here is part of the
> -device tree for the NVIDIA Tegra board.
> +device tree for the NVIDIA Tegra board::
>  
> -/{
> +  /{
>  	compatible = "nvidia,harmony", "nvidia,tegra20";
>  	#address-cells = <1>;
>  	#size-cells = <1>;
> @@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board.
>  		i2s-controller = <&i2s1>;
>  		i2s-codec = <&wm8903>;
>  	};
> -};
> +  };
>  
>  At .init_machine() time, Tegra board support code will need to look at
>  this DT and decide which nodes to create platform_devices for.
> @@ -379,13 +384,13 @@ device tree support code reflects that and makes the above example
>  simpler.  The second argument to of_platform_populate() is an
>  of_device_id table, and any node that matches an entry in that table
>  will also get its child nodes registered.  In the Tegra case, the code
> -can look something like this:
> +can look something like this::
>  
> -static void __init harmony_init_machine(void)
> -{
> +  static void __init harmony_init_machine(void)
> +  {
>  	/* ... */
>  	of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL);
> -}
> +  }
>  
>  "simple-bus" is defined in the Devicetree Specification as a property
>  meaning a simple memory mapped bus, so the of_platform_populate() code
> diff --git a/include/linux/mfd/core.h b/include/linux/mfd/core.h
> index d01d1299e49d..21718c8b2b48 100644
> --- a/include/linux/mfd/core.h
> +++ b/include/linux/mfd/core.h
> @@ -74,7 +74,7 @@ struct mfd_cell {
>  
>  	/*
>  	 * Device Tree compatible string
> -	 * See: Documentation/devicetree/usage-model.txt Chapter 2.2 for details
> +	 * See: Documentation/devicetree/usage-model.rst Chapter 2.2 for details
>  	 */
>  	const char		*of_compatible;
>  
> 

Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST

[Mauro Carvalho Chehab]

Em Mon, 2 Mar 2020 15:18:51 -0600
Frank Rowand <frowand.list@gmail.com> escreveu:

> On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> > - Add a SPDX header;
> > - Adjust document title;
> > - Use footnoote 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 +
> >  Documentation/devicetree/of_unittest.txt      |  2 +-
> >  .../{usage-model.txt => usage-model.rst}      | 35 +++++++++++--------
> >  include/linux/mfd/core.h                      |  2 +-
> >  4 files changed, 23 insertions(+), 17 deletions(-)
> >  rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)
> > 
> > diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> > index a11efe26f205..7a6aad7d384a 100644
> > --- a/Documentation/devicetree/index.rst
> > +++ b/Documentation/devicetree/index.rst
> > @@ -7,4 +7,5 @@ Open Firmware and Device Tree
> >  .. toctree::
> >     :maxdepth: 1
> >  
> > +   usage-model
> >     writing-schema
> > diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt
> > index 3e4e7d48ae93..9fdd2de9b770 100644
> > --- a/Documentation/devicetree/of_unittest.txt
> > +++ b/Documentation/devicetree/of_unittest.txt
> > @@ -11,7 +11,7 @@ architecture.
> >  
> >  It is recommended to read the following documents before moving ahead.
> >  
> > -[1] Documentation/devicetree/usage-model.txt
> > +[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)
> > diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.rst
> > similarity index 97%
> > rename from Documentation/devicetree/usage-model.txt
> > rename to Documentation/devicetree/usage-model.rst
> > index 33a8aaac02a8..326d7af10c5b 100644
> > --- a/Documentation/devicetree/usage-model.txt
> > +++ b/Documentation/devicetree/usage-model.rst
> > @@ -1,14 +1,18 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=========================
> >  Linux and the Device Tree
> > --------------------------
> > +=========================
> > +
> >  The Linux usage model for device tree data
> >  
> > -Author: Grant Likely <grant.likely@secretlab.ca>
> > +:Author: Grant Likely <grant.likely@secretlab.ca>
> >  
> >  This article describes how Linux uses the device tree.  An overview of
> >  the device tree data format can be found on the device tree usage page
> > -at devicetree.org[1].
> > +at devicetree.org\ [1]_.
> >  
> > -[1] http://devicetree.org/Device_Tree_Usage
> > +.. [1] http://devicetree.org/Device_Tree_Usage  
> 
> I don't know the proper ReST syntax for footnotes, but on the html page
> you kindly provided in 00/12, '.. [1]' is shown as '1(1,2)'.
> 
> -Frank

The syntax is simple: just add an  underline at the end, when referencing
it, like [1]_. The definitions should start with "..", like ".. [1] something".

Sphinx will automatically generate the reverse reference(s) at the html output.

Yet, sometimes (like the above), it needs to be escaped by a "\ ", as ReST would
recognize "foo[1]_" as something else.

Ps.: it also accepts an "auto-numbered" references like [#]_, but such syntax
require some care, in order to avoid wrong cross-references.

Regards,
Mauro

[PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage

[Mauro Carvalho Chehab]

The devicetree.org doesn't host the Device_Tree_Usage page
anymore. So, fix the link to point to a new address.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/devicetree/usage-model.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
index 326d7af10c5b..e1b42dc63f01 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -12,7 +12,7 @@ This article describes how Linux uses the device tree.  An overview of
 the device tree data format can be found on the device tree usage page
 at devicetree.org\ [1]_.
 
-.. [1] http://devicetree.org/Device_Tree_Usage
+.. [1] https://elinux.org/Device_Tree_Usage
 
 The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
 structure and language for describing hardware.  More specifically, it
-- 
2.21.1

Re: [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage

[Frank Rowand]

On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> The devicetree.org doesn't host the Device_Tree_Usage page
> anymore. So, fix the link to point to a new address.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/devicetree/usage-model.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
> index 326d7af10c5b..e1b42dc63f01 100644
> --- a/Documentation/devicetree/usage-model.rst
> +++ b/Documentation/devicetree/usage-model.rst
> @@ -12,7 +12,7 @@ This article describes how Linux uses the device tree.  An overview of
>  the device tree data format can be found on the device tree usage page
>  at devicetree.org\ [1]_.

s/devicetree.org/elinux.org/


>  
> -.. [1] http://devicetree.org/Device_Tree_Usage
> +.. [1] https://elinux.org/Device_Tree_Usage
>  
>  The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
>  structure and language for describing hardware.  More specifically, it
> 

Re: [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage

[Rob Herring]

On Mon, Mar 2, 2020 at 3:11 PM Frank Rowand <frowand.list@gmail.com> wrote:
>
> On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> > The devicetree.org doesn't host the Device_Tree_Usage page
> > anymore. So, fix the link to point to a new address.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/devicetree/usage-model.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
> > index 326d7af10c5b..e1b42dc63f01 100644
> > --- a/Documentation/devicetree/usage-model.rst
> > +++ b/Documentation/devicetree/usage-model.rst
> > @@ -12,7 +12,7 @@ This article describes how Linux uses the device tree.  An overview of
> >  the device tree data format can be found on the device tree usage page
> >  at devicetree.org\ [1]_.
>
> s/devicetree.org/elinux.org/

I wonder if we should make the devicetree.org link work again instead.
Primarily just to avoid the appearance of it being Linux specific.

The website is hosted on github[1] and I'd assume there's a way to do
redirects as a start.

Rob

[1] https://github.com/devicetree-org/devicetree-website

Re: [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage

[Mauro Carvalho Chehab]

Em Mon, 2 Mar 2020 15:40:37 -0600
Rob Herring <robh+dt@kernel.org> escreveu:

> On Mon, Mar 2, 2020 at 3:11 PM Frank Rowand <frowand.list@gmail.com> wrote:
> >
> > On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:  
> > > The devicetree.org doesn't host the Device_Tree_Usage page
> > > anymore. So, fix the link to point to a new address.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > > ---
> > >  Documentation/devicetree/usage-model.rst | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > >
> > > diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
> > > index 326d7af10c5b..e1b42dc63f01 100644
> > > --- a/Documentation/devicetree/usage-model.rst
> > > +++ b/Documentation/devicetree/usage-model.rst
> > > @@ -12,7 +12,7 @@ This article describes how Linux uses the device tree.  An overview of
> > >  the device tree data format can be found on the device tree usage page
> > >  at devicetree.org\ [1]_.  
> >
> > s/devicetree.org/elinux.org/  
> 
> I wonder if we should make the devicetree.org link work again instead.
> Primarily just to avoid the appearance of it being Linux specific.

Makes sense to me. Another alternative would be to convert this file to
ReST and add to the Kernel docs (it should be easy to convert with pandoc).

Yet, as those references are part of the Linux Kernel documentation, it 
doesn't sound wrong to me to have them pointing to a linux-specific site.

In any case, I'll update this patch, placing all such changes altogether.
This way, if you decide to re-add this at devicetree.org, we could simply
drop (or revert) it.

> 
> The website is hosted on github[1] and I'd assume there's a way to do
> redirects as a start.
> 
> Rob
> 
> [1] https://github.com/devicetree-org/devicetree-website

[PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Use copyright symbol;
- Adjust document title;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to devicetree/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/arm/booting.rst                 |   2 +-
 ...-without-of.txt => booting-without-of.rst} | 299 ++++++++++--------
 Documentation/devicetree/index.rst            |   1 +
 Documentation/translations/zh_CN/arm/Booting  |   2 +-
 4 files changed, 169 insertions(+), 135 deletions(-)
 rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%)

diff --git a/Documentation/arm/booting.rst b/Documentation/arm/booting.rst
index 4babb6c6ae1e..a2263451dc2c 100644
--- a/Documentation/arm/booting.rst
+++ b/Documentation/arm/booting.rst
@@ -128,7 +128,7 @@ it.  The recommended placement is in the first 16KiB of RAM.
 
 The boot loader must load a device tree image (dtb) into system ram
 at a 64bit aligned address and initialize it with the boot data.  The
-dtb format is documented in Documentation/devicetree/booting-without-of.txt.
+dtb format is documented in Documentation/devicetree/booting-without-of.rst.
 The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
 physical address to determine if a dtb has been passed instead of a
 tagged list.
diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.rst
similarity index 90%
rename from Documentation/devicetree/booting-without-of.txt
rename to Documentation/devicetree/booting-without-of.rst
index 4660ccee35a3..56e54e95efa7 100644
--- a/Documentation/devicetree/booting-without-of.txt
+++ b/Documentation/devicetree/booting-without-of.rst
@@ -1,15 +1,20 @@
-           Booting the Linux/ppc kernel without Open Firmware
-           --------------------------------------------------
-
-(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
-    IBM Corp.
-(c) 2005 Becky Bruce <becky.bruce at freescale.com>,
-    Freescale Semiconductor, FSL SOC and 32-bit additions
-(c) 2006 MontaVista Software, Inc.
-    Flash chip node definition
-
-Table of Contents
-=================
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+==================================================
+Booting the Linux/ppc kernel without Open Firmware
+==================================================
+
+Copyright |copy| 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
+IBM Corp.
+
+Copyright |copy| 2005 Becky Bruce <becky.bruce at freescale.com>,
+Freescale Semiconductor, FSL SOC and 32-bit additions
+
+Copyright |copy| 2006 MontaVista Software, Inc.
+Flash chip node definition
+
+.. Table of Contents
 
   I - Introduction
     1) Entry point for arch/arm
@@ -61,15 +66,18 @@ Table of Contents
 Revision Information
 ====================
 
-   May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
+   May 18, 2005: Rev 0.1
+			 - Initial draft, no chapter III yet.
 
-   May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
+   May 19, 2005: Rev 0.2
+			 - Add chapter III and bits & pieces here or
                            clarifies the fact that a lot of things are
                            optional, the kernel only requires a very
                            small device tree, though it is encouraged
                            to provide an as complete one as possible.
 
-   May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
+   May 24, 2005: Rev 0.3
+			 - Precise that DT block has to be in RAM
 			 - Misc fixes
 			 - Define version 3 and new format version 16
 			   for the DT block (version 16 needs kernel
@@ -82,7 +90,8 @@ Revision Information
 			   "name" property is now automatically
 			   deduced from the unit name
 
-   June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
+   June 1, 2005: Rev 0.4
+			 - Correct confusion between OF_DT_END and
                            OF_DT_END_NODE in structure definition.
                          - Change version 16 format to always align
                            property data to 4 bytes. Since tokens are
@@ -115,7 +124,7 @@ Revision Information
 	- Compare FSL SOC use of PCI to standard and make sure no new
 	  node definition required.
 	- Add more information about node definitions for SOC devices
-  	  that currently have no standard, like the FSL CPM.
+	  that currently have no standard, like the FSL CPM.
 
 
 I - Introduction
@@ -260,7 +269,7 @@ it with special cases.
 
         b) create your main platform file as
         "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
-        to the Makefile under the condition of your CONFIG_
+        to the Makefile under the condition of your ``CONFIG_``
         option. This file will define a structure of type "ppc_md"
         containing the various callbacks that the generic code will
         use to get to your platform specific code
@@ -271,7 +280,7 @@ it with special cases.
   with classic Powerpc architectures.
 
 3) Entry point for arch/x86
--------------------------------
+---------------------------
 
   There is one single 32bit entry point to the kernel at code32_start,
   the decompressor (the real mode entry point goes to the same  32bit
@@ -280,9 +289,9 @@ it with special cases.
   Documentation/x86/boot.rst
   The physical pointer to the device-tree block (defined in chapter II)
   is passed via setup_data which requires at least boot protocol 2.09.
-  The type filed is defined as
+  The type filed is defined as::
 
-  #define SETUP_DTB                      2
+    #define SETUP_DTB                      2
 
   This device-tree is used as an extension to the "boot page". As such it
   does not parse / consider data which is already covered by the boot
@@ -354,9 +363,9 @@ the block to RAM before passing it to the kernel.
 
    The kernel is passed the physical address pointing to an area of memory
    that is roughly described in include/linux/of_fdt.h by the structure
-   boot_param_header:
+   boot_param_header:::
 
-struct boot_param_header {
+      struct boot_param_header {
         u32     magic;                  /* magic word OF_DT_HEADER */
         u32     totalsize;              /* total size of DT block */
         u32     off_dt_struct;          /* offset to structure */
@@ -374,19 +383,19 @@ struct boot_param_header {
 
         /* version 17 fields below */
         u32	size_dt_struct;		/* size of the DT structure block */
-};
+      };
 
-   Along with the constants:
+   Along with the constants::
 
-/* Definitions used by the flattened device tree */
-#define OF_DT_HEADER            0xd00dfeed      /* 4: version,
-						   4: total size */
-#define OF_DT_BEGIN_NODE        0x1             /* Start node: full name
-						   */
-#define OF_DT_END_NODE          0x2             /* End node */
-#define OF_DT_PROP              0x3             /* Property: name off,
-                                                   size, content */
-#define OF_DT_END               0x9
+    /* Definitions used by the flattened device tree */
+    #define OF_DT_HEADER            0xd00dfeed      /* 4: version,
+						    4: total size */
+    #define OF_DT_BEGIN_NODE        0x1             /* Start node: full name
+						    */
+    #define OF_DT_END_NODE          0x2             /* End node */
+    #define OF_DT_PROP              0x3             /* Property: name off,
+						    size, content */
+    #define OF_DT_END               0x9
 
    All values in this header are in big endian format, the various
    fields in this header are defined more precisely below. All
@@ -430,7 +439,7 @@ struct boot_param_header {
      way to avoid overriding critical things like, on Open Firmware
      capable machines, the RTAS instance, or on some pSeries, the TCE
      tables used for the iommu. Typically, the reserve map should
-     contain _at least_ this DT block itself (header,total_size). If
+     contain **at least** this DT block itself (header,total_size). If
      you are passing an initrd to the kernel, you should reserve it as
      well. You do not need to reserve the kernel image itself. The map
      should be 64-bit aligned.
@@ -485,7 +494,7 @@ struct boot_param_header {
 
    So the typical layout of a DT block (though the various parts don't
    need to be in that order) looks like this (addresses go from top to
-   bottom):
+   bottom)::
 
 
              ------------------------------
@@ -511,9 +520,9 @@ struct boot_param_header {
       |
       --- (base + totalsize)
 
-  (*) The alignment gaps are not necessarily present; their presence
-      and size are dependent on the various alignment requirements of
-      the individual data blocks.
+     (*) The alignment gaps are not necessarily present; their presence
+         and size are dependent on the various alignment requirements of
+         the individual data blocks.
 
 
 2) Device tree generalities
@@ -600,7 +609,7 @@ discussed in a later chapter. At this point, it is only meant to give
 you a idea of what a device-tree looks like. I have purposefully kept
 the "name" and "linux,phandle" properties which aren't necessary in
 order to give you a better idea of what the tree looks like in
-practice.
+practice::
 
   / o device-tree
       |- name = "device-tree"
@@ -650,6 +659,7 @@ properties and their content.
 
 
 3) Device tree "structure" block
+--------------------------------
 
 The structure of the device tree is a linearized tree structure. The
 "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
@@ -666,12 +676,14 @@ Here's the basic structure of a single node:
        root node)
      * [align gap to next 4 bytes boundary]
      * for each property:
+
         * token OF_DT_PROP (that is 0x00000003)
         * 32-bit value of property value size in bytes (or 0 if no
           value)
         * 32-bit value of offset in string block of property name
         * property value data if any
         * [align gap to next 4 bytes boundary]
+
      * [child nodes if any]
      * token OF_DT_END_NODE (that is 0x00000002)
 
@@ -688,6 +700,7 @@ manipulating a flattened tree must take care to preserve this
 constraint.
 
 4) Device tree "strings" block
+------------------------------
 
 In order to save space, property names, which are generally redundant,
 are stored separately in the "strings" block. This block is simply the
@@ -700,15 +713,17 @@ strings block.
 III - Required content of the device tree
 =========================================
 
-WARNING: All "linux,*" properties defined in this document apply only
-to a flattened device-tree. If your platform uses a real
-implementation of Open Firmware or an implementation compatible with
-the Open Firmware client interface, those properties will be created
-by the trampoline code in the kernel's prom_init() file. For example,
-that's where you'll have to add code to detect your board model and
-set the platform number. However, when using the flattened device-tree
-entry point, there is no prom_init() pass, and thus you have to
-provide those properties yourself.
+.. Warning::
+
+   All ``linux,*`` properties defined in this document apply only
+   to a flattened device-tree. If your platform uses a real
+   implementation of Open Firmware or an implementation compatible with
+   the Open Firmware client interface, those properties will be created
+   by the trampoline code in the kernel's prom_init() file. For example,
+   that's where you'll have to add code to detect your board model and
+   set the platform number. However, when using the flattened device-tree
+   entry point, there is no prom_init() pass, and thus you have to
+   provide those properties yourself.
 
 
 1) Note about cells and address representation
@@ -769,7 +784,7 @@ addresses), all buses must contain a "ranges" property. If the
 "ranges" property is missing at a given level, it's assumed that
 translation isn't possible, i.e., the registers are not visible on the
 parent bus.  The format of the "ranges" property for a bus is a list
-of:
+of::
 
 	bus address, parent bus address, size
 
@@ -877,7 +892,7 @@ address which can extend beyond that limit.
 
   This node is the parent of all individual CPU nodes. It doesn't
   have any specific requirements, though it's generally good practice
-  to have at least:
+  to have at least::
 
                #address-cells = <00000001>
                #size-cells    = <00000000>
@@ -887,7 +902,7 @@ address which can extend beyond that limit.
   that format when reading the "reg" properties of a CPU node, see
   below
 
-  c) The /cpus/* nodes
+  c) The ``/cpus/*`` nodes
 
   So under /cpus, you are supposed to create a node for every CPU on
   the machine. There is no specific restriction on the name of the
@@ -903,21 +918,23 @@ address which can extend beyond that limit.
     - reg : This is the physical CPU number, it's a single 32-bit cell
       and is also used as-is as the unit number for constructing the
       unit name in the full path. For example, with 2 CPUs, you would
-      have the full path:
+      have the full path::
+
         /cpus/PowerPC,970FX@0
         /cpus/PowerPC,970FX@1
+
       (unit addresses do not require leading zeroes)
-    - d-cache-block-size : one cell, L1 data cache block size in bytes (*)
+    - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_
     - i-cache-block-size : one cell, L1 instruction cache block size in
       bytes
     - d-cache-size : one cell, size of L1 data cache in bytes
     - i-cache-size : one cell, size of L1 instruction cache in bytes
 
-(*) The cache "block" size is the size on which the cache management
-instructions operate. Historically, this document used the cache
-"line" size here which is incorrect. The kernel will prefer the cache
-block size and will fallback to cache line size for backward
-compatibility.
+    .. [#] The cache "block" size is the size on which the cache management
+	   instructions operate. Historically, this document used the cache
+	   "line" size here which is incorrect. The kernel will prefer the cache
+	   block size and will fallback to cache line size for backward
+	   compatibility.
 
   Recommended properties:
 
@@ -963,10 +980,10 @@ compatibility.
       #address-cells and #size-cells of the root node. For example,
       with both of these properties being 2 like in the example given
       earlier, a 970 based machine with 6Gb of RAM could typically
-      have a "reg" property here that looks like:
+      have a "reg" property here that looks like::
 
-      00000000 00000000 00000000 80000000
-      00000001 00000000 00000001 00000000
+        00000000 00000000 00000000 80000000
+        00000001 00000000 00000001 00000000
 
       That is a range starting at 0 of 0x80000000 bytes and a range
       starting at 0x100000000 and of 0x100000000 bytes. You can see
@@ -1047,18 +1064,18 @@ compatibility.
       See 1) above for more details on defining #address-cells.
     - #size-cells : Size representation for "soc" devices
     - #interrupt-cells : Defines the width of cells used to represent
-       interrupts.  Typically this value is <2>, which includes a
-       32-bit number that represents the interrupt number, and a
-       32-bit number that represents the interrupt sense and level.
-       This field is only needed if the SOC contains an interrupt
-       controller.
+      interrupts.  Typically this value is <2>, which includes a
+      32-bit number that represents the interrupt number, and a
+      32-bit number that represents the interrupt sense and level.
+      This field is only needed if the SOC contains an interrupt
+      controller.
 
   The SOC node may contain child nodes for each SOC device that the
   platform uses.  Nodes should not be created for devices which exist
   on the SOC but are not used by a particular platform. See chapter VI
   for more information on how to specify devices that are part of a SOC.
 
-  Example SOC node for the MPC8540:
+  Example SOC node for the MPC8540::
 
 	soc8540@e0000000 {
 		#address-cells = <1>;
@@ -1079,31 +1096,33 @@ IV - "dtc", the device tree compiler
 dtc source code can be found at
 <http://git.jdl.com/gitweb/?p=dtc.git>
 
-WARNING: This version is still in early development stage; the
-resulting device-tree "blobs" have not yet been validated with the
-kernel. The current generated block lacks a useful reserve map (it will
-be fixed to generate an empty one, it's up to the bootloader to fill
-it up) among others. The error handling needs work, bugs are lurking,
-etc...
+.. Warning::
+
+   This version is still in early development stage; the
+   resulting device-tree "blobs" have not yet been validated with the
+   kernel. The current generated block lacks a useful reserve map (it will
+   be fixed to generate an empty one, it's up to the bootloader to fill
+   it up) among others. The error handling needs work, bugs are lurking,
+   etc...
 
 dtc basically takes a device-tree in a given format and outputs a
 device-tree in another format. The currently supported formats are:
 
-  Input formats:
-  -------------
+Input formats
+-------------
 
      - "dtb": "blob" format, that is a flattened device-tree block
        with
-        header all in a binary blob.
+       header all in a binary blob.
      - "dts": "source" format. This is a text file containing a
        "source" for a device-tree. The format is defined later in this
-        chapter.
+       chapter.
      - "fs" format. This is a representation equivalent to the
-        output of /proc/device-tree, that is nodes are directories and
-	properties are files
+       output of /proc/device-tree, that is nodes are directories and
+       properties are files
 
- Output formats:
- ---------------
+Output formats
+--------------
 
      - "dtb": "blob" format
      - "dts": "source" format
@@ -1113,7 +1132,7 @@ device-tree in another format. The currently supported formats are:
        assembly file exports some symbols that can be used.
 
 
-The syntax of the dtc tool is
+The syntax of the dtc tool is::
 
     dtc [-I <input-format>] [-O <output-format>]
         [-o output-filename] [-V output_version] input_filename
@@ -1127,43 +1146,45 @@ Additionally, dtc performs various sanity checks on the tree, like the
 uniqueness of linux, phandle properties, validity of strings, etc...
 
 The format of the .dts "source" file is "C" like, supports C and C++
-style comments.
+style comments::
 
-/ {
-}
+    / {
+    }
 
 The above is the "device-tree" definition. It's the only statement
 supported currently at the toplevel.
 
-/ {
-  property1 = "string_value";	/* define a property containing a 0
-                                 * terminated string
-				 */
+::
 
-  property2 = <0x1234abcd>;	/* define a property containing a
-                                 * numerical 32-bit value (hexadecimal)
-				 */
+  / {
+    property1 = "string_value";	   /* define a property containing a 0
+				    * terminated string
+				    */
 
-  property3 = <0x12345678 0x12345678 0xdeadbeef>;
-                                /* define a property containing 3
-                                 * numerical 32-bit values (cells) in
-                                 * hexadecimal
-				 */
-  property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef];
-                                /* define a property whose content is
-                                 * an arbitrary array of bytes
-                                 */
+    property2 = <0x1234abcd>;	   /* define a property containing a
+				    * numerical 32-bit value (hexadecimal)
+				    */
 
-  childnode@address {	/* define a child node named "childnode"
-                                 * whose unit name is "childnode at
-				 * address"
-                                 */
+    property3 = <0x12345678 0x12345678 0xdeadbeef>;
+				   /* define a property containing 3
+				    * numerical 32-bit values (cells) in
+				    * hexadecimal
+				    */
+    property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef];
+				   /* define a property whose content is
+				    * an arbitrary array of bytes
+				    */
 
-    childprop = "hello\n";      /* define a property "childprop" of
-                                 * childnode (in this case, a string)
-                                 */
-  };
-};
+    childnode@address {		   /* define a child node named "childnode"
+				    * whose unit name is "childnode at
+				    * address"
+				    */
+
+	childprop = "hello\n";	       /* define a property "childprop" of
+					* childnode (in this case, a string)
+					*/
+	};
+    };
 
 Nodes can contain other nodes etc... thus defining the hierarchical
 structure of the tree.
@@ -1322,7 +1343,7 @@ phandle of the parent node.
 
 If the interrupt-parent property is not defined for a node, its
 interrupt parent is assumed to be an ancestor in the node's
-_device tree_ hierarchy.
+*device tree* hierarchy.
 
 3) OpenPIC Interrupt Controllers
 --------------------------------
@@ -1334,10 +1355,12 @@ information.
 
 Sense and level information should be encoded as follows:
 
-	0 = low to high edge sensitive type enabled
-	1 = active low level sensitive type enabled
-	2 = active high level sensitive type enabled
-	3 = high to low edge sensitive type enabled
+	==  ========================================
+	0   low to high edge sensitive type enabled
+	1   active low level sensitive type enabled
+	2   active high level sensitive type enabled
+	3   high to low edge sensitive type enabled
+	==  ========================================
 
 4) ISA Interrupt Controllers
 ----------------------------
@@ -1350,13 +1373,15 @@ information.
 ISA PIC interrupt controllers should adhere to the ISA PIC
 encodings listed below:
 
-	0 =  active low level sensitive type enabled
-	1 =  active high level sensitive type enabled
-	2 =  high to low edge sensitive type enabled
-	3 =  low to high edge sensitive type enabled
+	==  ========================================
+	0   active low level sensitive type enabled
+	1   active high level sensitive type enabled
+	2   high to low edge sensitive type enabled
+	3   low to high edge sensitive type enabled
+	==  ========================================
 
 VIII - Specifying Device Power Management Information (sleep property)
-===================================================================
+======================================================================
 
 Devices on SOCs often have mechanisms for placing devices into low-power
 states that are decoupled from the devices' own register blocks.  Sometimes,
@@ -1387,6 +1412,7 @@ reasonably grouped in this manner, then create a virtual sleep controller
 sleep-map should wait until its necessity is demonstrated).
 
 IX - Specifying dma bus information
+===================================
 
 Some devices may have DMA memory range shifted relatively to the beginning of
 RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC
@@ -1404,25 +1430,30 @@ coherent DMA operations. The "dma-coherent" property is intended to be used
 for identifying devices supported coherent DMA operations in DT.
 
 * DMA Bus master
+
 Optional property:
+
 - dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of
-	(child-bus-address, parent-bus-address, length). Each triplet specified
-	describes a contiguous DMA address range.
-	The dma-ranges property is used to describe the direct memory access (DMA)
-	structure of a memory-mapped bus whose device tree parent can be accessed
-	from DMA operations originating from the bus. It provides a means of
-	defining a mapping or translation between the physical address space of
-	the bus and the physical address space of the parent of the bus.
-	(for more information see the Devicetree Specification)
+  (child-bus-address, parent-bus-address, length). Each triplet specified
+  describes a contiguous DMA address range.
+  The dma-ranges property is used to describe the direct memory access (DMA)
+  structure of a memory-mapped bus whose device tree parent can be accessed
+  from DMA operations originating from the bus. It provides a means of
+  defining a mapping or translation between the physical address space of
+  the bus and the physical address space of the parent of the bus.
+  (for more information see the Devicetree Specification)
 
 * DMA Bus child
+
 Optional property:
+
 - dma-ranges: <empty> value. if present - It means that DMA addresses
-	translation has to be enabled for this device.
+  translation has to be enabled for this device.
 - dma-coherent: Present if dma operations are coherent
 
-Example:
-soc {
+Example::
+
+	soc {
 		compatible = "ti,keystone","simple-bus";
 		ranges = <0x0 0x0 0x0 0xc0000000>;
 		dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>;
@@ -1435,11 +1466,13 @@ soc {
 			[...]
 			dma-coherent;
 		};
-};
+	};
 
 Appendix A - Sample SOC node for MPC8540
 ========================================
 
+::
+
 	soc@e0000000 {
 		#address-cells = <1>;
 		#size-cells = <1>;
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 7a6aad7d384a..6b4daf252375 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -9,3 +9,4 @@ Open Firmware and Device Tree
 
    usage-model
    writing-schema
+   booting-without-of
diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting
index 562e9a2957e6..c3d26ce5f6de 100644
--- a/Documentation/translations/zh_CN/arm/Booting
+++ b/Documentation/translations/zh_CN/arm/Booting
@@ -124,7 +124,7 @@ bootloader 必须传递一个系统内存的位置和最小值，以及根文件
 
 bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统
 RAM 中，并用启动数据初始化它。dtb 格式在文档
-Documentation/devicetree/booting-without-of.txt 中。内核将会在
+Documentation/devicetree/booting-without-of.rst 中。内核将会在
 dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替
 标签列表被传递进来。
 
-- 
2.21.1

Re: [PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format

[Rob Herring]

On Mon, Mar 2, 2020 at 1:59 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> - Add a SPDX header;
> - Use copyright symbol;
> - Adjust document title;
> - Adjust document and section titles;
> - Some whitespace fixes and new line breaks;
> - Mark literal blocks as such;
> - Add table markups;
> - Add it to devicetree/index.rst.

Let's skip this doc. It's been on my todo to remove it. It's pretty
stale and 15 years old. Much of this document is now covered by what's
in the DT spec. There's a few pieces that aren't which we need to find
new homes for.

> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/arm/booting.rst                 |   2 +-
>  ...-without-of.txt => booting-without-of.rst} | 299 ++++++++++--------
>  Documentation/devicetree/index.rst            |   1 +
>  Documentation/translations/zh_CN/arm/Booting  |   2 +-
>  4 files changed, 169 insertions(+), 135 deletions(-)
>  rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%)

Re: [PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format

[Alex Shi]

在 2020/3/5 上午2:25, Rob Herring 写道:
> Let's skip this doc. It's been on my todo to remove it. It's pretty
> stale and 15 years old. Much of this document is now covered by what's
> in the DT spec. There's a few pieces that aren't which we need to find
> new homes for.
> 

Happy to see a old doc getting update! :)

[PATCH v2 05/12] docs: dt: convert changesets to ReST

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Add it to devicetree/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../{changesets.txt => changesets.rst}        | 24 ++++++++++++-------
 Documentation/devicetree/index.rst            |  1 +
 2 files changed, 16 insertions(+), 9 deletions(-)
 rename Documentation/devicetree/{changesets.txt => changesets.rst} (59%)

diff --git a/Documentation/devicetree/changesets.txt b/Documentation/devicetree/changesets.rst
similarity index 59%
rename from Documentation/devicetree/changesets.txt
rename to Documentation/devicetree/changesets.rst
index cb488eeb6353..c7fd8cd6a270 100644
--- a/Documentation/devicetree/changesets.txt
+++ b/Documentation/devicetree/changesets.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+DT Changesets
+=============
+
 A DT changeset is a method which allows one to apply changes
 in the live tree in such a way that either the full set of changes
 will be applied, or none of them will be. If an error occurs partway
@@ -15,17 +21,17 @@ The sequence of a changeset is as follows.
 1. of_changeset_init() - initializes a changeset
 
 2. A number of DT tree change calls, of_changeset_attach_node(),
-of_changeset_detach_node(), of_changeset_add_property(),
-of_changeset_remove_property, of_changeset_update_property() to prepare
-a set of changes. No changes to the active tree are made at this point.
-All the change operations are recorded in the of_changeset 'entries'
-list.
+   of_changeset_detach_node(), of_changeset_add_property(),
+   of_changeset_remove_property, of_changeset_update_property() to prepare
+   a set of changes. No changes to the active tree are made at this point.
+   All the change operations are recorded in the of_changeset 'entries'
+   list.
 
 3. of_changeset_apply() - Apply the changes to the tree. Either the
-entire changeset will get applied, or if there is an error the tree will
-be restored to the previous state. The core ensures proper serialization
-through locking. An unlocked version __of_changeset_apply is available,
-if needed.
+   entire changeset will get applied, or if there is an error the tree will
+   be restored to the previous state. The core ensures proper serialization
+   through locking. An unlocked version __of_changeset_apply is available,
+   if needed.
 
 If a successfully applied changeset needs to be removed, it can be done
 with of_changeset_revert().
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 6b4daf252375..64c78c3ffea6 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -10,3 +10,4 @@ Open Firmware and Device Tree
    usage-model
    writing-schema
    booting-without-of
+   changesets
-- 
2.21.1

[PATCH v2 06/12] docs: dt: convert dynamic-resolution-notes.txt to ReST

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Adjust document title;
- Add it to devicetree/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 ...mic-resolution-notes.txt => dynamic-resolution-notes.rst} | 5 ++++-
 Documentation/devicetree/index.rst                           | 1 +
 Documentation/devicetree/overlay-notes.txt                   | 2 +-
 MAINTAINERS                                                  | 2 +-
 4 files changed, 7 insertions(+), 3 deletions(-)
 rename Documentation/devicetree/{dynamic-resolution-notes.txt => dynamic-resolution-notes.rst} (90%)

diff --git a/Documentation/devicetree/dynamic-resolution-notes.txt b/Documentation/devicetree/dynamic-resolution-notes.rst
similarity index 90%
rename from Documentation/devicetree/dynamic-resolution-notes.txt
rename to Documentation/devicetree/dynamic-resolution-notes.rst
index c24ec366c5dc..570b7e1f39eb 100644
--- a/Documentation/devicetree/dynamic-resolution-notes.txt
+++ b/Documentation/devicetree/dynamic-resolution-notes.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
 Device Tree Dynamic Resolver Notes
-----------------------------------
+==================================
 
 This document describes the implementation of the in-kernel
 Device Tree resolver, residing in drivers/of/resolver.c
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 64c78c3ffea6..308cac9d7021 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -11,3 +11,4 @@ Open Firmware and Device Tree
    writing-schema
    booting-without-of
    changesets
+   dynamic-resolution-notes
diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt
index 725fb8d255c1..3f20a39e4bc2 100644
--- a/Documentation/devicetree/overlay-notes.txt
+++ b/Documentation/devicetree/overlay-notes.txt
@@ -3,7 +3,7 @@ Device Tree Overlay Notes
 
 This document describes the implementation of the in-kernel
 device tree overlay functionality residing in drivers/of/overlay.c and is a
-companion document to Documentation/devicetree/dynamic-resolution-notes.txt[1]
+companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1]
 
 How overlays work
 -----------------
diff --git a/MAINTAINERS b/MAINTAINERS
index 09b04505e7c3..1380b1ed69a2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12458,7 +12458,7 @@ M:	Pantelis Antoniou <pantelis.antoniou@konsulko.com>
 M:	Frank Rowand <frowand.list@gmail.com>
 L:	devicetree@vger.kernel.org
 S:	Maintained
-F:	Documentation/devicetree/dynamic-resolution-notes.txt
+F:	Documentation/devicetree/dynamic-resolution-notes.rst
 F:	Documentation/devicetree/overlay-notes.txt
 F:	drivers/of/overlay.c
 F:	drivers/of/resolver.c
-- 
2.21.1

[PATCH v2 07/12] docs: dt: convert of_unittest.txt to ReST

[Mauro Carvalho Chehab]

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

Re: [PATCH v2 07/12] docs: dt: convert of_unittest.txt to ReST

[Frank Rowand]

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
> 

Re: [PATCH v2 07/12] docs: dt: convert of_unittest.txt to ReST

[Mauro Carvalho Chehab]

Em Mon, 2 Mar 2020 15:11:42 -0600
Frank Rowand <frowand.list@gmail.com> escreveu:

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

Thanks for noticing. I'll move patch 03/12 to the end and fix all those
references altogether there.

Regards,
Mauro

[PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Adjust document title;
- 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 +
 .../{overlay-notes.txt => overlay-notes.rst}  | 141 +++++++++---------
 MAINTAINERS                                   |   2 +-
 3 files changed, 74 insertions(+), 70 deletions(-)
 rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%)

diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index ca83258fbba5..0669a53fc617 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -13,3 +13,4 @@ Open Firmware and Device Tree
    changesets
    dynamic-resolution-notes
    of_unittest
+   overlay-notes
diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.rst
similarity index 56%
rename from Documentation/devicetree/overlay-notes.txt
rename to Documentation/devicetree/overlay-notes.rst
index 3f20a39e4bc2..7e8e568f64a8 100644
--- a/Documentation/devicetree/overlay-notes.txt
+++ b/Documentation/devicetree/overlay-notes.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
 Device Tree Overlay Notes
--------------------------
+=========================
 
 This document describes the implementation of the in-kernel
 device tree overlay functionality residing in drivers/of/overlay.c and is a
@@ -15,68 +18,68 @@ Since the kernel mainly deals with devices, any new device node that result
 in an active device should have it created while if the device node is either
 disabled or removed all together, the affected device should be deregistered.
 
-Lets take an example where we have a foo board with the following base tree:
-
----- foo.dts -----------------------------------------------------------------
-	/* FOO platform */
-	/ {
-		compatible = "corp,foo";
-
-		/* shared resources */
-		res: res {
-		};
-
-		/* On chip peripherals */
-		ocp: ocp {
-			/* peripherals that are always instantiated */
-			peripheral1 { ... };
-		}
-	};
----- foo.dts -----------------------------------------------------------------
-
-The overlay bar.dts, when loaded (and resolved as described in [1]) should
-
----- bar.dts -----------------------------------------------------------------
-/plugin/;	/* allow undefined label references and record them */
-/ {
-	....	/* various properties for loader use; i.e. part id etc. */
-	fragment@0 {
-		target = <&ocp>;
-		__overlay__ {
-			/* bar peripheral */
-			bar {
-				compatible = "corp,bar";
-				... /* various properties and child nodes */
-			}
-		};
-	};
-};
----- bar.dts -----------------------------------------------------------------
-
-result in foo+bar.dts
-
----- foo+bar.dts -------------------------------------------------------------
-	/* FOO platform + bar peripheral */
-	/ {
-		compatible = "corp,foo";
-
-		/* shared resources */
-		res: res {
-		};
-
-		/* On chip peripherals */
-		ocp: ocp {
-			/* peripherals that are always instantiated */
-			peripheral1 { ... };
-
-			/* bar peripheral */
-			bar {
-				compatible = "corp,bar";
-				... /* various properties and child nodes */
-			}
-		}
-	};
----- foo+bar.dts -------------------------------------------------------------
+Lets take an example where we have a foo board with the following base tree::
+
+    ---- foo.dts --------------------------------------------------------------
+	    /* FOO platform */
+	    / {
+		    compatible = "corp,foo";
+
+		    /* shared resources */
+		    res: res {
+		    };
+
+		    /* On chip peripherals */
+		    ocp: ocp {
+			    /* peripherals that are always instantiated */
+			    peripheral1 { ... };
+		    }
+	    };
+    ---- foo.dts --------------------------------------------------------------
+
+The overlay bar.dts, when loaded (and resolved as described in [1]) should::
+
+    ---- bar.dts --------------------------------------------------------------
+    /plugin/;	/* allow undefined label references and record them */
+    / {
+	    ....	/* various properties for loader use; i.e. part id etc. */
+	    fragment@0 {
+		    target = <&ocp>;
+		    __overlay__ {
+			    /* bar peripheral */
+			    bar {
+				    compatible = "corp,bar";
+				    ... /* various properties and child nodes */
+			    }
+		    };
+	    };
+    };
+    ---- bar.dts --------------------------------------------------------------
+
+result in foo+bar.dts::
+
+    ---- foo+bar.dts ----------------------------------------------------------
+	    /* FOO platform + bar peripheral */
+	    / {
+		    compatible = "corp,foo";
+
+		    /* shared resources */
+		    res: res {
+		    };
+
+		    /* On chip peripherals */
+		    ocp: ocp {
+			    /* peripherals that are always instantiated */
+			    peripheral1 { ... };
+
+			    /* bar peripheral */
+			    bar {
+				    compatible = "corp,bar";
+				    ... /* various properties and child nodes */
+			    }
+		    }
+	    };
+    ---- foo+bar.dts ----------------------------------------------------------
 
 As a result of the overlay, a new device node (bar) has been created
 so a bar platform device will be registered and if a matching device driver
@@ -88,11 +91,11 @@ Overlay in-kernel API
 The API is quite easy to use.
 
 1. Call of_overlay_fdt_apply() to create and apply an overlay changeset. The
-return value is an error or a cookie identifying this overlay.
+   return value is an error or a cookie identifying this overlay.
 
 2. Call of_overlay_remove() to remove and cleanup the overlay changeset
-previously created via the call to of_overlay_fdt_apply(). Removal of an
-overlay changeset that is stacked by another will not be permitted.
+   previously created via the call to of_overlay_fdt_apply(). Removal of an
+   overlay changeset that is stacked by another will not be permitted.
 
 Finally, if you need to remove all overlays in one-go, just call
 of_overlay_remove_all() which will remove every single one in the correct
@@ -109,9 +112,9 @@ respective node it received.
 Overlay DTS Format
 ------------------
 
-The DTS of an overlay should have the following format:
+The DTS of an overlay should have the following format::
 
-{
+    {
 	/* ignored properties by the overlay */
 
 	fragment@0 {	/* first child node */
@@ -131,7 +134,7 @@ The DTS of an overlay should have the following format:
 		...
 	};
 	/* more fragments follow */
-}
+    }
 
 Using the non-phandle based target method allows one to use a base DT which does
 not contain a __symbols__ node, i.e. it was not compiled with the -@ option.
diff --git a/MAINTAINERS b/MAINTAINERS
index 1380b1ed69a2..3f679cb4b330 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12459,7 +12459,7 @@ M:	Frank Rowand <frowand.list@gmail.com>
 L:	devicetree@vger.kernel.org
 S:	Maintained
 F:	Documentation/devicetree/dynamic-resolution-notes.rst
-F:	Documentation/devicetree/overlay-notes.txt
+F:	Documentation/devicetree/overlay-notes.rst
 F:	drivers/of/overlay.c
 F:	drivers/of/resolver.c
 K:	of_overlay_notifier_
-- 
2.21.1

Re: [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format

[Frank Rowand]

On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> - Add a SPDX header;
> - Adjust document title;
> - 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 +
>  .../{overlay-notes.txt => overlay-notes.rst}  | 141 +++++++++---------
>  MAINTAINERS                                   |   2 +-
>  3 files changed, 74 insertions(+), 70 deletions(-)
>  rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%)
> 
> diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> index ca83258fbba5..0669a53fc617 100644
> --- a/Documentation/devicetree/index.rst
> +++ b/Documentation/devicetree/index.rst
> @@ -13,3 +13,4 @@ Open Firmware and Device Tree
>     changesets
>     dynamic-resolution-notes
>     of_unittest
> +   overlay-notes
> diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.rst
> similarity index 56%
> rename from Documentation/devicetree/overlay-notes.txt
> rename to Documentation/devicetree/overlay-notes.rst
> index 3f20a39e4bc2..7e8e568f64a8 100644
> --- a/Documentation/devicetree/overlay-notes.txt
> +++ b/Documentation/devicetree/overlay-notes.rst

There is a collision between 08/12 and a patch I sent a couple of days ago:

   https://lore.kernel.org/r/1580171838-1770-1-git-send-email-frowand.list@gmail.com

-Frank


> @@ -1,5 +1,8 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=========================
>  Device Tree Overlay Notes
> --------------------------
> +=========================
>  
>  This document describes the implementation of the in-kernel
>  device tree overlay functionality residing in drivers/of/overlay.c and is a
> @@ -15,68 +18,68 @@ Since the kernel mainly deals with devices, any new device node that result
>  in an active device should have it created while if the device node is either
>  disabled or removed all together, the affected device should be deregistered.
>  
> -Lets take an example where we have a foo board with the following base tree:
> -
> ----- foo.dts -----------------------------------------------------------------
> -	/* FOO platform */
> -	/ {
> -		compatible = "corp,foo";
> -
> -		/* shared resources */
> -		res: res {
> -		};
> -
> -		/* On chip peripherals */
> -		ocp: ocp {
> -			/* peripherals that are always instantiated */
> -			peripheral1 { ... };
> -		}
> -	};
> ----- foo.dts -----------------------------------------------------------------
> -
> -The overlay bar.dts, when loaded (and resolved as described in [1]) should
> -
> ----- bar.dts -----------------------------------------------------------------
> -/plugin/;	/* allow undefined label references and record them */
> -/ {
> -	....	/* various properties for loader use; i.e. part id etc. */
> -	fragment@0 {
> -		target = <&ocp>;
> -		__overlay__ {
> -			/* bar peripheral */
> -			bar {
> -				compatible = "corp,bar";
> -				... /* various properties and child nodes */
> -			}
> -		};
> -	};
> -};
> ----- bar.dts -----------------------------------------------------------------
> -
> -result in foo+bar.dts
> -
> ----- foo+bar.dts -------------------------------------------------------------
> -	/* FOO platform + bar peripheral */
> -	/ {
> -		compatible = "corp,foo";
> -
> -		/* shared resources */
> -		res: res {
> -		};
> -
> -		/* On chip peripherals */
> -		ocp: ocp {
> -			/* peripherals that are always instantiated */
> -			peripheral1 { ... };
> -
> -			/* bar peripheral */
> -			bar {
> -				compatible = "corp,bar";
> -				... /* various properties and child nodes */
> -			}
> -		}
> -	};
> ----- foo+bar.dts -------------------------------------------------------------
> +Lets take an example where we have a foo board with the following base tree::
> +
> +    ---- foo.dts --------------------------------------------------------------
> +	    /* FOO platform */
> +	    / {
> +		    compatible = "corp,foo";
> +
> +		    /* shared resources */
> +		    res: res {
> +		    };
> +
> +		    /* On chip peripherals */
> +		    ocp: ocp {
> +			    /* peripherals that are always instantiated */
> +			    peripheral1 { ... };
> +		    }
> +	    };
> +    ---- foo.dts --------------------------------------------------------------
> +
> +The overlay bar.dts, when loaded (and resolved as described in [1]) should::
> +
> +    ---- bar.dts --------------------------------------------------------------
> +    /plugin/;	/* allow undefined label references and record them */
> +    / {
> +	    ....	/* various properties for loader use; i.e. part id etc. */
> +	    fragment@0 {
> +		    target = <&ocp>;
> +		    __overlay__ {
> +			    /* bar peripheral */
> +			    bar {
> +				    compatible = "corp,bar";
> +				    ... /* various properties and child nodes */
> +			    }
> +		    };
> +	    };
> +    };
> +    ---- bar.dts --------------------------------------------------------------
> +
> +result in foo+bar.dts::
> +
> +    ---- foo+bar.dts ----------------------------------------------------------
> +	    /* FOO platform + bar peripheral */
> +	    / {
> +		    compatible = "corp,foo";
> +
> +		    /* shared resources */
> +		    res: res {
> +		    };
> +
> +		    /* On chip peripherals */
> +		    ocp: ocp {
> +			    /* peripherals that are always instantiated */
> +			    peripheral1 { ... };
> +
> +			    /* bar peripheral */
> +			    bar {
> +				    compatible = "corp,bar";
> +				    ... /* various properties and child nodes */
> +			    }
> +		    }
> +	    };
> +    ---- foo+bar.dts ----------------------------------------------------------
>  
>  As a result of the overlay, a new device node (bar) has been created
>  so a bar platform device will be registered and if a matching device driver
> @@ -88,11 +91,11 @@ Overlay in-kernel API
>  The API is quite easy to use.
>  
>  1. Call of_overlay_fdt_apply() to create and apply an overlay changeset. The
> -return value is an error or a cookie identifying this overlay.
> +   return value is an error or a cookie identifying this overlay.
>  
>  2. Call of_overlay_remove() to remove and cleanup the overlay changeset
> -previously created via the call to of_overlay_fdt_apply(). Removal of an
> -overlay changeset that is stacked by another will not be permitted.
> +   previously created via the call to of_overlay_fdt_apply(). Removal of an
> +   overlay changeset that is stacked by another will not be permitted.
>  
>  Finally, if you need to remove all overlays in one-go, just call
>  of_overlay_remove_all() which will remove every single one in the correct
> @@ -109,9 +112,9 @@ respective node it received.
>  Overlay DTS Format
>  ------------------
>  
> -The DTS of an overlay should have the following format:
> +The DTS of an overlay should have the following format::
>  
> -{
> +    {
>  	/* ignored properties by the overlay */
>  
>  	fragment@0 {	/* first child node */
> @@ -131,7 +134,7 @@ The DTS of an overlay should have the following format:
>  		...
>  	};
>  	/* more fragments follow */
> -}
> +    }
>  
>  Using the non-phandle based target method allows one to use a base DT which does
>  not contain a __symbols__ node, i.e. it was not compiled with the -@ option.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 1380b1ed69a2..3f679cb4b330 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -12459,7 +12459,7 @@ M:	Frank Rowand <frowand.list@gmail.com>
>  L:	devicetree@vger.kernel.org
>  S:	Maintained
>  F:	Documentation/devicetree/dynamic-resolution-notes.rst
> -F:	Documentation/devicetree/overlay-notes.txt
> +F:	Documentation/devicetree/overlay-notes.rst
>  F:	drivers/of/overlay.c
>  F:	drivers/of/resolver.c
>  K:	of_overlay_notifier_
> 

Re: [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format

[Mauro Carvalho Chehab]

Em Mon, 2 Mar 2020 15:13:21 -0600
Frank Rowand <frowand.list@gmail.com> escreveu:

> On 3/2/20 1:59 AM, Mauro Carvalho Chehab wrote:
> > - Add a SPDX header;
> > - Adjust document title;
> > - 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 +
> >  .../{overlay-notes.txt => overlay-notes.rst}  | 141 +++++++++---------
> >  MAINTAINERS                                   |   2 +-
> >  3 files changed, 74 insertions(+), 70 deletions(-)
> >  rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%)
> > 
> > diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> > index ca83258fbba5..0669a53fc617 100644
> > --- a/Documentation/devicetree/index.rst
> > +++ b/Documentation/devicetree/index.rst
> > @@ -13,3 +13,4 @@ Open Firmware and Device Tree
> >     changesets
> >     dynamic-resolution-notes
> >     of_unittest
> > +   overlay-notes
> > diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.rst
> > similarity index 56%
> > rename from Documentation/devicetree/overlay-notes.txt
> > rename to Documentation/devicetree/overlay-notes.rst
> > index 3f20a39e4bc2..7e8e568f64a8 100644
> > --- a/Documentation/devicetree/overlay-notes.txt
> > +++ b/Documentation/devicetree/overlay-notes.rst  
> 
> There is a collision between 08/12 and a patch I sent a couple of days ago:
> 
>    https://lore.kernel.org/r/1580171838-1770-1-git-send-email-frowand.list@gmail.com

Thanks for pointing it! I'll rebase on the top of linux-next tomorrow
and add your patch on my tree before my series, if not merged on -next
before that.

Regards,
Mauro

[PATCH v2 09/12] docs: dt: minor adjustments at writing-schema.rst

[Mauro Carvalho Chehab]

There are two literal blocks that aren't mark as such. Mark them,
in order to make the document to produce a better html output.

While here, also add a SPDX header to it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/devicetree/writing-schema.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
index 7635ab230456..6b3ef308c59f 100644
--- a/Documentation/devicetree/writing-schema.rst
+++ b/Documentation/devicetree/writing-schema.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 Writing DeviceTree Bindings in json-schema
 ==========================================
@@ -124,9 +124,12 @@ dtc must also be built with YAML output support enabled. This requires that
 libyaml and its headers be installed on the host system. For some distributions
 that involves installing the development package, such as:
 
-Debian:
+Debian::
+
   apt-get install libyaml-dev
-Fedora:
+
+Fedora::
+
   dnf -y install libyaml-devel
 
 Running checks
-- 
2.21.1

[PATCH v2 10/12] docs: dt: convert ABI.txt to ReST format

[Mauro Carvalho Chehab]

This file only requires a properly-formatted title to be
recognized as a ReST file.

As there will be more files under bindings/ that will be
included at the documentation body, add a new index.rst
file there.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/arm/microchip.rst                        |  2 +-
 Documentation/devicetree/bindings/{ABI.txt => ABI.rst} |  5 ++++-
 Documentation/devicetree/bindings/arm/amlogic.yaml     |  2 +-
 Documentation/devicetree/bindings/arm/syna.txt         |  2 +-
 Documentation/devicetree/bindings/index.rst            | 10 ++++++++++
 Documentation/devicetree/index.rst                     |  2 ++
 6 files changed, 19 insertions(+), 4 deletions(-)
 rename Documentation/devicetree/bindings/{ABI.txt => ABI.rst} (94%)
 create mode 100644 Documentation/devicetree/bindings/index.rst

diff --git a/Documentation/arm/microchip.rst b/Documentation/arm/microchip.rst
index 05e5f2dfb814..9c013299fd3b 100644
--- a/Documentation/arm/microchip.rst
+++ b/Documentation/arm/microchip.rst
@@ -192,7 +192,7 @@ Device Tree files and Device Tree bindings that apply to AT91 SoCs and boards ar
 considered as "Unstable". To be completely clear, any at91 binding can change at
 any time. So, be sure to use a Device Tree Binary and a Kernel Image generated from
 the same source tree.
-Please refer to the Documentation/devicetree/bindings/ABI.txt file for a
+Please refer to the Documentation/devicetree/bindings/ABI.rst file for a
 definition of a "Stable" binding/ABI.
 This statement will be removed by AT91 MAINTAINERS when appropriate.
 
diff --git a/Documentation/devicetree/bindings/ABI.txt b/Documentation/devicetree/bindings/ABI.rst
similarity index 94%
rename from Documentation/devicetree/bindings/ABI.txt
rename to Documentation/devicetree/bindings/ABI.rst
index d25f8d379680..a885713cf184 100644
--- a/Documentation/devicetree/bindings/ABI.txt
+++ b/Documentation/devicetree/bindings/ABI.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
 
-  Devicetree (DT) ABI
+===================
+Devicetree (DT) ABI
+===================
 
 I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit
    summary document:
diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml
index f74aba48cec1..a21ce4ad63f6 100644
--- a/Documentation/devicetree/bindings/arm/amlogic.yaml
+++ b/Documentation/devicetree/bindings/arm/amlogic.yaml
@@ -17,7 +17,7 @@ description: |+
   any time. Be sure to use a device tree binary and a kernel image
   generated from the same source tree.
 
-  Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a
+  Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a
   stable binding/ABI.
 
 properties:
diff --git a/Documentation/devicetree/bindings/arm/syna.txt b/Documentation/devicetree/bindings/arm/syna.txt
index 2face46a5f64..d8b48f2edf1b 100644
--- a/Documentation/devicetree/bindings/arm/syna.txt
+++ b/Documentation/devicetree/bindings/arm/syna.txt
@@ -13,7 +13,7 @@ considered "unstable". Any Marvell Berlin device tree binding may change at any
 time. Be sure to use a device tree binary and a kernel image generated from the
 same source tree.
 
-Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a
+Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a
 stable binding/ABI.
 
 ---------------------------------------------------------------
diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
new file mode 100644
index 000000000000..98ebdab24b51
--- /dev/null
+++ b/Documentation/devicetree/bindings/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Device Tree
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   ABI
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 0669a53fc617..2f2c93c75713 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -14,3 +14,5 @@ Open Firmware and Device Tree
    dynamic-resolution-notes
    of_unittest
    overlay-notes
+
+   bindings/index
-- 
2.21.1

[PATCH v2 11/12] docs: dt: convert submitting-patches.txt to ReST format

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Adjust document and section titles;
- Mark literal blocks as such;
- Add it to bindings/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/devicetree/bindings/index.rst          |  1 +
 ...submitting-patches.txt => submitting-patches.rst} | 12 +++++++++---
 .../devicetree/bindings/writing-bindings.txt         |  2 +-
 Documentation/process/submitting-patches.rst         |  2 +-
 .../it_IT/process/submitting-patches.rst             |  2 +-
 scripts/checkpatch.pl                                |  2 +-
 6 files changed, 14 insertions(+), 7 deletions(-)
 rename Documentation/devicetree/bindings/{submitting-patches.txt => submitting-patches.rst} (92%)

diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
index 98ebdab24b51..6b87875a049c 100644
--- a/Documentation/devicetree/bindings/index.rst
+++ b/Documentation/devicetree/bindings/index.rst
@@ -8,3 +8,4 @@ Device Tree
    :maxdepth: 1
 
    ABI
+   submitting-patches
diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.rst
similarity index 92%
rename from Documentation/devicetree/bindings/submitting-patches.txt
rename to Documentation/devicetree/bindings/submitting-patches.rst
index 98bee6240b65..0aab2b3f16d0 100644
--- a/Documentation/devicetree/bindings/submitting-patches.txt
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -1,13 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
 
-  Submitting devicetree (DT) binding patches
+==========================================
+Submitting devicetree (DT) binding patches
+==========================================
 
 I. For patch submitters
+=======================
 
   0) Normal patch submission rules from Documentation/process/submitting-patches.rst
      applies.
 
   1) The Documentation/ and include/dt-bindings/ portion of the patch should
-     be a separate patch. The preferred subject prefix for binding patches is:
+     be a separate patch. The preferred subject prefix for binding patches is::
 
        "dt-bindings: <binding dir>: ..."
 
@@ -17,7 +21,7 @@ I. For patch submitters
 
   2) DT binding files are written in DT schema format using json-schema
      vocabulary and YAML file format. The DT binding files must pass validation
-     by running:
+     by running::
 
        make dt_binding_check
 
@@ -60,6 +64,7 @@ I. For patch submitters
 
 
 II. For kernel maintainers
+==========================
 
   1) If you aren't comfortable reviewing a given binding, reply to it and ask
      the devicetree maintainers for guidance.  This will help them prioritize
@@ -76,6 +81,7 @@ II. For kernel maintainers
      kept with the driver using the binding.
 
 III. Notes
+==========
 
   0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
 
diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.txt
index 27dfd2d8016e..ca024b9c7433 100644
--- a/Documentation/devicetree/bindings/writing-bindings.txt
+++ b/Documentation/devicetree/bindings/writing-bindings.txt
@@ -4,7 +4,7 @@ This is a list of common review feedback items focused on binding design. With
 every rule, there are exceptions and bindings have many gray areas.
 
 For guidelines related to patches, see
-Documentation/devicetree/bindings/submitting-patches.txt
+Documentation/devicetree/bindings/submitting-patches.rst
 
 
 Overall design
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index ba5e944c7a63..1699b7f8e63a 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -16,7 +16,7 @@ for a list of items to check before
 submitting code.  If you are submitting a driver, also read
 :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`;
 for device tree binding patches, read
-Documentation/devicetree/bindings/submitting-patches.txt.
+Documentation/devicetree/bindings/submitting-patches.rst.
 
 Many of these steps describe the default behavior of the ``git`` version
 control system; if you use ``git`` to prepare your patches, you'll find much
diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst
index cba1f8cb61ed..7c23c08e4401 100644
--- a/Documentation/translations/it_IT/process/submitting-patches.rst
+++ b/Documentation/translations/it_IT/process/submitting-patches.rst
@@ -21,7 +21,7 @@ Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rs
 per una lista di punti da verificare prima di inviare del codice.  Se state
 inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`;
 per delle patch relative alle associazioni per Device Tree leggete
-Documentation/devicetree/bindings/submitting-patches.txt.
+Documentation/devicetree/bindings/submitting-patches.rst.
 
 Molti di questi passi descrivono il comportamento di base del sistema di
 controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 4480d5eec2fa..14c7277e60a0 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -2607,7 +2607,7 @@ sub process {
 				if (($last_binding_patch != -1) &&
 				    ($last_binding_patch ^ $is_binding_patch)) {
 					WARN("DT_SPLIT_BINDING_PATCH",
-					     "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.txt\n");
+					     "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.rst\n");
 				}
 			}
 
-- 
2.21.1

[PATCH v2 12/12] docs: dt: convert writing-bindings.txt to ReST

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Adjust document and section titles;
- Mark literal blocks as such;
- Add it to bindings/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/devicetree/bindings/index.rst                | 1 +
 .../{writing-bindings.txt => writing-bindings.rst}         | 7 +++++++
 2 files changed, 8 insertions(+)
 rename Documentation/devicetree/bindings/{writing-bindings.txt => writing-bindings.rst} (92%)

diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
index 6b87875a049c..3837b17c234f 100644
--- a/Documentation/devicetree/bindings/index.rst
+++ b/Documentation/devicetree/bindings/index.rst
@@ -9,3 +9,4 @@ Device Tree
 
    ABI
    submitting-patches
+   writing-bindings
diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.rst
similarity index 92%
rename from Documentation/devicetree/bindings/writing-bindings.txt
rename to Documentation/devicetree/bindings/writing-bindings.rst
index ca024b9c7433..45ff426d0019 100644
--- a/Documentation/devicetree/bindings/writing-bindings.txt
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -1,4 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================================
 DOs and DON'Ts for designing and writing Devicetree bindings
+============================================================
 
 This is a list of common review feedback items focused on binding design. With
 every rule, there are exceptions and bindings have many gray areas.
@@ -8,6 +12,7 @@ Documentation/devicetree/bindings/submitting-patches.rst
 
 
 Overall design
+==============
 
 - DO attempt to make bindings complete even if a driver doesn't support some
   features. For example, if a device has an interrupt, then include the
@@ -32,6 +37,7 @@ Overall design
 
 
 Properties
+==========
 
 - DO make 'compatible' properties specific. DON'T use wildcards in compatible
   strings. DO use fallback compatibles when devices are the same as or a subset
@@ -53,6 +59,7 @@ Properties
 
 
 Board/SoC .dts Files
+====================
 
 - DO put all MMIO devices under a bus node and not at the top-level.
 
-- 
2.21.1

Re: [PATCH v2 00/12] Convert some DT documentation files to ReST

[Mauro Carvalho Chehab]

Em Mon, 2 Mar 2020 12:35:54 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon,  2 Mar 2020 08:59:25 +0100
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
> > While most of the devicetree stuff has its own format (with is now being
> > converted to YAML format), some documents there are actually
> > describing the DT concepts and how to contribute to it.
> > 
> > IMHO, those documents would fit perfectly as part of the documentation
> > body, as part of the firmare documents set.
> > 
> > This patch series manually converts some DT documents that, on my
> > opinion, would belong to it.  
> 
> Did you consider putting this stuff into the firmware-guide while you were
> at it?  It's not a perfect fit, I guess, but it doesn't seem too awkward
> either.

I placed it just below the firmware-guide at the main index file.

I have split thoughts about moving the files to there, though. From
one side, it may fit better from the PoV of organizing the documentation.

From other side, newcomers working with DT may expect looking at the
text files inside Documentation/devicetree/.

Maybe I could add an extra patch at the end of this series with the
move, adding a "RFC" on his title. This way, we can better discuss it,
and either merge the last one or not depending on the comments.

> 
> It also seems like it would be good to CC the devicetree folks, or at
> least the devicetree mailing list?

Yeah, that would make sense. I'm using get-maintainers script to
prepare the c/c list, as it is simply too much work to find the
right maintainers by hand, for every single patch.

I just noticed today that there's just *one entry* at MAINTAINERS
file for Documentation/devicetree, and that points to you:

	DOCUMENTATION
	M:	Jonathan Corbet <corbet@lwn.net>
	L:      linux-doc@vger.kernel.org
	S:	Maintained
	F:      Documentation/
	F:	scripts/documentation-file-ref-check
	F:	scripts/kernel-doc
	F:	scripts/sphinx-pre-install
	X:      Documentation/ABI/
	X:	Documentation/firmware-guide/acpi/
	X:	Documentation/devicetree/

So, perhaps we should add something like this to MAINTAINERS:

diff --git a/MAINTAINERS b/MAINTAINERS
index fe3ab10354c2..64deb23dbb13 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12394,6 +12394,11 @@ L:	linux-rdma@vger.kernel.org
 S:	Supported
 F:	drivers/infiniband/ulp/opa_vnic
 
+OPEN FIRMWARE
+L:	devicetree@vger.kernel.org
+S:	Maintained
+F:	Documentation/devicetree
+
 OPEN FIRMWARE AND DEVICE TREE OVERLAYS
 M:	Pantelis Antoniou <pantelis.antoniou@konsulko.com>
 M:	Frank Rowand <frowand.list@gmail.com>

Re: [PATCH v2 00/12] Convert some DT documentation files to ReST

[Rob Herring]

On Tue, Mar 3, 2020 at 1:09 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Em Mon, 2 Mar 2020 12:35:54 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
> > On Mon,  2 Mar 2020 08:59:25 +0100
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> >
> > > While most of the devicetree stuff has its own format (with is now being
> > > converted to YAML format), some documents there are actually
> > > describing the DT concepts and how to contribute to it.
> > >
> > > IMHO, those documents would fit perfectly as part of the documentation
> > > body, as part of the firmare documents set.
> > >
> > > This patch series manually converts some DT documents that, on my
> > > opinion, would belong to it.
> >
> > Did you consider putting this stuff into the firmware-guide while you were
> > at it?  It's not a perfect fit, I guess, but it doesn't seem too awkward
> > either.
>
> I placed it just below the firmware-guide at the main index file.
>
> I have split thoughts about moving the files to there, though. From
> one side, it may fit better from the PoV of organizing the documentation.
>
> From other side, newcomers working with DT may expect looking at the
> text files inside Documentation/devicetree/.
>
> Maybe I could add an extra patch at the end of this series with the
> move, adding a "RFC" on his title. This way, we can better discuss it,
> and either merge the last one or not depending on the comments.

Keep in mind that we generate a standalone DT only tree[1] with the
documentation, dts files and headers. So things should be structured
such that all the DT documentation could be built by itself without
dependencies on the 'kernel documentation'. I'm not asking for that to
be done in this series, but just don't do anything to make that
harder. I don't *think* have, but just want to make sure that's clear.

> > It also seems like it would be good to CC the devicetree folks, or at
> > least the devicetree mailing list?

I was wondering what happened to the cover letter on v2...

> Yeah, that would make sense. I'm using get-maintainers script to
> prepare the c/c list, as it is simply too much work to find the
> right maintainers by hand, for every single patch.
>
> I just noticed today that there's just *one entry* at MAINTAINERS
> file for Documentation/devicetree, and that points to you:
>
>         DOCUMENTATION
>         M:      Jonathan Corbet <corbet@lwn.net>
>         L:      linux-doc@vger.kernel.org
>         S:      Maintained
>         F:      Documentation/
>         F:      scripts/documentation-file-ref-check
>         F:      scripts/kernel-doc
>         F:      scripts/sphinx-pre-install
>         X:      Documentation/ABI/
>         X:      Documentation/firmware-guide/acpi/
>         X:      Documentation/devicetree/

You mean doesn't point to Jon as 'X' is exclude. You missed this entry:

OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
M:      Rob Herring <robh+dt@kernel.org>
M:      Mark Rutland <mark.rutland@arm.com>
L:      devicetree@vger.kernel.org
T:      git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git
Q:      http://patchwork.ozlabs.org/project/devicetree-bindings/list/
S:      Maintained
F:      Documentation/devicetree/
F:      arch/*/boot/dts/
F:      include/dt-bindings/


Rob

[1] https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/

Re: [PATCH v2 00/12] Convert some DT documentation files to ReST

[Mauro Carvalho Chehab]

Em Tue, 3 Mar 2020 10:20:25 -0600
Rob Herring <robh@kernel.org> escreveu:

> On Tue, Mar 3, 2020 at 1:09 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Em Mon, 2 Mar 2020 12:35:54 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >  
> > > On Mon,  2 Mar 2020 08:59:25 +0100
> > > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > >  
> > > > While most of the devicetree stuff has its own format (with is now being
> > > > converted to YAML format), some documents there are actually
> > > > describing the DT concepts and how to contribute to it.
> > > >
> > > > IMHO, those documents would fit perfectly as part of the documentation
> > > > body, as part of the firmare documents set.
> > > >
> > > > This patch series manually converts some DT documents that, on my
> > > > opinion, would belong to it.  
> > >
> > > Did you consider putting this stuff into the firmware-guide while you were
> > > at it?  It's not a perfect fit, I guess, but it doesn't seem too awkward
> > > either.  
> >
> > I placed it just below the firmware-guide at the main index file.
> >
> > I have split thoughts about moving the files to there, though. From
> > one side, it may fit better from the PoV of organizing the documentation.
> >
> > From other side, newcomers working with DT may expect looking at the
> > text files inside Documentation/devicetree/.
> >
> > Maybe I could add an extra patch at the end of this series with the
> > move, adding a "RFC" on his title. This way, we can better discuss it,
> > and either merge the last one or not depending on the comments.  
> 
> Keep in mind that we generate a standalone DT only tree[1] with the
> documentation, dts files and headers. So things should be structured
> such that all the DT documentation could be built by itself without
> dependencies on the 'kernel documentation'. I'm not asking for that to
> be done in this series, but just don't do anything to make that
> harder. I don't *think* have, but just want to make sure that's clear.

So, I guess it is better to keep the .rst files under Documentation/devicetree,
instead of moving them to Documentation/firmware-guide.

Well, if moved, I guess it would be easy to modify the scripts that produce
the documentation to also parse something a new directory inside
Documentation/firmware-guide.

> 
> > > It also seems like it would be good to CC the devicetree folks, or at
> > > least the devicetree mailing list?  
> 
> I was wondering what happened to the cover letter on v2...
> 
> > Yeah, that would make sense. I'm using get-maintainers script to
> > prepare the c/c list, as it is simply too much work to find the
> > right maintainers by hand, for every single patch.
> >
> > I just noticed today that there's just *one entry* at MAINTAINERS
> > file for Documentation/devicetree, and that points to you:
> >
> >         DOCUMENTATION
> >         M:      Jonathan Corbet <corbet@lwn.net>
> >         L:      linux-doc@vger.kernel.org
> >         S:      Maintained
> >         F:      Documentation/
> >         F:      scripts/documentation-file-ref-check
> >         F:      scripts/kernel-doc
> >         F:      scripts/sphinx-pre-install
> >         X:      Documentation/ABI/
> >         X:      Documentation/firmware-guide/acpi/
> >         X:      Documentation/devicetree/  
> 
> You mean doesn't point to Jon as 'X' is exclude. You missed this entry:
> 
> OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
> M:      Rob Herring <robh+dt@kernel.org>
> M:      Mark Rutland <mark.rutland@arm.com>
> L:      devicetree@vger.kernel.org
> T:      git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git
> Q:      http://patchwork.ozlabs.org/project/devicetree-bindings/list/
> S:      Maintained
> F:      Documentation/devicetree/
> F:      arch/*/boot/dts/
> F:      include/dt-bindings/

Yeah, I remember I saw something like the above in the past. However,
I'm not seeing this entry at the MAINTAINERS file at next-20200303 anymore.

Did someone removed such entry?

> 
> 
> Rob
> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/

Re: [PATCH v2 00/12] Convert some DT documentation files to ReST

[Mauro Carvalho Chehab]

Em Tue, 3 Mar 2020 18:01:09 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Tue, 3 Mar 2020 10:20:25 -0600
> Rob Herring <robh@kernel.org> escreveu:
> 
> > On Tue, Mar 3, 2020 at 1:09 AM Mauro Carvalho Chehab
> > <mchehab+huawei@kernel.org> wrote:  
> > >
> > > Em Mon, 2 Mar 2020 12:35:54 -0700
> > > Jonathan Corbet <corbet@lwn.net> escreveu:
> > >    
> > > > On Mon,  2 Mar 2020 08:59:25 +0100
> > > > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > > >    
> > > > > While most of the devicetree stuff has its own format (with is now being
> > > > > converted to YAML format), some documents there are actually
> > > > > describing the DT concepts and how to contribute to it.
> > > > >
> > > > > IMHO, those documents would fit perfectly as part of the documentation
> > > > > body, as part of the firmare documents set.
> > > > >
> > > > > This patch series manually converts some DT documents that, on my
> > > > > opinion, would belong to it.    
> > > >
> > > > Did you consider putting this stuff into the firmware-guide while you were
> > > > at it?  It's not a perfect fit, I guess, but it doesn't seem too awkward
> > > > either.    
> > >
> > > I placed it just below the firmware-guide at the main index file.
> > >
> > > I have split thoughts about moving the files to there, though. From
> > > one side, it may fit better from the PoV of organizing the documentation.
> > >
> > > From other side, newcomers working with DT may expect looking at the
> > > text files inside Documentation/devicetree/.
> > >
> > > Maybe I could add an extra patch at the end of this series with the
> > > move, adding a "RFC" on his title. This way, we can better discuss it,
> > > and either merge the last one or not depending on the comments.    
> > 
> > Keep in mind that we generate a standalone DT only tree[1] with the
> > documentation, dts files and headers. So things should be structured
> > such that all the DT documentation could be built by itself without
> > dependencies on the 'kernel documentation'. I'm not asking for that to
> > be done in this series, but just don't do anything to make that
> > harder. I don't *think* have, but just want to make sure that's clear.  
> 
> So, I guess it is better to keep the .rst files under Documentation/devicetree,
> instead of moving them to Documentation/firmware-guide.
> 
> Well, if moved, I guess it would be easy to modify the scripts that produce
> the documentation to also parse something a new directory inside
> Documentation/firmware-guide.
> 
> >   
> > > > It also seems like it would be good to CC the devicetree folks, or at
> > > > least the devicetree mailing list?    
> > 
> > I was wondering what happened to the cover letter on v2...
> >   
> > > Yeah, that would make sense. I'm using get-maintainers script to
> > > prepare the c/c list, as it is simply too much work to find the
> > > right maintainers by hand, for every single patch.
> > >
> > > I just noticed today that there's just *one entry* at MAINTAINERS
> > > file for Documentation/devicetree, and that points to you:
> > >
> > >         DOCUMENTATION
> > >         M:      Jonathan Corbet <corbet@lwn.net>
> > >         L:      linux-doc@vger.kernel.org
> > >         S:      Maintained
> > >         F:      Documentation/
> > >         F:      scripts/documentation-file-ref-check
> > >         F:      scripts/kernel-doc
> > >         F:      scripts/sphinx-pre-install
> > >         X:      Documentation/ABI/
> > >         X:      Documentation/firmware-guide/acpi/
> > >         X:      Documentation/devicetree/    
> > 
> > You mean doesn't point to Jon as 'X' is exclude. You missed this entry:
> > 
> > OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
> > M:      Rob Herring <robh+dt@kernel.org>
> > M:      Mark Rutland <mark.rutland@arm.com>
> > L:      devicetree@vger.kernel.org
> > T:      git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git
> > Q:      http://patchwork.ozlabs.org/project/devicetree-bindings/list/
> > S:      Maintained
> > F:      Documentation/devicetree/
> > F:      arch/*/boot/dts/
> > F:      include/dt-bindings/  
> 
> Yeah, I remember I saw something like the above in the past. However,
> I'm not seeing this entry at the MAINTAINERS file at next-20200303 anymore.
> 
> Did someone removed such entry?

Sorry, false alarm. 

It is there at next. 

I guess it is time for call it a day.

That doesn't explain why I didn't add DT ML to the c/c. I'll try to 
verify what's going on tomorrow.

Regards,
Mauro