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