Changes between Version 1 and Version 2 of newport/bootloader

Timestamp:

02/08/2018 09:04:07 PM (6 years ago)

Author:

Tim Harvey

Comment:

added distro-config, boot scripts, and FIT sections

newport/bootloader

@@ -74 +74 @@
 
 '''Note that {{{hwconfig}}} is also used for serial configuration so care should be taken to preserve that configuration if used''' 
+
+
+[=#distro-config]
+=== Distro Config ===
+The Newport Bootloader uses U-Boot's 'Distro Config' which is a well defined U-Boot env intended to make it easier for distro maintainers to develop compatible bootscripts. This primarily entails a set of 'boot scripts' and variables that control them.
+
+Ultimately this U-Boot environment is looking for a U-Boot [#bootscript boot script] on a 'bootable' partition (partitions with the 'boot' flag enabled). It searches in this order with these rules:
+ - **boot_targets** - list of target device type/nums to search: defaults to mmc0 mmc1 usb0 sata0
+ - **devplist** - ''dynamically created'' list of all partitions flagged as 'bootable'
+ - **boot_prefixes** - list of directories within a partition searched for bootscripts
+ - **boot_scripts** - list of boot script names searched for
+
+
+[=#bootscript]
+=== Boot Scripts ===
+When writing bootscripts compatible with [#distro-config Distro Config] you can assume the following env variables:
+ - **devtype** - the device type the script was loaded from (mmc|usb|sata)
+ - **devnum** - the device number the script was loaded from (ie 0 for mmc0, 1 for mmc1, etc)
+ - **distro_bootpart** - the partition number the script was loaded from (ie 0, 1, etc)
+ - **fdtcontroladdr** - the address the device-tree is at (Note that the Newport bootloader does not load/manipulate the device-tree itself - this is done by the SPL which loads/manipulates the device-tree and passes it to the bootloader)
+ - **kernel_addr_r** - address where kernel can be loaded
+ - **bootargs** - default bootargs to pass to the kernel - you probably want to add to this and not overwrite it
+ - **console** - the serial console device to pass to the kernel
+
+Additionally you should note the following:
+ - use load/ls/save commands which support FAT/ext filesystem types automatically instead of the fs specific commands
+ - if using a root filesystem that is not supported by the bootloader (ie F2FS or BTRFS) you can place your kernel image in the FAT12 filesystem on partition 1 of the boot device. This filesystem is part of the 16MB 'Boot Firmware' image. If doing so you will need to compress the kernel and package it into a [#fit FIT image] in order to fit it in the available space.
+
+The Distro-Config environment supports legacy uImage scripts (it does not support FIT images with scripts). You can create these with the {{{mkimage}}} tool from U-Boot as such:
+{{{#!bash
+mkimage -A arm64 -T script -C none -d ubuntu.txt newport.scr
+}}}
+
+You can then place the uImage {{{newport.scr}}} on a bootable partition such as the embedded FAT12 filesystem within the Newport boot firmware as such:
+{{{#!bash
+fatfs-tool -i firmware-newport.img cp newport.scr /
+}}}
+
+Alternatively this can be done at runtime on the target within Linux by mounting the FAT12 partition. For example:
+{{{#!bash
+mount /dev/mmcblk0p1 /mnt
+mkimage -A arm64 -T script -C none -d ubuntu.txt /mnt/newport.scr
+umount
+}}}
+
+
+[=#boot_targets]
+=== Boot Device Order (boot_targets) ===
+While the Newport product family can only boot its [wiki:newport/boot Boot Firmware] from an MMC device (ie eMMC or microSD), once you are booted to the bootloader you can choose from a wider variety of devices to boot the OS from.
+
+This OS boot device order is specified by the [#distro-config Distro Config] environment. Specifically it is controlled by the {{{boot_targets}}} env variable which defaults to {{{mmc0 mmc1 usb0 sata0}}}.
+
+For example, to limit OS booting to only SATA:
+{{{#!bash
+setenv boot_targets sata0
+saveenv
+}}}
+
+
+[=#fit]
+== Flattened Image Tree (FIT) images ==
+The U-Boot bootloader supports Flattened Image Tree (FIT) images which expand greatly on the legacy U-Boot image (uImage) format by allowing multiple binary blobs within an image. These blobs can be kernel images, ramdisk images, device-tree blobs, and bootloader scripts. Each image can also be optionally compressed (meaning U-Boot will decompress it) and check-sumed with a variety of hash mechanisms (meaning U-Boot will verify the image before using it).
+
+Quick summary of FIT Images:
+ * introduced to resolve limitations with original single-image formats and follow-on multi-image format supported by UBoot bootm (boot memory)
+ * uses power of the Device-Tree-Compiler (DTC)
+ * FIT .itb files can be created with mkimage by passing in a .its file which in device-tree notation describes the images
+ * U-Boot supports FIT with several commands:
+  - {{{source <addr>:<name>}}} # source a script by name from FIT image in memory
+  - {{{iminfo <fitaddress>}}} # print all the info contained in a FIT image in memory and verify (just not boot it)
+  - {{{imextract <fitaddress> <item> <addr>}}} # extract item (ie kernel@1) to addr
+  - {{{bootm <fitaddress>[#conf] - $fdtcontroladdr}}} # boot default or 'conf' configuration (ie #config@1)
+  - {{{bootm start <fitaddress>[#conf] - $fdtcontroladdr}}} # boot from memory a specific configuration (or default configuration) from FIT image
+
+Example:
+ * kernel.its with a single compressed kernel for ARM64 (used by Newport)
+{{{#!bash
+/dts-v1/;
+/ {
+        description = "Simple image with single Linux kernel";
+        #address-cells = <1>;
+        images {
+                kernel@1 {
+                        description = "ThunderX kernel";
+                        data = /incbin/("./Image.gz");
+                        type = "kernel";
+                        arch = "arm64";
+                        os = "linux";
+                        compression = "gzip";
+                        load = <0x40080000>;
+                        entry = <0x40080000>;
+                        hash@1 {
+                                algo = "sha256";
+                        };
+                };
+        };
+
+        configurations {
+                default = "conf@1";
+                conf@1 {
+                        description = "Boot Linux kernel";
+                        kernel = "kernel@1";
+                };
+        };
+};
+}}}
+ * create image:
+{{{#!bash
+cp arch/arm64/boot/Image .
+gzip Image
+mkimage -f kernel.its /tftpboot/kernel.itb
+}}}
+ * boot the default configuration from U-Boot:
+{{{#!bash
+tftpboot $loadaddr kernel.itb && setenv bootargs 'console=ttyAMA0,115200n8 earlycon=pl011,0x87e028000000 coherent_poll=64M root=/dev/mmcblk2 rootfstype=f2fs' && bootm $loadaddr - $fdtcontroladdr
+}}}
+
+
+References:
+ * [http://git.denx.de/?p=u-boot.git;a=tree;f=doc/uImage.FIT doc/uImage.FIT]
+ * http://www.denx.de/wiki/pub/U-Boot/Documentation/multi_image_booting_scenarios.pdf
+ * http://elinux.org/images/f/f4/Elc2013_Fernandes.pdf