Merge git://git.denx.de/u-boot-fdt

5 files changed, 355 insertions, 4 deletions

diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays
new file mode 100644
index 0000000000..39139cb850
--- /dev/null
+++ b/doc/README.fdt-overlays
@@ -0,0 +1,114 @@
+U-Boot FDT Overlay usage
+=============================================
+
+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
+overlapping anything.
+
+=> setenv fdtaddr 0x87f00000
+=> setenv fdtovaddr 0x87fc0000
+
+2. Load the base blob and overlay blobs
+
+=> load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
+=> load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtb
+
+3. Set it as the working fdt tree.
+
+=> fdtaddr $fdtaddr
+
+4. Grow it enough so it can 'fit' all the applied overlays
+
+=> fdt resize 8192
+
+5. You are now ready to apply the overlay.
+
+=> 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.
+
+Pantelis Antoniou
+pantelis.antoniou@konsulko.com
+11/7/2017
diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt
index 3ed8c759d6..732bc34f06 100644
--- a/doc/driver-model/of-plat.txt
+++ b/doc/driver-model/of-plat.txt
@@ -111,7 +111,7 @@ struct dtd_rockchip_rk3288_dw_mshc {
         bool            cap_sd_highspeed;
         fdt32_t         card_detect_delay;
         fdt32_t         clock_freq_min_max[2];
-        struct phandle_2_cell clocks[4];
+        struct phandle_1_arg clocks[4];
         bool            disable_wp;
         fdt32_t         fifo_depth;
         fdt32_t         interrupts[3];
diff --git a/doc/uImage.FIT/command_syntax_extensions.txt b/doc/uImage.FIT/command_syntax_extensions.txt
index 6c99b1c159..676f992f90 100644
--- a/doc/uImage.FIT/command_syntax_extensions.txt
+++ b/doc/uImage.FIT/command_syntax_extensions.txt
@@ -36,7 +36,7 @@ Old uImage:
 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 @@ following syntax:
 - 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 @@ bootm 200000:kernel@1
 - 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 0000000000..63e47da2a9
--- /dev/null
+++ b/doc/uImage.FIT/overlay-fdt-boot.txt
@@ -0,0 +1,225 @@
+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@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 32825eda8d..6f727a1e8a 100644
--- a/doc/uImage.FIT/source_file_format.txt
+++ b/doc/uImage.FIT/source_file_format.txt
@@ -235,7 +235,7 @@ o config@1
   |- 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 @@ o config@1
   - 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