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@xxxxxxxxxx>
> ---
>  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@xxxxxxxxx

-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@xxxxxxxxx>
>  L:	devicetree@xxxxxxxxxxxxxxx
>  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_
>