From: Simon Glass Date: Fri, 23 Jun 2023 12:22:04 +0000 (+0100) Subject: doc: Bring in the FIT examples X-Git-Url: http://git.dujemihanovic.xyz/html/index.html?a=commitdiff_plain;h=ba399ce2142ab14c772ca258fa10276095846835;p=u-boot.git doc: Bring in the FIT examples Convert these to rST format and add them to the index. Signed-off-by: Simon Glass --- diff --git a/doc/uImage.FIT/kernel.its b/doc/uImage.FIT/kernel.its deleted file mode 100644 index 77ddf622de..0000000000 --- a/doc/uImage.FIT/kernel.its +++ /dev/null @@ -1,91 +0,0 @@ -/* - * Simple U-Boot uImage source file containing a single kernel - */ - -/dts-v1/; - -/ { - description = "Simple image with single Linux kernel"; - #address-cells = <1>; - - images { - kernel { - description = "Vanilla Linux kernel"; - data = /incbin/("./vmlinux.bin.gz"); - type = "kernel"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "crc32"; - }; - hash-2 { - algo = "sha1"; - }; - }; - }; - - configurations { - default = "config-1"; - config-1 { - description = "Boot Linux kernel"; - kernel = "kernel"; - }; - }; -}; - - - -For x86 a setup node is also required: see x86-fit-boot.txt. - -/dts-v1/; - -/ { - description = "Simple image with single Linux kernel on x86"; - #address-cells = <1>; - - images { - kernel { - description = "Vanilla Linux kernel"; - data = /incbin/("./image.bin.lzo"); - type = "kernel"; - arch = "x86"; - os = "linux"; - compression = "lzo"; - load = <0x01000000>; - entry = <0x00000000>; - hash-2 { - algo = "sha1"; - }; - }; - - setup { - description = "Linux setup.bin"; - data = /incbin/("./setup.bin"); - type = "x86_setup"; - arch = "x86"; - os = "linux"; - compression = "none"; - load = <0x00090000>; - entry = <0x00090000>; - hash-2 { - algo = "sha1"; - }; - }; - }; - - configurations { - default = "config-1"; - config-1 { - description = "Boot Linux kernel"; - kernel = "kernel"; - setup = "setup"; - }; - }; -}; - -Note: the above assumes a 32-bit kernel. To directly boot a 64-bit kernel, -change both arch values to "x86_64". U-Boot will then change to 64-bit mode -before booting the kernel (see boot_linux_kernel()). diff --git a/doc/uImage.FIT/kernel_fdt.its b/doc/uImage.FIT/kernel_fdt.its deleted file mode 100644 index 000d85b8e0..0000000000 --- a/doc/uImage.FIT/kernel_fdt.its +++ /dev/null @@ -1,51 +0,0 @@ -/* - * Simple U-Boot uImage source file containing a single kernel and FDT blob - */ - -/dts-v1/; - -/ { - description = "Simple image with single Linux kernel and FDT blob"; - #address-cells = <1>; - - images { - kernel { - description = "Vanilla Linux kernel"; - data = /incbin/("./vmlinux.bin.gz"); - type = "kernel"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "crc32"; - }; - hash-2 { - algo = "sha1"; - }; - }; - fdt-1 { - description = "Flattened Device Tree blob"; - data = /incbin/("./target.dtb"); - type = "flat_dt"; - arch = "ppc"; - compression = "none"; - hash-1 { - algo = "crc32"; - }; - hash-2 { - algo = "sha1"; - }; - }; - }; - - configurations { - default = "conf-1"; - conf-1 { - description = "Boot Linux kernel with FDT blob"; - kernel = "kernel"; - fdt = "fdt-1"; - }; - }; -}; diff --git a/doc/uImage.FIT/kernel_fdts_compressed.its b/doc/uImage.FIT/kernel_fdts_compressed.its deleted file mode 100644 index 8f81106efc..0000000000 --- a/doc/uImage.FIT/kernel_fdts_compressed.its +++ /dev/null @@ -1,73 +0,0 @@ -/* - * U-Boot uImage source file with a kernel and multiple compressed FDT blobs. - * Since the FDTs are compressed, configurations must provide a compatible - * string to match directly. - */ - -/dts-v1/; - -/ { - description = "Image with single Linux kernel and compressed FDT blobs"; - #address-cells = <1>; - - images { - kernel { - description = "Vanilla Linux kernel"; - data = /incbin/("./vmlinux.bin.gz"); - type = "kernel"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "crc32"; - }; - hash-2 { - algo = "sha1"; - }; - }; - fdt@1 { - description = "Flattened Device Tree blob 1"; - data = /incbin/("./myboard-var1.dtb"); - type = "flat_dt"; - arch = "ppc"; - compression = "gzip"; - hash-1 { - algo = "crc32"; - }; - hash-2 { - algo = "sha1"; - }; - }; - fdt@2 { - description = "Flattened Device Tree blob 2"; - data = /incbin/("./myboard-var2.dtb"); - type = "flat_dt"; - arch = "ppc"; - compression = "lzma"; - hash-1 { - algo = "crc32"; - }; - hash-2 { - algo = "sha1"; - }; - }; - }; - - configurations { - default = "conf@1"; - conf@1 { - description = "Boot Linux kernel with FDT blob 1"; - kernel = "kernel"; - fdt = "fdt@1"; - compatible = "myvendor,myboard-variant1"; - }; - conf@2 { - description = "Boot Linux kernel with FDT blob 2"; - kernel = "kernel"; - fdt = "fdt@2"; - compatible = "myvendor,myboard-variant2"; - }; - }; -}; diff --git a/doc/uImage.FIT/multi-with-fpga.its b/doc/uImage.FIT/multi-with-fpga.its deleted file mode 100644 index 021cbc7cf4..0000000000 --- a/doc/uImage.FIT/multi-with-fpga.its +++ /dev/null @@ -1,68 +0,0 @@ -/* - * U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs - * This example makes use of the 'loadables' field - */ - -/dts-v1/; - -/ { - description = "Configuration to load fpga before Kernel"; - #address-cells = <1>; - - images { - fdt-1 { - description = "zc706"; - data = /incbin/("/tftpboot/devicetree.dtb"); - type = "flat_dt"; - arch = "arm"; - compression = "none"; - load = <0x10000000>; - hash-1 { - algo = "md5"; - }; - }; - - fpga { - description = "FPGA"; - data = /incbin/("/tftpboot/download.bit"); - type = "fpga"; - arch = "arm"; - compression = "none"; - load = <0x30000000>; - compatible = "u-boot,fpga-legacy" - hash-1 { - algo = "md5"; - }; - }; - - linux_kernel { - description = "Linux"; - data = /incbin/("/tftpboot/zImage"); - type = "kernel"; - arch = "arm"; - os = "linux"; - compression = "none"; - load = <0x8000>; - entry = <0x8000>; - hash-1 { - algo = "md5"; - }; - }; - }; - - configurations { - default = "config-2"; - config-1 { - description = "Linux"; - kernel = "linux_kernel"; - fdt = "fdt-1"; - }; - - config-2 { - description = "Linux with fpga"; - kernel = "linux_kernel"; - fdt = "fdt-1"; - loadables = "fpga"; - }; - }; -}; diff --git a/doc/uImage.FIT/multi-with-loadables.its b/doc/uImage.FIT/multi-with-loadables.its deleted file mode 100644 index 4d4909f832..0000000000 --- a/doc/uImage.FIT/multi-with-loadables.its +++ /dev/null @@ -1,89 +0,0 @@ -/* - * U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs - * This example makes use of the 'loadables' field - */ - -/dts-v1/; - -/ { - description = "Configuration to load a Xen Kernel"; - #address-cells = <1>; - - images { - xen_kernel { - description = "xen binary"; - data = /incbin/("./xen"); - type = "kernel"; - arch = "arm"; - os = "linux"; - compression = "none"; - load = <0xa0000000>; - entry = <0xa0000000>; - hash-1 { - algo = "md5"; - }; - }; - - fdt-1 { - description = "xexpress-ca15 tree blob"; - data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); - type = "flat_dt"; - arch = "arm"; - compression = "none"; - load = <0xb0000000>; - hash-1 { - algo = "md5"; - }; - }; - - fdt-2 { - description = "xexpress-ca15 tree blob"; - data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); - type = "flat_dt"; - arch = "arm"; - compression = "none"; - load = <0xb0400000>; - hash-1 { - algo = "md5"; - }; - }; - - linux_kernel { - description = "Linux Image"; - data = /incbin/("./Image"); - type = "kernel"; - arch = "arm"; - os = "linux"; - compression = "none"; - load = <0xa0000000>; - entry = <0xa0000000>; - hash-1 { - algo = "md5"; - }; - }; - }; - - configurations { - default = "config-2"; - - config-1 { - description = "Just plain Linux"; - kernel = "linux_kernel"; - fdt = "fdt-1"; - }; - - config-2 { - description = "Xen one loadable"; - kernel = "xen_kernel"; - fdt = "fdt-1"; - loadables = "linux_kernel"; - }; - - config-3 { - description = "Xen two loadables"; - kernel = "xen_kernel"; - fdt = "fdt-1"; - loadables = "linux_kernel", "fdt-2"; - }; - }; -}; diff --git a/doc/uImage.FIT/multi.its b/doc/uImage.FIT/multi.its deleted file mode 100644 index 26c8dad6a2..0000000000 --- a/doc/uImage.FIT/multi.its +++ /dev/null @@ -1,133 +0,0 @@ -/* - * U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs - */ - -/dts-v1/; - -/ { - description = "Various kernels, ramdisks and FDT blobs"; - #address-cells = <1>; - - images { - kernel-1 { - description = "vanilla-2.6.23"; - data = /incbin/("./vmlinux.bin.gz"); - type = "kernel"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "md5"; - }; - hash-2 { - algo = "sha1"; - }; - }; - - kernel-2 { - description = "2.6.23-denx"; - data = /incbin/("./2.6.23-denx.bin.gz"); - type = "kernel"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "sha1"; - }; - }; - - kernel-3 { - description = "2.4.25-denx"; - data = /incbin/("./2.4.25-denx.bin.gz"); - type = "kernel"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "md5"; - }; - }; - - ramdisk-1 { - description = "eldk-4.2-ramdisk"; - data = /incbin/("./eldk-4.2-ramdisk"); - type = "ramdisk"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "sha1"; - }; - }; - - ramdisk-2 { - description = "eldk-3.1-ramdisk"; - data = /incbin/("./eldk-3.1-ramdisk"); - type = "ramdisk"; - arch = "ppc"; - os = "linux"; - compression = "gzip"; - load = <00000000>; - entry = <00000000>; - hash-1 { - algo = "crc32"; - }; - }; - - fdt-1 { - description = "tqm5200-fdt"; - data = /incbin/("./tqm5200.dtb"); - type = "flat_dt"; - arch = "ppc"; - compression = "none"; - hash-1 { - algo = "crc32"; - }; - }; - - fdt-2 { - description = "tqm5200s-fdt"; - data = /incbin/("./tqm5200s.dtb"); - type = "flat_dt"; - arch = "ppc"; - compression = "none"; - load = <00700000>; - hash-1 { - algo = "sha1"; - }; - }; - - }; - - configurations { - default = "config-1"; - - config-1 { - description = "tqm5200 vanilla-2.6.23 configuration"; - kernel = "kernel-1"; - ramdisk = "ramdisk-1"; - fdt = "fdt-1"; - }; - - config-2 { - description = "tqm5200s denx-2.6.23 configuration"; - kernel = "kernel-2"; - ramdisk = "ramdisk-1"; - fdt = "fdt-2"; - }; - - config-3 { - description = "tqm5200s denx-2.4.25 configuration"; - kernel = "kernel-3"; - ramdisk = "ramdisk-2"; - }; - }; -}; diff --git a/doc/uImage.FIT/multi_spl.its b/doc/uImage.FIT/multi_spl.its deleted file mode 100644 index 5942199744..0000000000 --- a/doc/uImage.FIT/multi_spl.its +++ /dev/null @@ -1,96 +0,0 @@ -/dts-v1/; - -/* - * (Bogus) example FIT image description file demonstrating the usage - * of multiple images loaded by the SPL. - * Several binaries will be loaded at their respective load addresses. - * - * For booting U-Boot, "firmware" is searched first. If not found, "loadables" - * is used to identify images to be loaded into memory. If falcon boot is - * enabled, "kernel" is searched first. If not found, it falls back to the - * same flow as booting U-Boot. Changing image type will result skipping - * specific image. - * - * Finally the one image specifying an entry point will be entered by the SPL. - */ - -/ { - description = "multiple firmware blobs and U-Boot, loaded by SPL"; - #address-cells = <0x1>; - - images { - - uboot { - description = "U-Boot (64-bit)"; - type = "standalone"; - arch = "arm64"; - compression = "none"; - load = <0x4a000000>; - }; - - atf { - description = "ARM Trusted Firmware"; - type = "firmware"; - arch = "arm64"; - compression = "none"; - load = <0x18000>; - entry = <0x18000>; - }; - - mgmt-firmware { - description = "arisc management processor firmware"; - type = "firmware"; - arch = "or1k"; - compression = "none"; - load = <0x40000>; - }; - - fdt-1 { - description = "Pine64+ DT"; - type = "flat_dt"; - compression = "none"; - load = <0x4fa00000>; - arch = "arm64"; - }; - - fdt-2 { - description = "Pine64 DT"; - type = "flat_dt"; - compression = "none"; - load = <0x4fa00000>; - arch = "arm64"; - }; - - kernel { - description = "4.7-rc5 kernel"; - type = "kernel"; - compression = "none"; - load = <0x40080000>; - arch = "arm64"; - }; - - initrd { - description = "Debian installer initrd"; - type = "ramdisk"; - compression = "none"; - load = <0x4fe00000>; - arch = "arm64"; - }; - }; - - configurations { - default = "config-1"; - - config-1 { - description = "sun50i-a64-pine64-plus"; - loadables = "uboot", "atf", "kernel", "initrd"; - fdt = "fdt-1"; - }; - - config-2 { - description = "sun50i-a64-pine64"; - loadables = "uboot", "atf", "mgmt-firmware"; - fdt = "fdt-2"; - }; - }; -}; diff --git a/doc/uImage.FIT/sec_firmware_ppa.its b/doc/uImage.FIT/sec_firmware_ppa.its deleted file mode 100644 index a7acde17cf..0000000000 --- a/doc/uImage.FIT/sec_firmware_ppa.its +++ /dev/null @@ -1,49 +0,0 @@ -/dts-v1/; - -/* - * Example FIT image description file demonstrating the usage - * of SEC Firmware and multiple loadable images loaded by the u-boot. - * For booting PPA (SEC Firmware), "firmware" is searched and loaded. - * - * Multiple binaries will be loaded as "loadables" (if present) at their - * respective load offsets from firmware image address. - */ - -/{ - description = "PPA Firmware"; - #address-cells = <1>; - images { - firmware@1 { - description = "PPA Firmware: "; - data = /incbin/("../obj/monitor.bin"); - type = "firmware"; - arch = "arm64"; - compression = "none"; - }; - trustedOS@1 { - description = "Trusted OS"; - data = /incbin/("../../tee.bin"); - type = "OS"; - arch = "arm64"; - compression = "none"; - load = <0x00200000>; - }; - fuse_scr { - description = "Fuse Script"; - data = /incbin/("../../fuse_scr.bin"); - type = "firmware"; - arch = "arm64"; - compression = "none"; - load = <0x00180000>; - }; - }; - - configurations { - default = "config-1"; - config-1 { - description = "PPA Secure firmware"; - firmware = "firmware@1"; - loadables = "trustedOS@1", "fuse_scr"; - }; - }; -}; diff --git a/doc/uImage.FIT/sign-configs.its b/doc/uImage.FIT/sign-configs.its deleted file mode 100644 index 9e992c1988..0000000000 --- a/doc/uImage.FIT/sign-configs.its +++ /dev/null @@ -1,45 +0,0 @@ -/dts-v1/; - -/ { - description = "Chrome OS kernel image with one or more FDT blobs"; - #address-cells = <1>; - - images { - kernel { - data = /incbin/("test-kernel.bin"); - type = "kernel_noload"; - arch = "sandbox"; - os = "linux"; - compression = "lzo"; - load = <0x4>; - entry = <0x8>; - kernel-version = <1>; - hash-1 { - algo = "sha1"; - }; - }; - fdt-1 { - description = "snow"; - data = /incbin/("sandbox-kernel.dtb"); - type = "flat_dt"; - arch = "sandbox"; - compression = "none"; - fdt-version = <1>; - hash-1 { - algo = "sha1"; - }; - }; - }; - configurations { - default = "conf-1"; - conf-1 { - kernel = "kernel"; - fdt = "fdt-1"; - signature { - algo = "sha1,rsa2048"; - key-name-hint = "dev"; - sign-images = "fdt", "kernel"; - }; - }; - }; -}; diff --git a/doc/uImage.FIT/sign-images.its b/doc/uImage.FIT/sign-images.its deleted file mode 100644 index 18c759e9e6..0000000000 --- a/doc/uImage.FIT/sign-images.its +++ /dev/null @@ -1,42 +0,0 @@ -/dts-v1/; - -/ { - description = "Chrome OS kernel image with one or more FDT blobs"; - #address-cells = <1>; - - images { - kernel { - data = /incbin/("test-kernel.bin"); - type = "kernel_noload"; - arch = "sandbox"; - os = "linux"; - compression = "none"; - load = <0x4>; - entry = <0x8>; - kernel-version = <1>; - signature { - algo = "sha1,rsa2048"; - key-name-hint = "dev"; - }; - }; - fdt-1 { - description = "snow"; - data = /incbin/("sandbox-kernel.dtb"); - type = "flat_dt"; - arch = "sandbox"; - compression = "none"; - fdt-version = <1>; - signature { - algo = "sha1,rsa2048"; - key-name-hint = "dev"; - }; - }; - }; - configurations { - default = "conf-1"; - conf-1 { - kernel = "kernel"; - fdt = "fdt-1"; - }; - }; -}; diff --git a/doc/uImage.FIT/uefi.its b/doc/uImage.FIT/uefi.its deleted file mode 100644 index 378ca4ed8d..0000000000 --- a/doc/uImage.FIT/uefi.its +++ /dev/null @@ -1,67 +0,0 @@ -/* - * Example FIT image description file demonstrating the usage of the - * bootm command to launch UEFI binaries. - * - * Two boot configurations are available to enable booting GRUB2 on QEMU, - * the former uses a FDT blob contained in the FIT image, while the later - * relies on the FDT provided by the board emulator. - */ - -/dts-v1/; - -/ { - description = "GRUB2 EFI and QEMU FDT blob"; - #address-cells = <1>; - - images { - efi-grub { - description = "GRUB EFI Firmware"; - data = /incbin/("bootarm.efi"); - type = "kernel_noload"; - arch = "arm"; - os = "efi"; - compression = "none"; - load = <0x0>; - entry = <0x0>; - hash-1 { - algo = "sha256"; - }; - }; - - fdt-qemu { - description = "QEMU DTB"; - data = /incbin/("qemu-arm.dtb"); - type = "flat_dt"; - arch = "arm"; - compression = "none"; - hash-1 { - algo = "sha256"; - }; - }; - }; - - configurations { - default = "config-grub-fdt"; - - config-grub-fdt { - description = "GRUB EFI Boot w/ FDT"; - kernel = "efi-grub"; - fdt = "fdt-qemu"; - signature-1 { - algo = "sha256,rsa2048"; - key-name-hint = "dev"; - sign-images = "kernel", "fdt"; - }; - }; - - config-grub-nofdt { - description = "GRUB EFI Boot w/o FDT"; - kernel = "efi-grub"; - signature-1 { - algo = "sha256,rsa2048"; - key-name-hint = "dev"; - sign-images = "kernel"; - }; - }; - }; -}; diff --git a/doc/uImage.FIT/update3.its b/doc/uImage.FIT/update3.its deleted file mode 100644 index 0659f20002..0000000000 --- a/doc/uImage.FIT/update3.its +++ /dev/null @@ -1,44 +0,0 @@ -/* - * Example Automatic software update file. - */ - -/dts-v1/; - -/ { - description = "Automatic software updates: kernel, ramdisk, FDT"; - #address-cells = <1>; - - images { - update-1 { - description = "Linux kernel binary"; - data = /incbin/("./vmlinux.bin.gz"); - compression = "none"; - type = "firmware"; - load = ; - hash-1 { - algo = "sha1"; - }; - }; - update-2 { - description = "Ramdisk image"; - data = /incbin/("./ramdisk_image.gz"); - compression = "none"; - type = "firmware"; - load = ; - hash-1 { - algo = "sha1"; - }; - }; - - update-3 { - description = "FDT blob"; - data = /incbin/("./blob.fdt"); - compression = "none"; - type = "firmware"; - load = ; - hash-1 { - algo = "sha1"; - }; - }; - }; -}; diff --git a/doc/uImage.FIT/update_uboot.its b/doc/uImage.FIT/update_uboot.its deleted file mode 100644 index aec4826008..0000000000 --- a/doc/uImage.FIT/update_uboot.its +++ /dev/null @@ -1,24 +0,0 @@ -/* - * Automatic software update for U-Boot - * Make sure the flashing addresses ('load' prop) is correct for your board! - */ - -/dts-v1/; - -/ { - description = "Automatic U-Boot update"; - #address-cells = <1>; - - images { - update-1 { - description = "U-Boot binary"; - data = /incbin/("./u-boot.bin"); - compression = "none"; - type = "firmware"; - load = <0xFFFC0000>; - hash-1 { - algo = "sha1"; - }; - }; - }; -}; diff --git a/doc/usage/fit/kernel.rst b/doc/usage/fit/kernel.rst new file mode 100644 index 0000000000..012a81efea --- /dev/null +++ b/doc/usage/fit/kernel.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Single kernel +============= + +:: + + /dts-v1/; + + / { + description = "Simple image with single Linux kernel"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot Linux kernel"; + kernel = "kernel"; + }; + }; + }; + + +For x86 a setup node is also required: see x86-fit-boot:: + + /dts-v1/; + + / { + description = "Simple image with single Linux kernel on x86"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./image.bin.lzo"); + type = "kernel"; + arch = "x86"; + os = "linux"; + compression = "lzo"; + load = <0x01000000>; + entry = <0x00000000>; + hash-2 { + algo = "sha1"; + }; + }; + + setup { + description = "Linux setup.bin"; + data = /incbin/("./setup.bin"); + type = "x86_setup"; + arch = "x86"; + os = "linux"; + compression = "none"; + load = <0x00090000>; + entry = <0x00090000>; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot Linux kernel"; + kernel = "kernel"; + setup = "setup"; + }; + }; + }; + +Note: the above assumes a 32-bit kernel. To directly boot a 64-bit kernel, +change both arch values to "x86_64". U-Boot will then change to 64-bit mode +before booting the kernel (see boot_linux_kernel()). diff --git a/doc/usage/fit/kernel_fdt.rst b/doc/usage/fit/kernel_fdt.rst new file mode 100644 index 0000000000..8eee13af78 --- /dev/null +++ b/doc/usage/fit/kernel_fdt.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Single kernel and FDT blob +========================== + +:: + + /dts-v1/; + + / { + description = "Simple image with single Linux kernel and FDT blob"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + fdt-1 { + description = "Flattened Device Tree blob"; + data = /incbin/("./target.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "conf-1"; + conf-1 { + description = "Boot Linux kernel with FDT blob"; + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; + }; diff --git a/doc/usage/fit/kernel_fdts_compressed.rst b/doc/usage/fit/kernel_fdts_compressed.rst new file mode 100644 index 0000000000..0b169c7c27 --- /dev/null +++ b/doc/usage/fit/kernel_fdts_compressed.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Kernel and multiple compressed FDT blobs +======================================== + +Since the FDTs are compressed, configurations must provide a compatible +string to match directly. + +:: + + /dts-v1/; + + / { + description = "Image with single Linux kernel and compressed FDT blobs"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + fdt@1 { + description = "Flattened Device Tree blob 1"; + data = /incbin/("./myboard-var1.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "gzip"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + fdt@2 { + description = "Flattened Device Tree blob 2"; + data = /incbin/("./myboard-var2.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "lzma"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha1"; + }; + }; + }; + + configurations { + default = "conf@1"; + conf@1 { + description = "Boot Linux kernel with FDT blob 1"; + kernel = "kernel"; + fdt = "fdt@1"; + compatible = "myvendor,myboard-variant1"; + }; + conf@2 { + description = "Boot Linux kernel with FDT blob 2"; + kernel = "kernel"; + fdt = "fdt@2"; + compatible = "myvendor,myboard-variant2"; + }; + }; + }; diff --git a/doc/usage/fit/multi-with-fpga.rst b/doc/usage/fit/multi-with-fpga.rst new file mode 100644 index 0000000000..28d7d5d262 --- /dev/null +++ b/doc/usage/fit/multi-with-fpga.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple kernels, ramdisks and FDT blobs with FPGA +================================================== + +This example makes use of the 'loadables' field:: + + /dts-v1/; + + / { + description = "Configuration to load fpga before Kernel"; + #address-cells = <1>; + + images { + fdt-1 { + description = "zc706"; + data = /incbin/("/tftpboot/devicetree.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0x10000000>; + hash-1 { + algo = "md5"; + }; + }; + + fpga { + description = "FPGA"; + data = /incbin/("/tftpboot/download.bit"); + type = "fpga"; + arch = "arm"; + compression = "none"; + load = <0x30000000>; + compatible = "u-boot,fpga-legacy" + hash-1 { + algo = "md5"; + }; + }; + + linux_kernel { + description = "Linux"; + data = /incbin/("/tftpboot/zImage"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0x8000>; + entry = <0x8000>; + hash-1 { + algo = "md5"; + }; + }; + }; + + configurations { + default = "config-2"; + config-1 { + description = "Linux"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + }; + + config-2 { + description = "Linux with fpga"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + loadables = "fpga"; + }; + }; + }; diff --git a/doc/usage/fit/multi-with-loadables.rst b/doc/usage/fit/multi-with-loadables.rst new file mode 100644 index 0000000000..a0241df96c --- /dev/null +++ b/doc/usage/fit/multi-with-loadables.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple kernels, ramdisks and FDT blobs with Xen +================================================= + +This example makes use of the 'loadables' field:: + + /dts-v1/; + + / { + description = "Configuration to load a Xen Kernel"; + #address-cells = <1>; + + images { + xen_kernel { + description = "xen binary"; + data = /incbin/("./xen"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0xa0000000>; + entry = <0xa0000000>; + hash-1 { + algo = "md5"; + }; + }; + + fdt-1 { + description = "xexpress-ca15 tree blob"; + data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0xb0000000>; + hash-1 { + algo = "md5"; + }; + }; + + fdt-2 { + description = "xexpress-ca15 tree blob"; + data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0xb0400000>; + hash-1 { + algo = "md5"; + }; + }; + + linux_kernel { + description = "Linux Image"; + data = /incbin/("./Image"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0xa0000000>; + entry = <0xa0000000>; + hash-1 { + algo = "md5"; + }; + }; + }; + + configurations { + default = "config-2"; + + config-1 { + description = "Just plain Linux"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + }; + + config-2 { + description = "Xen one loadable"; + kernel = "xen_kernel"; + fdt = "fdt-1"; + loadables = "linux_kernel"; + }; + + config-3 { + description = "Xen two loadables"; + kernel = "xen_kernel"; + fdt = "fdt-1"; + loadables = "linux_kernel", "fdt-2"; + }; + }; + }; diff --git a/doc/usage/fit/multi.rst b/doc/usage/fit/multi.rst new file mode 100644 index 0000000000..2e6ae58c40 --- /dev/null +++ b/doc/usage/fit/multi.rst @@ -0,0 +1,136 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple kernels, ramdisks and FDT blobs +======================================== + +:: + + /dts-v1/; + + / { + description = "Various kernels, ramdisks and FDT blobs"; + #address-cells = <1>; + + images { + kernel-1 { + description = "vanilla-2.6.23"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "md5"; + }; + hash-2 { + algo = "sha1"; + }; + }; + + kernel-2 { + description = "2.6.23-denx"; + data = /incbin/("./2.6.23-denx.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha1"; + }; + }; + + kernel-3 { + description = "2.4.25-denx"; + data = /incbin/("./2.4.25-denx.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "md5"; + }; + }; + + ramdisk-1 { + description = "eldk-4.2-ramdisk"; + data = /incbin/("./eldk-4.2-ramdisk"); + type = "ramdisk"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha1"; + }; + }; + + ramdisk-2 { + description = "eldk-3.1-ramdisk"; + data = /incbin/("./eldk-3.1-ramdisk"); + type = "ramdisk"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + }; + + fdt-1 { + description = "tqm5200-fdt"; + data = /incbin/("./tqm5200.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + hash-1 { + algo = "crc32"; + }; + }; + + fdt-2 { + description = "tqm5200s-fdt"; + data = /incbin/("./tqm5200s.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + load = <00700000>; + hash-1 { + algo = "sha1"; + }; + }; + + }; + + configurations { + default = "config-1"; + + config-1 { + description = "tqm5200 vanilla-2.6.23 configuration"; + kernel = "kernel-1"; + ramdisk = "ramdisk-1"; + fdt = "fdt-1"; + }; + + config-2 { + description = "tqm5200s denx-2.6.23 configuration"; + kernel = "kernel-2"; + ramdisk = "ramdisk-1"; + fdt = "fdt-2"; + }; + + config-3 { + description = "tqm5200s denx-2.4.25 configuration"; + kernel = "kernel-3"; + ramdisk = "ramdisk-2"; + }; + }; + }; diff --git a/doc/usage/fit/multi_spl.rst b/doc/usage/fit/multi_spl.rst new file mode 100644 index 0000000000..74b6f865ab --- /dev/null +++ b/doc/usage/fit/multi_spl.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple images for SPL +======================= + +(Bogus) example FIT image description file demonstrating the usage +of multiple images loaded by the SPL. +Several binaries will be loaded at their respective load addresses. + +For booting U-Boot, "firmware" is searched first. If not found, "loadables" +is used to identify images to be loaded into memory. If falcon boot is +enabled, "kernel" is searched first. If not found, it falls back to the +same flow as booting U-Boot. Changing image type will result skipping +specific image. + +Finally the one image specifying an entry point will be entered by the SPL. + +:: + + /dts-v1/; + + / { + description = "multiple firmware blobs and U-Boot, loaded by SPL"; + #address-cells = <0x1>; + + images { + + uboot { + description = "U-Boot (64-bit)"; + type = "standalone"; + arch = "arm64"; + compression = "none"; + load = <0x4a000000>; + }; + + atf { + description = "ARM Trusted Firmware"; + type = "firmware"; + arch = "arm64"; + compression = "none"; + load = <0x18000>; + entry = <0x18000>; + }; + + mgmt-firmware { + description = "arisc management processor firmware"; + type = "firmware"; + arch = "or1k"; + compression = "none"; + load = <0x40000>; + }; + + fdt-1 { + description = "Pine64+ DT"; + type = "flat_dt"; + compression = "none"; + load = <0x4fa00000>; + arch = "arm64"; + }; + + fdt-2 { + description = "Pine64 DT"; + type = "flat_dt"; + compression = "none"; + load = <0x4fa00000>; + arch = "arm64"; + }; + + kernel { + description = "4.7-rc5 kernel"; + type = "kernel"; + compression = "none"; + load = <0x40080000>; + arch = "arm64"; + }; + + initrd { + description = "Debian installer initrd"; + type = "ramdisk"; + compression = "none"; + load = <0x4fe00000>; + arch = "arm64"; + }; + }; + + configurations { + default = "config-1"; + + config-1 { + description = "sun50i-a64-pine64-plus"; + loadables = "uboot", "atf", "kernel", "initrd"; + fdt = "fdt-1"; + }; + + config-2 { + description = "sun50i-a64-pine64"; + loadables = "uboot", "atf", "mgmt-firmware"; + fdt = "fdt-2"; + }; + }; + }; diff --git a/doc/usage/fit/sec_firmware_ppa.rst b/doc/usage/fit/sec_firmware_ppa.rst new file mode 100644 index 0000000000..4cb292cb4e --- /dev/null +++ b/doc/usage/fit/sec_firmware_ppa.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +SEC Firmware and multiple loadable images +========================================= + +Example FIT image description file demonstrating the usage +of SEC Firmware and multiple loadable images loaded by U-Boot. +For booting PPA (SEC Firmware), "firmware" is searched and loaded. + +Multiple binaries will be loaded as "loadables" (if present) at their +respective load offsets from firmware image address. + +:: + + /dts-v1/; + + /{ + description = "PPA Firmware"; + #address-cells = <1>; + images { + firmware@1 { + description = "PPA Firmware: "; + data = /incbin/("../obj/monitor.bin"); + type = "firmware"; + arch = "arm64"; + compression = "none"; + }; + trustedOS@1 { + description = "Trusted OS"; + data = /incbin/("../../tee.bin"); + type = "OS"; + arch = "arm64"; + compression = "none"; + load = <0x00200000>; + }; + fuse_scr { + description = "Fuse Script"; + data = /incbin/("../../fuse_scr.bin"); + type = "firmware"; + arch = "arm64"; + compression = "none"; + load = <0x00180000>; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "PPA Secure firmware"; + firmware = "firmware@1"; + loadables = "trustedOS@1", "fuse_scr"; + }; + }; + }; diff --git a/doc/usage/fit/sign-configs.rst b/doc/usage/fit/sign-configs.rst new file mode 100644 index 0000000000..6a3df8f2c5 --- /dev/null +++ b/doc/usage/fit/sign-configs.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Signed configurations +===================== + +:: + + /dts-v1/; + + / { + description = "Chrome OS kernel image with one or more FDT blobs"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("test-kernel.bin"); + type = "kernel_noload"; + arch = "sandbox"; + os = "linux"; + compression = "lzo"; + load = <0x4>; + entry = <0x8>; + kernel-version = <1>; + hash-1 { + algo = "sha1"; + }; + }; + fdt-1 { + description = "snow"; + data = /incbin/("sandbox-kernel.dtb"); + type = "flat_dt"; + arch = "sandbox"; + compression = "none"; + fdt-version = <1>; + hash-1 { + algo = "sha1"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + signature { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + sign-images = "fdt", "kernel"; + }; + }; + }; + }; diff --git a/doc/usage/fit/sign-images.rst b/doc/usage/fit/sign-images.rst new file mode 100644 index 0000000000..7d54d702c9 --- /dev/null +++ b/doc/usage/fit/sign-images.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Signed Images +============= + +:: + + /dts-v1/; + + / { + description = "Chrome OS kernel image with one or more FDT blobs"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("test-kernel.bin"); + type = "kernel_noload"; + arch = "sandbox"; + os = "linux"; + compression = "none"; + load = <0x4>; + entry = <0x8>; + kernel-version = <1>; + signature { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + }; + }; + fdt-1 { + description = "snow"; + data = /incbin/("sandbox-kernel.dtb"); + type = "flat_dt"; + arch = "sandbox"; + compression = "none"; + fdt-version = <1>; + signature { + algo = "sha1,rsa2048"; + key-name-hint = "dev"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; + }; diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst index 7842256c22..e27377342a 100644 --- a/doc/usage/fit/source_file_format.rst +++ b/doc/usage/fit/source_file_format.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0+ + U-Boot new uImage source file format (bindings definition) ========================================================== @@ -386,7 +388,8 @@ data-offset store is placed immediately after the last byte of the device tree binary, aligned to a 4-byte boundary. -data-size : size of the data in bytes +data-size + size of the data in bytes The 'data-offset' property can be substituted with 'data-position', which defines an absolute position or address as the offset. This is helpful when @@ -405,7 +408,25 @@ structure and data to 512 byte, other values available for other align size. Examples -------- -Please see `doc/uImage.FIT/*.its` for actual image source files. +Some example files are available here, showing various scenarios + +.. toctree:: + :maxdepth: 1 + + kernel + kernel_fdt + kernel_fdts_compressed + kernel + multi + multi_spl + multi-with-fpga + multi-with-loadables + sec_firmware_ppa + sign-configs + sign-images + uefi + update3 + update_uboot .. sectionauthor:: Marian Balakowicz .. sectionauthor:: External data additions, 25/1/16 Simon Glass diff --git a/doc/usage/fit/uefi.rst b/doc/usage/fit/uefi.rst new file mode 100644 index 0000000000..3bbacb5cad --- /dev/null +++ b/doc/usage/fit/uefi.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +UEFI +==== + +Example FIT image description file demonstrating the usage of the +bootm command to launch UEFI binaries. + +Two boot configurations are available to enable booting GRUB2 on QEMU, +the former uses a FDT blob contained in the FIT image, while the later +relies on the FDT provided by the board emulator. + +:: + + /dts-v1/; + + / { + description = "GRUB2 EFI and QEMU FDT blob"; + #address-cells = <1>; + + images { + efi-grub { + description = "GRUB EFI Firmware"; + data = /incbin/("bootarm.efi"); + type = "kernel_noload"; + arch = "arm"; + os = "efi"; + compression = "none"; + load = <0x0>; + entry = <0x0>; + hash-1 { + algo = "sha256"; + }; + }; + + fdt-qemu { + description = "QEMU DTB"; + data = /incbin/("qemu-arm.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-grub-fdt"; + + config-grub-fdt { + description = "GRUB EFI Boot w/ FDT"; + kernel = "efi-grub"; + fdt = "fdt-qemu"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "kernel", "fdt"; + }; + }; + + config-grub-nofdt { + description = "GRUB EFI Boot w/o FDT"; + kernel = "efi-grub"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "kernel"; + }; + }; + }; + }; diff --git a/doc/usage/fit/update3.rst b/doc/usage/fit/update3.rst new file mode 100644 index 0000000000..4ff3950c01 --- /dev/null +++ b/doc/usage/fit/update3.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Automatic software update: multiple files +========================================= + +:: + + /dts-v1/; + + / { + description = "Automatic software updates: kernel, ramdisk, FDT"; + #address-cells = <1>; + + images { + update-1 { + description = "Linux kernel binary"; + data = /incbin/("./vmlinux.bin.gz"); + compression = "none"; + type = "firmware"; + load = ; + hash-1 { + algo = "sha1"; + }; + }; + update-2 { + description = "Ramdisk image"; + data = /incbin/("./ramdisk_image.gz"); + compression = "none"; + type = "firmware"; + load = ; + hash-1 { + algo = "sha1"; + }; + }; + + update-3 { + description = "FDT blob"; + data = /incbin/("./blob.fdt"); + compression = "none"; + type = "firmware"; + load = ; + hash-1 { + algo = "sha1"; + }; + }; + }; + }; diff --git a/doc/usage/fit/update_uboot.rst b/doc/usage/fit/update_uboot.rst new file mode 100644 index 0000000000..a9288ee636 --- /dev/null +++ b/doc/usage/fit/update_uboot.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Automatic software update +========================= + +Make sure the flashing addresses ('load' prop) is correct for your board! + +:: + + /dts-v1/; + + / { + description = "Automatic U-Boot update"; + #address-cells = <1>; + + images { + update-1 { + description = "U-Boot binary"; + data = /incbin/("./u-boot.bin"); + compression = "none"; + type = "firmware"; + load = <0xFFFC0000>; + hash-1 { + algo = "sha1"; + }; + }; + }; + };