Skip to content

Commit

Permalink
of: Documentation: change overlay example to use current syntax
Browse files Browse the repository at this point in the history
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>
Reviewed-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Rob Herring <robh@kernel.org>
  • Loading branch information
frowand authored and robherring committed May 4, 2020
1 parent 2407fcb commit 9ae8578
Showing 1 changed file with 35 additions and 50 deletions.
85 changes: 35 additions & 50 deletions Documentation/devicetree/overlay-notes.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand All @@ -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 */
Expand All @@ -73,15 +69,36 @@ result in foo+bar.dts
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
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
--------------------------------

Expand All @@ -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.

0 comments on commit 9ae8578

Please sign in to comment.