Re: [U-Boot] [PATCH v2 06/10] doc: overlays: Tweak documentation regarding overlays

[Simon Glass]

On 11 August 2017 at 02:52, Pantelis Antoniou
 wrote:
> From: Franklin S Cooper Jr 
>
> Pull some information regarding overlays from commit messages and
> put them directly within the documentation. Also add some information
> regarding required dtc version to properly use overlays.
>
> Signed-off-by: Franklin S Cooper Jr 
> ---
>  doc/README.fdt-overlays | 85 
> +++--
>  doc/uImage.FIT/overlay-fdt-boot.txt |  8 +++-
>  2 files changed, 87 insertions(+), 6 deletions(-)

Reviewed-by: Simon Glass 
___
U-Boot mailing list
U-Boot@lists.denx.de
https://lists.denx.de/listinfo/u-boot

[U-Boot] [PATCH v2 06/10] doc: overlays: Tweak documentation regarding overlays

[Pantelis Antoniou]

From: Franklin S Cooper Jr 

Pull some information regarding overlays from commit messages and
put them directly within the documentation. Also add some information
regarding required dtc version to properly use overlays.

Signed-off-by: Franklin S Cooper Jr 
---
 doc/README.fdt-overlays | 85 +++--
 doc/uImage.FIT/overlay-fdt-boot.txt |  8 +++-
 2 files changed, 87 insertions(+), 6 deletions(-)

diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays
index ee868ec..39139cb 100644
--- a/doc/README.fdt-overlays
+++ b/doc/README.fdt-overlays
@@ -1,9 +1,76 @@
-U-Boot FDT Overlay usage (without FIT images)
+U-Boot FDT Overlay usage
 =
 
-FDT overlays are now available for use even without FIT images.
-It is not as automagic as with FIT images though and require a few
-manual steps.
+Overlays Syntax
+---
+
+Overlays require slightly different syntax compared to traditional overlays.
+Please refer to dt-object-internal.txt in the dtc sources for information
+regarding the internal format of overlays:
+https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
+
+Building Overlays
+-
+
+In a nutshell overlays provides a means to manipulate a symbol a previous dtb
+or overlay has defined. It requires both the base and all the overlays
+to be compiled with the -@ command line switch so that symbol information is
+included.
+
+Note support for -@ option can only be found in dtc version 1.4.4 or newer.
+Only version 4.14 or higher of the Linux kernel includes a built in version
+of dtc that meets this requirement.
+
+Building an overlay follows the same process as building a traditional dtb.
+
+For example:
+
+base.dts
+
+
+   /dts-v1/;
+   / {
+   foo: foonode {
+   foo-property;
+   };
+   };
+
+   $ dtc -@ -I dts -O dtb -o base.dtb base.dts
+
+bar.dts
+---
+
+   /dts-v1/;
+   /plugin/;
+   / {
+   fragment@1 {
+   target = <>;
+   __overlay__ {
+   overlay-1-property;
+   bar: barnode {
+   bar-property;
+   };
+   };
+   };
+   };
+
+   $ dtc -@ -I dts -O dtb -o bar.dtb bar.dts
+
+Ways to Utilize Overlays in U-boot
+--
+
+There are two ways to apply overlays in U-boot.
+1. Include and define overlays within a FIT image and have overlays
+   automatically applied.
+
+2. Manually load and apply overlays
+
+The remainder of this document will discuss using overlays via the manual
+approach. For information on using overlays as part of a FIT image please see:
+doc/uImage.FIT/overlay-fdt-boot.txt
+
+Manually Loading and Applying Overlays
+--
 
 1. Figure out where to place both the base device tree blob and the
 overlay. Make sure you have enough space to grow the base tree without
@@ -29,6 +96,16 @@ overlapping anything.
 
 => fdt apply $fdtovaddr
 
+6. Boot system like you would do with a traditional dtb.
+
+For bootm:
+
+=> bootm ${kerneladdr} - ${fdtaddr}
+
+For bootz:
+
+=> bootz ${kerneladdr} - ${fdtaddr}
+
 Please note that in case of an error, both the base and overlays are going
 to be invalidated, so keep copies to avoid reloading.
 
diff --git a/doc/uImage.FIT/overlay-fdt-boot.txt 
b/doc/uImage.FIT/overlay-fdt-boot.txt
index dbdf2a1..63e47da 100644
--- a/doc/uImage.FIT/overlay-fdt-boot.txt
+++ b/doc/uImage.FIT/overlay-fdt-boot.txt
@@ -1,5 +1,5 @@
-U-Boot FDT Overlay usage
-
+U-Boot FDT Overlay FIT usage
+
 
 Introduction
 
@@ -8,6 +8,10 @@ of similar boards and their expansion options. The same kernel 
on DT enabled
 platforms can support this easily enough by providing a DT blob upon boot
 that matches the desired configuration.
 
+This document focuses on specifically using overlays as part of a FIT image.
+General information regarding overlays including its syntax and building it
+can be found in doc/README.fdt-overlays
+
 Configuration without overlays
 --
 
-- 
2.1.4

___
U-Boot mailing list
U-Boot@lists.denx.de
https://lists.denx.de/listinfo/u-boot