From 56fc7032e1771882a086e8283586fc7c733ba6bd Mon Sep 17 00:00:00 2001
From: Franklin S Cooper Jr <fcooper@ti.com>
Date: Mon, 4 Sep 2017 23:12:19 +0300
Subject: [PATCH] doc: overlays: Tweak documentation regarding overlays

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 <fcooper@ti.com>
Acked-by: Simon Glass <sjg@chromium.org>
---
 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 = <&foo>;
+			__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
 ------------------------------