fit: fdt overlays doc
Signed-off-by: Pantelis Antoniou <pantelis.antoniou@konsulko.com>
Reviewed-by: Łukasz Majewski
Acked-by: Simon Glass <sjg@chromium.org>
diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/uImage.FIT/command_syntax_extensions.txt
index 6c99b1c..676f992 100644
--- a/doc/uImage.FIT/command_syntax_extensions.txt
+++ b/doc/uImage.FIT/command_syntax_extensions.txt
@@ -36,7 +36,7 @@
New uImage:
8. bootm <addr1>
9. bootm [<addr1>]:<subimg1>
-10. bootm [<addr1>]#<conf>
+10. bootm [<addr1>]#<conf>[#<extra-conf[#...]]
11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
@@ -129,6 +129,12 @@
- new uImage configuration specification
<addr>#<configuration unit_name>
+- new uImage configuration specification with extra configuration components
+<addr>#<configuration unit_name>[#<extra configuration unit_name>[#..]]
+
+The extra configuration currently is supported only for additional device tree
+overlays to apply on the base device tree supplied by the first configuration
+unit.
Examples:
@@ -138,6 +144,10 @@
- boot configuration "cfg@1" from a new uImage located at 200000:
bootm 200000#cfg@1
+- boot configuration "cfg@1" with extra "cfg@2" from a new uImage located
+ at 200000:
+bootm 200000#cfg@1#cfg@2
+
- boot "kernel@1" from a new uImage at 200000 with initrd "ramdisk@2" found in
some other new uImage stored at address 800000:
bootm 200000:kernel@1 800000:ramdisk@2
diff --git a/doc/uImage.FIT/overlay-fdt-boot.txt b/doc/uImage.FIT/overlay-fdt-boot.txt
new file mode 100644
index 0000000..dbdf2a1
--- /dev/null
+++ b/doc/uImage.FIT/overlay-fdt-boot.txt
@@ -0,0 +1,221 @@
+U-Boot FDT Overlay 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.
+
+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@1 {
+ 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@1";
+ fdt = "fdt@1";
+ };
+ foo-revb.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@2";
+ };
+ foo-reva-bar.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@3";
+ };
+ foo-revb-bar.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@4";
+ };
+ foo-revb-baz.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@5";
+ };
+ foo-revb-bar-baz.dtb {
+ kernel = "kernel@1";
+ 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@1 {
+ 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@1";
+ fdt = "fdt@1", "fdt@2";
+ };
+ foo-revb.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@1", "fdt@3";
+ };
+ foo-reva-bar.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@1", "fdt@2", "fdt@4";
+ };
+ foo-revb-bar.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@1", "fdt@3", "fdt@4";
+ };
+ foo-revb-baz.dtb {
+ kernel = "kernel@1";
+ fdt = "fdt@1", "fdt@3", "fdt@5";
+ };
+ foo-revb-bar-baz.dtb {
+ kernel = "kernel@1";
+ 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/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt
index 32825ed..6f727a1 100644
--- a/doc/uImage.FIT/source_file_format.txt
+++ b/doc/uImage.FIT/source_file_format.txt
@@ -235,7 +235,7 @@
|- description = "configuration description"
|- kernel = "kernel sub-node unit name"
|- ramdisk = "ramdisk sub-node unit name"
- |- fdt = "fdt sub-node unit-name"
+ |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
|- fpga = "fpga sub-node unit-name"
|- loadables = "loadables sub-node unit-name"
@@ -249,7 +249,9 @@
- ramdisk : Unit name of the corresponding ramdisk image (component image
node of a "ramdisk" type).
- fdt : Unit name of the corresponding fdt blob (component image node of a
- "fdt type").
+ "fdt type"). Additional fdt overlay nodes can be supplied which signify
+ that the resulting device tree blob is generated by the first base fdt
+ blob with all subsequent overlays applied.
- setup : Unit name of the corresponding setup binary (used for booting
an x86 kernel). This contains the setup.bin file built by the kernel.
- fpga : Unit name of the corresponding fpga bitstream blob