From 0d15463c0537806f70ea2359e32e4deb8c4766c2 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 29 Aug 2017 14:15:56 -0600 Subject: dtoc: Rename the phandle struct Rather than naming the phandle struct according to the number of cells it uses (e.g. struct phandle_2_cell) name it according to the number of arguments it has (e.g. struct phandle_1_arg). This is a more intuitive naming. Signed-off-by: Simon Glass Tested-by: Kever Yang --- doc/driver-model/of-plat.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt index 3ed8c75..732bc34 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]; -- cgit v1.1 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 --- doc/uImage.FIT/command_syntax_extensions.txt | 12 +- doc/uImage.FIT/overlay-fdt-boot.txt | 221 +++++++++++++++++++++++++++ doc/uImage.FIT/source_file_format.txt | 6 +- 3 files changed, 236 insertions(+), 3 deletions(-) create mode 100644 doc/uImage.FIT/overlay-fdt-boot.txt (limited to 'doc') 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 v1.1 From d80162cfc559491dee3009b120e7268e9388302f Mon Sep 17 00:00:00 2001 From: Pantelis Antoniou Date: Mon, 4 Sep 2017 23:12:18 +0300 Subject: doc: Document how to apply fdt overlays MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We have the capability to apply overlays on the command line but we didn't have a document explaining how. Signed-off-by: Pantelis Antoniou Reviewed-by: Łukasz Majewski Acked-by: Simon Glass --- doc/README.fdt-overlays | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 doc/README.fdt-overlays (limited to 'doc') diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays new file mode 100644 index 0000000..ee868ec --- /dev/null +++ b/doc/README.fdt-overlays @@ -0,0 +1,37 @@ +U-Boot FDT Overlay usage (without FIT images) +============================================= + +FDT overlays are now available for use even without FIT images. +It is not as automagic as with FIT images though and require a few +manual steps. + +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 + +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 -- cgit v1.1 From 56fc7032e1771882a086e8283586fc7c733ba6bd Mon Sep 17 00:00:00 2001 From: Franklin S Cooper Jr Date: Mon, 4 Sep 2017 23:12:19 +0300 Subject: doc: overlays: Tweak documentation regarding overlays Pull some information regarding overlays from commit messages and put them directly within the documentation. Also add some information regarding required dtc version to properly use overlays. Signed-off-by: Franklin S Cooper Jr Acked-by: Simon Glass --- doc/README.fdt-overlays | 85 +++++++++++++++++++++++++++++++++++-- doc/uImage.FIT/overlay-fdt-boot.txt | 8 +++- 2 files changed, 87 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/README.fdt-overlays b/doc/README.fdt-overlays index ee868ec..39139cb 100644 --- a/doc/README.fdt-overlays +++ b/doc/README.fdt-overlays @@ -1,9 +1,76 @@ -U-Boot FDT Overlay usage (without FIT images) +U-Boot FDT Overlay usage ============================================= -FDT overlays are now available for use even without FIT images. -It is not as automagic as with FIT images though and require a few -manual steps. +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 @@ -29,6 +96,16 @@ overlapping anything. => 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. diff --git a/doc/uImage.FIT/overlay-fdt-boot.txt b/doc/uImage.FIT/overlay-fdt-boot.txt index dbdf2a1..63e47da 100644 --- a/doc/uImage.FIT/overlay-fdt-boot.txt +++ b/doc/uImage.FIT/overlay-fdt-boot.txt @@ -1,5 +1,5 @@ -U-Boot FDT Overlay usage -======================== +U-Boot FDT Overlay FIT usage +============================ Introduction ------------ @@ -8,6 +8,10 @@ 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 ------------------------------ -- cgit v1.1