From 6b54e50b5a5889efe179cb06aa6aa25583ef25d5 Mon Sep 17 00:00:00 2001 From: Pantelis Antoniou Date: Mon, 4 Sep 2017 23:12:17 +0300 Subject: fit: fdt overlays doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pantelis Antoniou Reviewed-by: Łukasz Majewski Acked-by: Simon Glass 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 @@ Old uImage: New uImage: 8. bootm 9. bootm []: -10. bootm []# +10. bootm []#[#]: []: 12. bootm []: []: []: 13. bootm []: []: @@ -129,6 +129,12 @@ following syntax: - new uImage configuration specification # +- new uImage configuration specification with extra configuration components +#[#[#..]] + +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 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 # + +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 #foo-reva.dtb#bar + +While booting a revb with bar and baz is as follows: + + # bootm #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 @@ 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 -- cgit v0.10.2