[U-Boot] [PATCH v3 10/14] doc: overlays: Tweak documentation regarding overlays

[Łukasz Majewski]

On 09/04/2017 10:12 PM, Pantelis Antoniou wrote:
> From: Franklin S Cooper Jr <fcooper at ti.com>
> 
> 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 at ti.com>
> ---
>   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 at 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
>   ------------------------------
>   
> 

Reviwed-by: Łukasz Majewski

-- 
Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de