of: Documentation: change overlay example to use current syntax
PATCH v2 1/1 of: Documentation: change overlay example to use current syntax
From: Frank Rowand <[email protected]>
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.
---
changes since v1:
- fixed typo in patch comment (implementation)
Documentation/devicetree/overlay-notes.txt | 85 ++++++++++++------------------ 1 file changed, 35 insertions(+), 50 deletions(-)
Documentation/devicetree/overlay-notes.txt +35 -50
@@ -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.
Signature · 1 line
Frank Rowand <[email protected]>
Quoted 11 lines · On Tue, Jan 28, 2020 at 1:38 AM <[email protected]> wrote:
From: Frank Rowand <[email protected]>
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 <[email protected]>---
changes since v1:
- fixed typo in patch comment (implementation)
Gr{oetje,eeting}s,
Geert
Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected] In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that. -- Linus Torvalds
Hi Rob,
Ping.
There is a conflict between this and Mauro's v3 patch at:
https://lore.kernel.org/r/[email protected]
I pointed out the conflict to Mauro in his v2 patch, and he said he would rebase on a new -next to resolve the conflict. Unfortunately my patch was not in -next, so the conflict remains.
If Mauro's patches should go in first, I can redo my patches on top of his, after his go in.
-Frank
Quoted 145 lines · On 1/27/20 6:37 PM, [email protected] wrote:
From: Frank Rowand <[email protected]>
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 <[email protected]>---
changes since v1:
- fixed typo in patch comment (implementation)Documentation/devicetree/overlay-notes.txt | 85 ++++++++++++------------------ 1 file changed, 35 insertions(+), 50 deletions(-)Documentation/devicetree/overlay-notes.txt +35
-50@@ -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.
Quoted 6 lines · On Mon, Jan 27, 2020 at 06:37:18PM -0600, [email protected] wrote:
From: Frank Rowand <[email protected]>
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.
Quoted 8 lines
Signed-off-by Frank Rowand <[email protected]>---
changes since v1:
- fixed typo in patch comment (implementation)Documentation/devicetree/overlay-notes.txt | 85 ++++++++++++------------------ 1 file changed, 35 insertions(+), 50 deletions(-)
Applied. Sorry this slipped thru the cracks.
Rob