Skip to contentSkip to conversation

of: Documentation: change overlay example to use current syntax

PATCH Applied [email protected] 3 participants 4 messages Jan 28, 2020 – May 4, 2020 Device tree bindings

lore
Share & tools
lore
#0 lore raw

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
index 725fb8d255c1..fddc63da7dba 100644
@@ -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]>
Reviewed-by on v2 1/1
#1 lore raw
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.

---

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
#2 lore raw
In reply to [email protected]

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.

---

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
index 725fb8d255c1..fddc63da7dba 100644
@@ -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.
maintainer Applied
#3 lore raw
In reply to [email protected]
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

---

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