doc: Bring in the FIT overlay information

Bring this file into the documentation.

Signed-off-by: Simon Glass <sjg@chromium.org>

diff --git a/doc/uImage.FIT/overlay-fdt-boot.txt b/doc/uImage.FIT/overlay-fdt-boot.txt
deleted file mode 100644 (file)
index dddc4db..0000000
--- a/doc/uImage.FIT/overlay-fdt-boot.txt
+++ /dev/null
@@ -1,225 +0,0 @@
-U-Boot FDT Overlay FIT usage
-============================
-
-Introduction
-------------
-In many cases it is desirable to have a single FIT image support a multitude
-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
-------------------------------
-
-Take a hypothetical board named 'foo' where there are different supported
-revisions, reva and revb. Assume that both board revisions can use add a bar
-add-on board, while only the revb board can use a baz add-on board.
-
-Without using overlays the configuration would be as follows for every case.
-
-       /dts-v1/;
-       / {
-               images {
-                       kernel {
-                               data = /incbin/("./zImage");
-                               type = "kernel";
-                               arch = "arm";
-                               os = "linux";
-                               load = <0x82000000>;
-                               entry = <0x82000000>;
-                       };
-                       fdt-1 {
-                               data = /incbin/("./foo-reva.dtb");
-                               type = "flat_dt";
-                               arch = "arm";
-                       };
-                       fdt-2 {
-                               data = /incbin/("./foo-revb.dtb");
-                               type = "flat_dt";
-                               arch = "arm";
-                       };
-                       fdt-3 {
-                               data = /incbin/("./foo-reva-bar.dtb");
-                               type = "flat_dt";
-                               arch = "arm";
-                       };
-                       fdt-4 {
-                               data = /incbin/("./foo-revb-bar.dtb");
-                               type = "flat_dt";
-                               arch = "arm";
-                       };
-                       fdt-5 {
-                               data = /incbin/("./foo-revb-baz.dtb");
-                               type = "flat_dt";
-                               arch = "arm";
-                       };
-                       fdt-6 {
-                               data = /incbin/("./foo-revb-bar-baz.dtb");
-                               type = "flat_dt";
-                               arch = "arm";
-                       };
-               };
-
-               configurations {
-                       default = "foo-reva.dtb;
-                       foo-reva.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-1";
-                       };
-                       foo-revb.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-2";
-                       };
-                       foo-reva-bar.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-3";
-                       };
-                       foo-revb-bar.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-4";
-                       };
-                       foo-revb-baz.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-5";
-                       };
-                       foo-revb-bar-baz.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-6";
-                       };
-               };
-       };
-
-Note the blob needs to be compiled for each case and the combinatorial explosion of
-configurations. A typical device tree blob is in the low hunderds of kbytes so a
-multitude of configuration grows the image quite a bit.
-
-Booting this image is done by using
-
-       # bootm <addr>#<config>
-
-Where config is one of:
-       foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
-       foo-revb-baz.dtb, foo-revb-bar-baz.dtb
-
-This selects the DTB to use when booting.
-
-Configuration using overlays
-----------------------------
-
-Device tree overlays can be applied to a base DT and result in the same blob
-being passed to the booting kernel. This saves on space and avoid the combinatorial
-explosion problem.
-
-       /dts-v1/;
-       / {
-               images {
-                       kernel {
-                               data = /incbin/("./zImage");
-                               type = "kernel";
-                               arch = "arm";
-                               os = "linux";
-                               load = <0x82000000>;
-                               entry = <0x82000000>;
-                       };
-                       fdt-1 {
-                               data = /incbin/("./foo.dtb");
-                               type = "flat_dt";
-                               arch = "arm";
-                               load = <0x87f00000>;
-                       };
-                       fdt-2 {
-                               data = /incbin/("./reva.dtbo");
-                               type = "flat_dt";
-                               arch = "arm";
-                               load = <0x87fc0000>;
-                       };
-                       fdt-3 {
-                               data = /incbin/("./revb.dtbo");
-                               type = "flat_dt";
-                               arch = "arm";
-                               load = <0x87fc0000>;
-                       };
-                       fdt-4 {
-                               data = /incbin/("./bar.dtbo");
-                               type = "flat_dt";
-                               arch = "arm";
-                               load = <0x87fc0000>;
-                       };
-                       fdt-5 {
-                               data = /incbin/("./baz.dtbo");
-                               type = "flat_dt";
-                               arch = "arm";
-                               load = <0x87fc0000>;
-                       };
-               };
-
-               configurations {
-                       default = "foo-reva.dtb;
-                       foo-reva.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-1", "fdt-2";
-                       };
-                       foo-revb.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-1", "fdt-3";
-                       };
-                       foo-reva-bar.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-1", "fdt-2", "fdt-4";
-                       };
-                       foo-revb-bar.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-1", "fdt-3", "fdt-4";
-                       };
-                       foo-revb-baz.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-1", "fdt-3", "fdt-5";
-                       };
-                       foo-revb-bar-baz.dtb {
-                               kernel = "kernel";
-                               fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5";
-                       };
-                       bar {
-                               fdt = "fdt-4";
-                       };
-                       baz {
-                               fdt = "fdt-5";
-                       };
-               };
-       };
-
-Booting this image is exactly the same as the non-overlay example.
-u-boot will retrieve the base blob and apply the overlays in sequence as
-they are declared in the configuration.
-
-Note the minimum amount of different DT blobs, as well as the requirement for
-the DT blobs to have a load address; the overlay application requires the blobs
-to be writeable.
-
-Configuration using overlays and feature selection
---------------------------------------------------
-
-Although the configuration in the previous section works is a bit inflexible
-since it requires all possible configuration options to be laid out before
-hand in the FIT image. For the add-on boards the extra config selection method
-might make sense.
-
-Note the two bar & baz configuration nodes. To boot a reva board with
-the bar add-on board enabled simply use:
-
-       # bootm <addr>#foo-reva.dtb#bar
-
-While booting a revb with bar and baz is as follows:
-
-       # bootm <addr>#foo-revb.dtb#bar#baz
-
-The limitation for a feature selection configuration node is that a single
-fdt option is currently supported.
-
-Pantelis Antoniou
-pantelis.antoniou@konsulko.com
-12/6/2017

diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
index 83bc4d01ca4250fc05499b978c8a69271aa66f04..bd25bd30b2840390e240c1ed4e9ba3982f6af639 100644 (file)
--- a/doc/usage/fit/index.rst
+++ b/doc/usage/fit/index.rst
@@ -16,3 +16,4 @@ doc/uImage.FIT
     signature
     verified-boot
     beaglebone_vboot
+    overlay-fdt-boot

diff --git a/doc/usage/fit/overlay-fdt-boot.rst b/doc/usage/fit/overlay-fdt-boot.rst
new file mode 100644 (file)
index 0000000..a7db1a3
--- /dev/null
+++ b/doc/usage/fit/overlay-fdt-boot.rst
@@ -0,0 +1,227 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+U-Boot FDT Overlay FIT usage
+============================
+
+Introduction
+------------
+
+In many cases it is desirable to have a single FIT image support a multitude
+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
+------------------------------
+
+Take a hypothetical board named 'foo' where there are different supported
+revisions, reva and revb. Assume that both board revisions can use add a bar
+add-on board, while only the revb board can use a baz add-on board.
+
+Without using overlays the configuration would be as follows for every case::
+
+       /dts-v1/;
+       / {
+           images {
+           kernel {
+               data = /incbin/("./zImage");
+               type = "kernel";
+               arch = "arm";
+               os = "linux";
+               load = <0x82000000>;
+               entry = <0x82000000>;
+           };
+           fdt-1 {
+               data = /incbin/("./foo-reva.dtb");
+               type = "flat_dt";
+               arch = "arm";
+           };
+           fdt-2 {
+               data = /incbin/("./foo-revb.dtb");
+               type = "flat_dt";
+               arch = "arm";
+           };
+           fdt-3 {
+               data = /incbin/("./foo-reva-bar.dtb");
+               type = "flat_dt";
+               arch = "arm";
+           };
+           fdt-4 {
+               data = /incbin/("./foo-revb-bar.dtb");
+               type = "flat_dt";
+               arch = "arm";
+           };
+           fdt-5 {
+               data = /incbin/("./foo-revb-baz.dtb");
+               type = "flat_dt";
+               arch = "arm";
+           };
+           fdt-6 {
+               data = /incbin/("./foo-revb-bar-baz.dtb");
+               type = "flat_dt";
+               arch = "arm";
+           };
+           };
+
+           configurations {
+           default = "foo-reva.dtb;
+           foo-reva.dtb {
+               kernel = "kernel";
+               fdt = "fdt-1";
+           };
+           foo-revb.dtb {
+               kernel = "kernel";
+               fdt = "fdt-2";
+           };
+           foo-reva-bar.dtb {
+               kernel = "kernel";
+               fdt = "fdt-3";
+           };
+           foo-revb-bar.dtb {
+               kernel = "kernel";
+               fdt = "fdt-4";
+           };
+           foo-revb-baz.dtb {
+               kernel = "kernel";
+               fdt = "fdt-5";
+           };
+           foo-revb-bar-baz.dtb {
+               kernel = "kernel";
+               fdt = "fdt-6";
+           };
+           };
+       };
+
+Note the blob needs to be compiled for each case and the combinatorial explosion of
+configurations. A typical device tree blob is in the low hunderds of kbytes so a
+multitude of configuration grows the image quite a bit.
+
+Booting this image is done by using::
+
+    # bootm <addr>#<config>
+
+Where config is one of::
+
+    foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
+    foo-revb-baz.dtb, foo-revb-bar-baz.dtb
+
+This selects the DTB to use when booting.
+
+Configuration using overlays
+----------------------------
+
+Device tree overlays can be applied to a base DT and result in the same blob
+being passed to the booting kernel. This saves on space and avoid the combinatorial
+explosion problem::
+
+    /dts-v1/;
+    / {
+        images {
+            kernel {
+                data = /incbin/("./zImage");
+                type = "kernel";
+                arch = "arm";
+                os = "linux";
+                load = <0x82000000>;
+                entry = <0x82000000>;
+            };
+            fdt-1 {
+                data = /incbin/("./foo.dtb");
+                type = "flat_dt";
+                arch = "arm";
+                load = <0x87f00000>;
+            };
+            fdt-2 {
+                data = /incbin/("./reva.dtbo");
+                type = "flat_dt";
+                arch = "arm";
+                load = <0x87fc0000>;
+            };
+            fdt-3 {
+                data = /incbin/("./revb.dtbo");
+                type = "flat_dt";
+                arch = "arm";
+                load = <0x87fc0000>;
+            };
+            fdt-4 {
+                data = /incbin/("./bar.dtbo");
+                type = "flat_dt";
+                arch = "arm";
+                load = <0x87fc0000>;
+            };
+            fdt-5 {
+                data = /incbin/("./baz.dtbo");
+                type = "flat_dt";
+                arch = "arm";
+                load = <0x87fc0000>;
+            };
+        };
+
+        configurations {
+            default = "foo-reva.dtb;
+            foo-reva.dtb {
+                kernel = "kernel";
+                fdt = "fdt-1", "fdt-2";
+            };
+            foo-revb.dtb {
+                kernel = "kernel";
+                fdt = "fdt-1", "fdt-3";
+            };
+            foo-reva-bar.dtb {
+                kernel = "kernel";
+                fdt = "fdt-1", "fdt-2", "fdt-4";
+            };
+            foo-revb-bar.dtb {
+                kernel = "kernel";
+                fdt = "fdt-1", "fdt-3", "fdt-4";
+            };
+            foo-revb-baz.dtb {
+                kernel = "kernel";
+                fdt = "fdt-1", "fdt-3", "fdt-5";
+            };
+            foo-revb-bar-baz.dtb {
+                kernel = "kernel";
+                fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5";
+            };
+            bar {
+                fdt = "fdt-4";
+            };
+            baz {
+                fdt = "fdt-5";
+            };
+        };
+    };
+
+Booting this image is exactly the same as the non-overlay example.
+u-boot will retrieve the base blob and apply the overlays in sequence as
+they are declared in the configuration.
+
+Note the minimum amount of different DT blobs, as well as the requirement for
+the DT blobs to have a load address; the overlay application requires the blobs
+to be writeable.
+
+Configuration using overlays and feature selection
+--------------------------------------------------
+
+Although the configuration in the previous section works is a bit inflexible
+since it requires all possible configuration options to be laid out before
+hand in the FIT image. For the add-on boards the extra config selection method
+might make sense.
+
+Note the two bar & baz configuration nodes. To boot a reva board with
+the bar add-on board enabled simply use::
+
+    => bootm <addr>#foo-reva.dtb#bar
+
+While booting a revb with bar and baz is as follows::
+
+    => bootm <addr>#foo-revb.dtb#bar#baz
+
+The limitation for a feature selection configuration node is that a single
+fdt option is currently supported.
+
+.. sectionauthor:: Pantelis Antoniou <pantelis.antoniou@konsulko.com>, 12/6/2017