From: frowand.list@gmail.com
To: Rob Herring <robh+dt@kernel.org>, pantelis.antoniou@konsulko.com
Cc: devicetree@vger.kernel.org, linux-kernel@vger.kernel.org,
Geert Uytterhoeven <geert+renesas@glider.be>,
Alan Tull <atull@kernel.org>
Subject: [PATCH v2] of: Documentation: change overlay example to use current syntax
Date: Mon, 27 Jan 2020 18:37:18 -0600 [thread overview]
Message-ID: <1580171838-1770-1-git-send-email-frowand.list@gmail.com> (raw)
From: Frank Rowand <frank.rowand@sony.com>
The overlay implementation details in the compiled (DTB) file are
now properly implemented by the dtc compiler and should no longer
be hard coded in the source file.
Signed-off-by: Frank Rowand <frank.rowand@sony.com>
---
changes since v1:
- fixed typo in patch comment (implementation)
Documentation/devicetree/overlay-notes.txt | 85 ++++++++++++------------------
1 file changed, 35 insertions(+), 50 deletions(-)
diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt
index 725fb8d255c1..fddc63da7dba 100644
--- a/Documentation/devicetree/overlay-notes.txt
+++ b/Documentation/devicetree/overlay-notes.txt
@@ -19,6 +19,7 @@ Lets take an example where we have a foo board with the following base tree:
---- foo.dts -----------------------------------------------------------------
/* FOO platform */
+ /dts-v1/;
/ {
compatible = "corp,foo";
@@ -30,30 +31,25 @@ Lets take an example where we have a foo board with the following base tree:
ocp: ocp {
/* peripherals that are always instantiated */
peripheral1 { ... };
- }
+ };
};
---- foo.dts -----------------------------------------------------------------
-The overlay bar.dts, when loaded (and resolved as described in [1]) should
+The overlay bar.dts,
----- 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 - overlay target location by label ------------------------------
+ /dts-v1/;
+ /plugin/;
+ &ocp {
+ /* bar peripheral */
+ bar {
+ compatible = "corp,bar";
+ ... /* various properties and child nodes */
};
};
-};
---- bar.dts -----------------------------------------------------------------
-result in foo+bar.dts
+when loaded (and resolved as described in [1]) should result in foo+bar.dts
---- foo+bar.dts -------------------------------------------------------------
/* FOO platform + bar peripheral */
@@ -73,8 +69,8 @@ result in foo+bar.dts
bar {
compatible = "corp,bar";
... /* various properties and child nodes */
- }
- }
+ };
+ };
};
---- foo+bar.dts -------------------------------------------------------------
@@ -82,6 +78,27 @@ 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
is loaded the device will be created as expected.
+If the base DT was not compiled with the -@ option then the "&ocp" label
+will not be available to resolve the overlay node(s) to the proper location
+in the base DT. In this case, the target path can be provided. The target
+location by label syntax is preferred because the overlay can be applied to
+any base DT containing the label, no matter where the label occurs in the DT.
+
+The above bar.dts example modified to use target path syntax is:
+
+---- bar.dts - overlay target location by explicit path ----------------------
+ /dts-v1/;
+ /plugin/;
+ &{/ocp} {
+ /* bar peripheral */
+ bar {
+ compatible = "corp,bar";
+ ... /* various properties and child nodes */
+ }
+ };
+---- bar.dts -----------------------------------------------------------------
+
+
Overlay in-kernel API
--------------------------------
@@ -105,35 +122,3 @@ enum of_overlay_notify_action for details.
Note that a notifier callback is not supposed to store pointers to a device
tree node or its content beyond OF_OVERLAY_POST_REMOVE corresponding to the
respective node it received.
-
-Overlay DTS Format
-------------------
-
-The DTS of an overlay should have the following format:
-
-{
- /* ignored properties by the overlay */
-
- fragment@0 { /* first child node */
-
- target=<phandle>; /* phandle target of the overlay */
- or
- target-path="/path"; /* target path of the overlay */
-
- __overlay__ {
- property-a; /* add property-a to the target */
- node-a { /* add to an existing, or create a node-a */
- ...
- };
- };
- }
- fragment@1 { /* second child node */
- ...
- };
- /* 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.
-The __symbols__ node is only required for the target=<phandle> method, since it
-contains the information required to map from a phandle to a tree location.
--
Frank Rowand <frank.rowand@sony.com>
next reply other threads:[~2020-01-28 0:38 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-28 0:37 frowand.list [this message]
2020-01-28 8:37 ` [PATCH v2] of: Documentation: change overlay example to use current syntax Geert Uytterhoeven
2020-05-04 20:16 ` Frank Rowand
2020-05-04 20:56 ` Rob Herring
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=1580171838-1770-1-git-send-email-frowand.list@gmail.com \
--to=frowand.list@gmail.com \
--cc=atull@kernel.org \
--cc=devicetree@vger.kernel.org \
--cc=geert+renesas@glider.be \
--cc=linux-kernel@vger.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).