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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).