From: Frank Rowand <frowand.list@gmail.com>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
Rob Herring <robh+dt@kernel.org>,
Pantelis Antoniou <pantelis.antoniou@konsulko.com>,
devicetree@vger.kernel.org
Subject: Re: [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format
Date: Mon, 2 Mar 2020 15:13:21 -0600 [thread overview]
Message-ID: <3fac6196-e9c4-a23d-c5e3-f17367e5db91@gmail.com> (raw)
In-Reply-To: <1685e79f7b53c70c64e37841fb4df173094ebd17.1583135507.git.mchehab+huawei@kernel.org>
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_
>
next prev parent reply other threads:[~2020-03-02 21:13 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-02 7:59 [PATCH v2 00/12] Convert some DT documentation files to ReST Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 01/12] docs: dt: add an index.rst file for devicetree Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST Mauro Carvalho Chehab
2020-03-02 11:54 ` Lee Jones
2020-03-02 21:11 ` Frank Rowand
2020-03-03 7:13 ` Mauro Carvalho Chehab
2020-03-02 21:18 ` Frank Rowand
2020-03-03 7:25 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage Mauro Carvalho Chehab
2020-03-02 21:11 ` Frank Rowand
2020-03-02 21:40 ` Rob Herring
2020-03-03 7:31 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format Mauro Carvalho Chehab
2020-03-04 18:25 ` Rob Herring
2020-03-05 1:45 ` Alex Shi
2020-03-02 7:59 ` [PATCH v2 05/12] docs: dt: convert changesets to ReST Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 06/12] docs: dt: convert dynamic-resolution-notes.txt " Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 07/12] docs: dt: convert of_unittest.txt " Mauro Carvalho Chehab
2020-03-02 21:11 ` Frank Rowand
2020-03-03 7:15 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format Mauro Carvalho Chehab
2020-03-02 21:13 ` Frank Rowand [this message]
2020-03-03 7:17 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 09/12] docs: dt: minor adjustments at writing-schema.rst Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 10/12] docs: dt: convert ABI.txt to ReST format Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 11/12] docs: dt: convert submitting-patches.txt " Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 12/12] docs: dt: convert writing-bindings.txt to ReST Mauro Carvalho Chehab
2020-03-02 19:35 ` [PATCH v2 00/12] Convert some DT documentation files " Jonathan Corbet
2020-03-03 7:09 ` Mauro Carvalho Chehab
2020-03-03 16:20 ` Rob Herring
2020-03-03 17:01 ` Mauro Carvalho Chehab
2020-03-03 17:07 ` Mauro Carvalho Chehab
2020-03-02 21:10 ` Frank Rowand
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=3fac6196-e9c4-a23d-c5e3-f17367e5db91@gmail.com \
--to=frowand.list@gmail.com \
--cc=corbet@lwn.net \
--cc=devicetree@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab+huawei@kernel.org \
--cc=pantelis.antoniou@konsulko.com \
--cc=robh+dt@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.