fit: fdt overlays doc

Signed-off-by: Pantelis Antoniou <pantelis.antoniou@konsulko.com> Reviewed-by: Łukasz Majewski Acked-by: Simon Glass <sjg@chromium.org>

fit: fdt overlays doc
Signed-off-by: Pantelis Antoniou <pantelis.antoniou@konsulko.com> Reviewed-by: Łukasz Majewski Acked-by: Simon Glass <sjg@chromium.org>
Pantelis Antoniou · Simon Glass
1 parent 169043d826
Showing 3 changed files with 236 additions and 3 deletions Side-by-side Diff
doc/uImage.FIT/command_syntax_extensions.txt
doc/uImage.FIT/overlay-fdt-boot.txt
doc/uImage.FIT/source_file_format.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,7 +129,13 @@
 - 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:
  
 - boot kernel "kernel@1" stored in a new uImage located at 200000:
@@ -137,6 +143,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:
+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
@@ -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
...	...	@@ -36,7 +36,7 @@
36	36	New uImage:
37	37	8. bootm <addr1>
38	38	9. bootm [<addr1>]:<subimg1>
39		-10. bootm [<addr1>]#<conf>
	39	+10. bootm [<addr1>]#<conf>[#<extra-conf[#...]]
40	40	11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
41	41	12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
42	42	13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
43	43
...	...	@@ -129,7 +129,13 @@
129	129	- new uImage configuration specification
130	130	<addr>#<configuration unit_name>
131	131
	132	+- new uImage configuration specification with extra configuration components
	133	+<addr>#<configuration unit_name>[#<extra configuration unit_name>[#..]]
132	134
	135	+The extra configuration currently is supported only for additional device tree
	136	+overlays to apply on the base device tree supplied by the first configuration
	137	+unit.
	138	+
133	139	Examples:
134	140
135	141	- boot kernel "kernel@1" stored in a new uImage located at 200000:
...	...	@@ -137,6 +143,10 @@
137	143
138	144	- boot configuration "cfg@1" from a new uImage located at 200000:
139	145	bootm 200000#cfg@1
	146	+
	147	+- boot configuration "cfg@1" with extra "cfg@2" from a new uImage located
	148	+ at 200000:
	149	+bootm 200000#cfg@1#cfg@2
140	150
141	151	- boot "kernel@1" from a new uImage at 200000 with initrd "ramdisk@2" found in
142	152	some other new uImage stored at address 800000:
	1	+U-Boot FDT Overlay usage
	2	+========================
	3	+
	4	+Introduction
	5	+------------
	6	+In many cases it is desirable to have a single FIT image support a multitude
	7	+of similar boards and their expansion options. The same kernel on DT enabled
	8	+platforms can support this easily enough by providing a DT blob upon boot
	9	+that matches the desired configuration.
	10	+
	11	+Configuration without overlays
	12	+------------------------------
	13	+
	14	+Take a hypothetical board named 'foo' where there are different supported
	15	+revisions, reva and revb. Assume that both board revisions can use add a bar
	16	+add-on board, while only the revb board can use a baz add-on board.
	17	+
	18	+Without using overlays the configuration would be as follows for every case.
	19	+
	20	+ /dts-v1/;
	21	+ / {
	22	+ images {
	23	+ kernel@1 {
	24	+ data = /incbin/("./zImage");
	25	+ type = "kernel";
	26	+ arch = "arm";
	27	+ os = "linux";
	28	+ load = <0x82000000>;
	29	+ entry = <0x82000000>;
	30	+ };
	31	+ fdt@1 {
	32	+ data = /incbin/("./foo-reva.dtb");
	33	+ type = "flat_dt";
	34	+ arch = "arm";
	35	+ };
	36	+ fdt@2 {
	37	+ data = /incbin/("./foo-revb.dtb");
	38	+ type = "flat_dt";
	39	+ arch = "arm";
	40	+ };
	41	+ fdt@3 {
	42	+ data = /incbin/("./foo-reva-bar.dtb");
	43	+ type = "flat_dt";
	44	+ arch = "arm";
	45	+ };
	46	+ fdt@4 {
	47	+ data = /incbin/("./foo-revb-bar.dtb");
	48	+ type = "flat_dt";
	49	+ arch = "arm";
	50	+ };
	51	+ fdt@5 {
	52	+ data = /incbin/("./foo-revb-baz.dtb");
	53	+ type = "flat_dt";
	54	+ arch = "arm";
	55	+ };
	56	+ fdt@6 {
	57	+ data = /incbin/("./foo-revb-bar-baz.dtb");
	58	+ type = "flat_dt";
	59	+ arch = "arm";
	60	+ };
	61	+ };
	62	+
	63	+ configurations {
	64	+ default = "foo-reva.dtb;
	65	+ foo-reva.dtb {
	66	+ kernel = "kernel@1";
	67	+ fdt = "fdt@1";
	68	+ };
	69	+ foo-revb.dtb {
	70	+ kernel = "kernel@1";
	71	+ fdt = "fdt@2";
	72	+ };
	73	+ foo-reva-bar.dtb {
	74	+ kernel = "kernel@1";
	75	+ fdt = "fdt@3";
	76	+ };
	77	+ foo-revb-bar.dtb {
	78	+ kernel = "kernel@1";
	79	+ fdt = "fdt@4";
	80	+ };
	81	+ foo-revb-baz.dtb {
	82	+ kernel = "kernel@1";
	83	+ fdt = "fdt@5";
	84	+ };
	85	+ foo-revb-bar-baz.dtb {
	86	+ kernel = "kernel@1";
	87	+ fdt = "fdt@6";
	88	+ };
	89	+ };
	90	+ };
	91	+
	92	+Note the blob needs to be compiled for each case and the combinatorial explosion of
	93	+configurations. A typical device tree blob is in the low hunderds of kbytes so a
	94	+multitude of configuration grows the image quite a bit.
	95	+
	96	+Booting this image is done by using
	97	+
	98	+ # bootm <addr>#<config>
	99	+
	100	+Where config is one of:
	101	+ foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
	102	+ foo-revb-baz.dtb, foo-revb-bar-baz.dtb
	103	+
	104	+This selects the DTB to use when booting.
	105	+
	106	+Configuration using overlays
	107	+----------------------------
	108	+
	109	+Device tree overlays can be applied to a base DT and result in the same blob
	110	+being passed to the booting kernel. This saves on space and avoid the combinatorial
	111	+explosion problem.
	112	+
	113	+ /dts-v1/;
	114	+ / {
	115	+ images {
	116	+ kernel@1 {
	117	+ data = /incbin/("./zImage");
	118	+ type = "kernel";
	119	+ arch = "arm";
	120	+ os = "linux";
	121	+ load = <0x82000000>;
	122	+ entry = <0x82000000>;
	123	+ };
	124	+ fdt@1 {
	125	+ data = /incbin/("./foo.dtb");
	126	+ type = "flat_dt";
	127	+ arch = "arm";
	128	+ load = <0x87f00000>;
	129	+ };
	130	+ fdt@2 {
	131	+ data = /incbin/("./reva.dtbo");
	132	+ type = "flat_dt";
	133	+ arch = "arm";
	134	+ load = <0x87fc0000>;
	135	+ };
	136	+ fdt@3 {
	137	+ data = /incbin/("./revb.dtbo");
	138	+ type = "flat_dt";
	139	+ arch = "arm";
	140	+ load = <0x87fc0000>;
	141	+ };
	142	+ fdt@4 {
	143	+ data = /incbin/("./bar.dtbo");
	144	+ type = "flat_dt";
	145	+ arch = "arm";
	146	+ load = <0x87fc0000>;
	147	+ };
	148	+ fdt@5 {
	149	+ data = /incbin/("./baz.dtbo");
	150	+ type = "flat_dt";
	151	+ arch = "arm";
	152	+ load = <0x87fc0000>;
	153	+ };
	154	+ };
	155	+
	156	+ configurations {
	157	+ default = "foo-reva.dtb;
	158	+ foo-reva.dtb {
	159	+ kernel = "kernel@1";
	160	+ fdt = "fdt@1", "fdt@2";
	161	+ };
	162	+ foo-revb.dtb {
	163	+ kernel = "kernel@1";
	164	+ fdt = "fdt@1", "fdt@3";
	165	+ };
	166	+ foo-reva-bar.dtb {
	167	+ kernel = "kernel@1";
	168	+ fdt = "fdt@1", "fdt@2", "fdt@4";
	169	+ };
	170	+ foo-revb-bar.dtb {
	171	+ kernel = "kernel@1";
	172	+ fdt = "fdt@1", "fdt@3", "fdt@4";
	173	+ };
	174	+ foo-revb-baz.dtb {
	175	+ kernel = "kernel@1";
	176	+ fdt = "fdt@1", "fdt@3", "fdt@5";
	177	+ };
	178	+ foo-revb-bar-baz.dtb {
	179	+ kernel = "kernel@1";
	180	+ fdt = "fdt@1", "fdt@3", "fdt@4", "fdt@5";
	181	+ };
	182	+ bar {
	183	+ fdt = "fdt@4";
	184	+ };
	185	+ baz {
	186	+ fdt = "fdt@5";
	187	+ };
	188	+ };
	189	+ };
	190	+
	191	+Booting this image is exactly the same as the non-overlay example.
	192	+u-boot will retrieve the base blob and apply the overlays in sequence as
	193	+they are declared in the configuration.
	194	+
	195	+Note the minimum amount of different DT blobs, as well as the requirement for
	196	+the DT blobs to have a load address; the overlay application requires the blobs
	197	+to be writeable.
	198	+
	199	+Configuration using overlays and feature selection
	200	+--------------------------------------------------
	201	+
	202	+Although the configuration in the previous section works is a bit inflexible
	203	+since it requires all possible configuration options to be laid out before
	204	+hand in the FIT image. For the add-on boards the extra config selection method
	205	+might make sense.
	206	+
	207	+Note the two bar & baz configuration nodes. To boot a reva board with
	208	+the bar add-on board enabled simply use:
	209	+
	210	+ # bootm <addr>#foo-reva.dtb#bar
	211	+
	212	+While booting a revb with bar and baz is as follows:
	213	+
	214	+ # bootm <addr>#foo-revb.dtb#bar#baz
	215	+
	216	+The limitation for a feature selection configuration node is that a single
	217	+fdt option is currently supported.
	218	+
	219	+Pantelis Antoniou
	220	+pantelis.antoniou@konsulko.com
	221	+12/6/2017
...	...	@@ -235,7 +235,7 @@
235	235	\|- description = "configuration description"
236	236	\|- kernel = "kernel sub-node unit name"
237	237	\|- ramdisk = "ramdisk sub-node unit name"
238		- \|- fdt = "fdt sub-node unit-name"
	238	+ \|- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
239	239	\|- fpga = "fpga sub-node unit-name"
240	240	\|- loadables = "loadables sub-node unit-name"
241	241
...	...	@@ -249,7 +249,9 @@
249	249	- ramdisk : Unit name of the corresponding ramdisk image (component image
250	250	node of a "ramdisk" type).
251	251	- fdt : Unit name of the corresponding fdt blob (component image node of a
252		- "fdt type").
	252	+ "fdt type"). Additional fdt overlay nodes can be supplied which signify
	253	+ that the resulting device tree blob is generated by the first base fdt
	254	+ blob with all subsequent overlays applied.
253	255	- setup : Unit name of the corresponding setup binary (used for booting
254	256	an x86 kernel). This contains the setup.bin file built by the kernel.
255	257	- fpga : Unit name of the corresponding fpga bitstream blob