At the moment we ignore any errors due to missing FIT properties, instead go ahead and calculate our addresses with the -1 return value. Fix this and bail out if any of the mandatory properties are missing.

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Simon Glass sjg@chromium.org --- common/spl/spl_fit.c | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/common/spl/spl_fit.c b/common/spl/spl_fit.c index 85af980..ecd42d8 100644 --- a/common/spl/spl_fit.c +++ b/common/spl/spl_fit.c @@ -11,14 +11,17 @@ #include <libfdt.h> #include <spl.h>

+#define FDT_ERROR ((ulong)(-1)) + static ulong fdt_getprop_u32(const void *fdt, int node, const char *prop) { const u32 *cell; int len;

cell = fdt_getprop(fdt, node, prop, &len); - if (len != sizeof(*cell)) - return -1U; + if (!cell || len != sizeof(*cell)) + return FDT_ERROR; + return fdt32_to_cpu(*cell); }

@@ -222,7 +225,11 @@ int spl_load_simple_fit(struct spl_image_info *spl_image,

/* Get its information and set up the spl_image structure */ data_offset = fdt_getprop_u32(fit, node, "data-offset"); + if (data_offset == FDT_ERROR) + return -ENOENT; data_size = fdt_getprop_u32(fit, node, "data-size"); + if (data_size == FDT_ERROR) + return -ENOENT; load = fdt_getprop_u32(fit, node, "load"); debug("data_offset=%x, data_size=%x\n", data_offset, data_size); spl_image->load_addr = load; @@ -265,6 +272,10 @@ int spl_load_simple_fit(struct spl_image_info *spl_image, } fdt_offset = fdt_getprop_u32(fit, node, "data-offset"); fdt_len = fdt_getprop_u32(fit, node, "data-size"); + if (fdt_offset == FDT_ERROR || fdt_len == FDT_ERROR) { + debug("%s: cannot load FDT data\n" __func__); + return -ENOENT; + }

/* * Read the device tree and place it after the image. There may be

So far we were not using the FIT image format to its full potential: The SPL FIT loader was just loading the first image from the /images node plus one of the listed DTBs. Now with the refactored loader code it's easy to load an arbitrary number of images in addition to the two mentioned above. As described in the FIT image source file format description, iterate over all images listed at the "loadables" property in the configuration node and load every image at its desired location. This allows to load any kind of images: - firmware images to execute before U-Boot proper (for instance ARM Trusted Firmware (ATF)) - firmware images for management processors (SCP, arisc, ...) - firmware images for devices like WiFi controllers - bit files for FPGAs - additional configuration data - kernels and/or ramdisks The actual usage of this feature would be platform and/or board specific.

Also update the FIT documentation to mention the new SPL feature and provide an example .its file to demonstrate its features.

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Lokesh Vutla lokeshvuta@ti.com Reviewed-by: Simon Glass sjg@chromium.org --- common/spl/spl_fit.c | 42 ++++++++++++++++++++- doc/uImage.FIT/howto.txt | 21 +++++++++++ doc/uImage.FIT/multi_spl.its | 89 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 2 deletions(-) create mode 100644 doc/uImage.FIT/multi_spl.its

diff --git a/common/spl/spl_fit.c b/common/spl/spl_fit.c index 9d9338c..4c42a96 100644 --- a/common/spl/spl_fit.c +++ b/common/spl/spl_fit.c @@ -234,6 +234,7 @@ int spl_load_simple_fit(struct spl_image_info *spl_image, struct spl_image_info image_info; int node, images, ret; int base_offset, align_len = ARCH_DMA_MINALIGN - 1; + int index = 0;

/* * Figure out where the external images start. This is the base for the @@ -278,6 +279,11 @@ int spl_load_simple_fit(struct spl_image_info *spl_image, if (node < 0) { debug("could not find firmware image, trying loadables...\n"); node = spl_fit_get_image_node(fit, images, "loadables", 0); + /* + * If we pick the U-Boot image from "loadables", start at + * the second image when later loading additional images. + */ + index = 1; } if (node < 0) { debug("%s: Cannot find u-boot image node: %d\n", @@ -305,6 +311,38 @@ int spl_load_simple_fit(struct spl_image_info *spl_image, * Align the destination address to ARCH_DMA_MINALIGN. */ image_info.load_addr = spl_image->load_addr + spl_image->size; - return spl_load_fit_image(info, sector, fit, base_offset, node, - &image_info); + ret = spl_load_fit_image(info, sector, fit, base_offset, node, + &image_info); + if (ret < 0) + return ret; + + /* Now check if there are more images for us to load */ + for (; ; index++) { + node = spl_fit_get_image_node(fit, images, "loadables", index); + if (node < 0) + break; + + ret = spl_load_fit_image(info, sector, fit, base_offset, node, + &image_info); + if (ret < 0) + continue; + + /* + * If the "firmware" image did not provide an entry point, + * use the first valid entry point from the loadables. + */ + if (spl_image->entry_point == FDT_ERROR && + image_info.entry_point != FDT_ERROR) + spl_image->entry_point = image_info.entry_point; + } + + /* + * If a platform does not provide CONFIG_SYS_UBOOT_START, U-Boot's + * Makefile will set it to 0 and it will end up as the entry point + * here. What it actually means is: use the load address. + */ + if (spl_image->entry_point == FDT_ERROR || spl_image->entry_point == 0) + spl_image->entry_point = spl_image->load_addr; + + return 0; } diff --git a/doc/uImage.FIT/howto.txt b/doc/uImage.FIT/howto.txt index 14e316f..2988a52 100644 --- a/doc/uImage.FIT/howto.txt +++ b/doc/uImage.FIT/howto.txt @@ -44,6 +44,27 @@ image source file mkimage + dtc transfer to target + ---------------> image file --------------------> bootm image data file(s)

+SPL usage +--------- + +The SPL can make use of the new image format as well, this traditionally +is used to ship multiple device tree files within one image. Code in the SPL +will choose the one matching the current board and append this to the +U-Boot proper binary to be automatically used up by it. +Aside from U-Boot proper and one device tree blob the SPL can load multiple, +arbitrary image files as well. These binaries should be specified in their +own subnode under the /images node, which should then be referenced from one or +multiple /configurations subnodes. The required images must be enumerated in +the "loadables" property as a list of strings. + +If a platform specific image source file (.its) is shipped with the U-Boot +source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol. +In this case it will be automatically used by U-Boot's Makefile to generate +the image. +If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR +can point to a script which generates this image source file during +the build process. It gets passed a list of device tree files (taken from the +CONFIG_OF_LIST symbol).

Example 1 -- old-style (non-FDT) kernel booting ----------------------------------------------- diff --git a/doc/uImage.FIT/multi_spl.its b/doc/uImage.FIT/multi_spl.its new file mode 100644 index 0000000..e5551d4 --- /dev/null +++ b/doc/uImage.FIT/multi_spl.its @@ -0,0 +1,89 @@ +/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. + * 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"; + }; + }; +};

Not every SoC needs to set up the GIC interrupt controller, so link think code only when the respective config option is set. This shaves off some bytes from the SPL code size.

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Simon Glass sjg@chromium.org --- arch/arm/lib/Makefile | 2 ++ 1 file changed, 2 insertions(+)

diff --git a/arch/arm/lib/Makefile b/arch/arm/lib/Makefile index 6e96cfb..4efa37b 100644 --- a/arch/arm/lib/Makefile +++ b/arch/arm/lib/Makefile @@ -44,7 +44,9 @@ ifdef CONFIG_CPU_V7M obj-y += interrupts_m.o else ifdef CONFIG_ARM64 obj-y += ccn504.o +ifneq ($(CONFIG_GICV2)$(CONFIG_GICV3),) obj-y += gic_64.o +endif obj-y += interrupts_64.o else obj-y += interrupts.o

The SPL stack is usually located at the end of SRAM A1, where it grows towards the end of the SPL. For the really big AArch64 binaries the stack overwrites code pretty soon, so move the SPL stack to the end of SRAM A2, which is unused at this time.

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Simon Glass sjg@chromium.org Acked-by: Maxime Ripard maxime.ripard@free-electrons.com --- include/configs/sunxi-common.h | 5 +++++ 1 file changed, 5 insertions(+)

diff --git a/include/configs/sunxi-common.h b/include/configs/sunxi-common.h index 64a1900..6b56776 100644 --- a/include/configs/sunxi-common.h +++ b/include/configs/sunxi-common.h @@ -187,7 +187,12 @@ #ifdef CONFIG_SUNXI_HIGH_SRAM #define CONFIG_SPL_TEXT_BASE 0x10040 /* sram start+header */ #define CONFIG_SPL_MAX_SIZE 0x7fc0 /* 32 KiB */ +#ifdef CONFIG_ARM64 +/* end of SRAM A2 for now, as SRAM A1 is pretty tight for an ARM64 build */ +#define LOW_LEVEL_SRAM_STACK 0x00054000 +#else #define LOW_LEVEL_SRAM_STACK 0x00018000 +#endif /* !CONFIG_ARM64 */ #else #define CONFIG_SPL_TEXT_BASE 0x40 /* sram start+header */ #define CONFIG_SPL_MAX_SIZE 0x5fc0 /* 24KB on sun4i/sun7i */

For a board or platform to support FIT loading in the SPL, it has to provide a board_fit_config_name_match() routine, which helps to select one of possibly multiple DTBs contained in a FIT image. Provide a simple function which chooses the DT name U-Boot was configured with. If the DT name is one of the two Pine64 versions, determine the exact model by checking the DRAM size.

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Simon Glass sjg@chromium.org Acked-by: Maxime Ripard maxime.ripard@free-electrons.com --- board/sunxi/board.c | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)

diff --git a/board/sunxi/board.c b/board/sunxi/board.c index c6fcb4c..5bb7b53 100644 --- a/board/sunxi/board.c +++ b/board/sunxi/board.c @@ -749,3 +749,26 @@ int ft_board_setup(void *blob, bd_t *bd) #endif return 0; } + +#ifdef CONFIG_SPL_LOAD_FIT +int board_fit_config_name_match(const char *name) +{ + const char *cmp_str; + +#ifdef CONFIG_DEFAULT_DEVICE_TREE + cmp_str = CONFIG_DEFAULT_DEVICE_TREE; +#else + return 0; +#endif + +/* Differentiate the two Pine64 board DTs by their DRAM size. */ + if (strstr(name, "-pine64") && strstr(cmp_str, "-pine64")) { + if ((gd->ram_size > 512 * 1024 * 1024)) + return !strstr(name, "plus"); + else + return !!strstr(name, "plus"); + } else { + return strcmp(name, cmp_str); + } +} +#endif

Now that the Makefile can call a generator script to build a more advanced FIT image, let's use this feature to address the needs of Allwinner boards with 64-bit SoCs (A64 and H5). The (DTB stripped) U-Boot binary and the ATF are static, but we allow an arbitrary number of supported device trees to be passed. The script enters both a DT entry in the /images node and the respective subnode in /configurations to support all listed DTBs.

The location of the bl31.bin image from the ARM Trusted Firmware build can either by specified via the BL31 environment variable. If this is not set, the script looks for bl31.bin in U-Boot's build directory (which could be a symlink as well).

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Simon Glass sjg@chromium.org Acked-by: Maxime Ripard maxime.ripard@free-electrons.com --- board/sunxi/mksunxi_fit_atf.sh | 75 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100755 board/sunxi/mksunxi_fit_atf.sh

diff --git a/board/sunxi/mksunxi_fit_atf.sh b/board/sunxi/mksunxi_fit_atf.sh new file mode 100755 index 0000000..ecea1b8 --- /dev/null +++ b/board/sunxi/mksunxi_fit_atf.sh @@ -0,0 +1,75 @@ +#!/bin/sh +# +# script to generate FIT image source for 64-bit sunxi boards with +# ARM Trusted Firmware and multiple device trees (given on the command line) +# +# usage: $0 <dt_name> [<dt_name> [<dt_name] ...] + +[ -z "$BL31" ] && BL31="bl31.bin" + +cat << __HEADER_EOF +/dts-v1/; + +/ { + description = "Configuration to load ATF before U-Boot"; + #address-cells = <1>; + + images { + uboot@1 { + description = "U-Boot (64-bit)"; + data = /incbin/("u-boot-nodtb.bin"); + type = "standalone"; + arch = "arm64"; + compression = "none"; + load = <0x4a000000>; + }; + atf@1 { + description = "ARM Trusted Firmware"; + data = /incbin/("$BL31"); + type = "firmware"; + arch = "arm64"; + compression = "none"; + load = <0x44000>; + entry = <0x44000>; + }; +__HEADER_EOF + +cnt=1 +for dtname in $* +do + cat << __FDT_IMAGE_EOF + fdt@$cnt { + description = "$(basename $dtname .dtb)"; + data = /incbin/("$dtname"); + type = "flat_dt"; + compression = "none"; + }; +__FDT_IMAGE_EOF + cnt=$((cnt+1)) +done + +cat << __CONF_HEADER_EOF + }; + configurations { + default = "config@1"; + +__CONF_HEADER_EOF + +cnt=1 +for dtname in $* +do + cat << __CONF_SECTION_EOF + config@$cnt { + description = "$(basename $dtname .dtb)"; + firmware = "uboot@1"; + loadables = "atf@1"; + fdt = "fdt@$cnt"; + }; +__CONF_SECTION_EOF + cnt=$((cnt+1)) +done + +cat << __ITS_EOF + }; +}; +__ITS_EOF

From: Siarhei Siamashka siarhei.siamashka@gmail.com

This patch updates the mksunxiboot tool to optionally add the default device tree name string to the SPL header. This information can be used by the firmware upgrade tools to protect users from harming themselves by trying to upgrade to an incompatible bootloader.

The primary use case here is a non-removable bootable media (such as NAND, eMMC or SPI flash), which already may have a properly working, but a little bit outdated bootloader installed. For example, the user may download or build a new U-Boot image for "Cubieboard", and then attemept to install it on a "Cubieboard2" hardware by mistake as a replacement for the already existing bootloader. If this happens, the flash programming tool can identify this problem and warn the user.

The size of the SPL header is also increased from 64 bytes to 96 bytes to provide enough space for the device tree name string. [Andre: split patch to remove OF_LIST hash feature]

Signed-off-by: Siarhei Siamashka siarhei.siamashka@gmail.com Signed-off-by: Andre Przywara andre.przywara@arm.com --- arch/arm/include/asm/arch-sunxi/spl.h | 19 +++++++++++--- include/configs/sunxi-common.h | 8 +++--- scripts/Makefile.spl | 3 ++- tools/mksunxiboot.c | 49 ++++++++++++++++++++++++++++++++--- 4 files changed, 67 insertions(+), 12 deletions(-)

diff --git a/arch/arm/include/asm/arch-sunxi/spl.h b/arch/arm/include/asm/arch-sunxi/spl.h index 831d0c0..9358397 100644 --- a/arch/arm/include/asm/arch-sunxi/spl.h +++ b/arch/arm/include/asm/arch-sunxi/spl.h @@ -10,7 +10,7 @@

#define BOOT0_MAGIC "eGON.BT0" #define SPL_SIGNATURE "SPL" /* marks "sunxi" SPL header */ -#define SPL_HEADER_VERSION 1 +#define SPL_HEADER_VERSION 2

#ifdef CONFIG_SUNXI_HIGH_SRAM #define SPL_ADDR 0x10000 @@ -58,11 +58,24 @@ struct boot_file_head { * compatible format, ready to be imported via "env import -t". */ uint32_t fel_uEnv_length; - uint32_t reserved1[2]; + /* + * Offset of an ASCIIZ string (relative to the SPL header), which + * contains the default device tree name (CONFIG_DEFAULT_DEVICE_TREE). + * This is optional and may be set to NULL. Is intended to be used + * by flash programming tools for providing nice informative messages + * to the users. + */ + uint32_t dt_name_offset; + uint32_t reserved1; uint32_t boot_media; /* written here by the boot ROM */ - uint32_t reserved2[5]; /* padding, align to 64 bytes */ + /* A padding area (may be used for storing text strings) */ + uint32_t string_pool[13]; + /* The header must be a multiple of 32 bytes (for VBAR alignment) */ };

+/* Compile time check to assure proper alignment of structure */ +typedef char boot_file_head_not_multiple_of_32[1 - 2*(sizeof(struct boot_file_head) % 32)]; + #define is_boot0_magic(addr) (memcmp((void *)addr, BOOT0_MAGIC, 8) == 0)

#endif diff --git a/include/configs/sunxi-common.h b/include/configs/sunxi-common.h index 311b13b..c864f51 100644 --- a/include/configs/sunxi-common.h +++ b/include/configs/sunxi-common.h @@ -189,8 +189,8 @@ #endif

#ifdef CONFIG_SUNXI_HIGH_SRAM -#define CONFIG_SPL_TEXT_BASE 0x10040 /* sram start+header */ -#define CONFIG_SPL_MAX_SIZE 0x7fc0 /* 32 KiB */ +#define CONFIG_SPL_TEXT_BASE 0x10060 /* sram start+header */ +#define CONFIG_SPL_MAX_SIZE 0x7fa0 /* 32 KiB */ #ifdef CONFIG_ARM64 /* end of SRAM A2 for now, as SRAM A1 is pretty tight for an ARM64 build */ #define LOW_LEVEL_SRAM_STACK 0x00054000 @@ -198,8 +198,8 @@ #define LOW_LEVEL_SRAM_STACK 0x00018000 #endif /* !CONFIG_ARM64 */ #else -#define CONFIG_SPL_TEXT_BASE 0x40 /* sram start+header */ -#define CONFIG_SPL_MAX_SIZE 0x5fc0 /* 24KB on sun4i/sun7i */ +#define CONFIG_SPL_TEXT_BASE 0x60 /* sram start+header */ +#define CONFIG_SPL_MAX_SIZE 0x5fa0 /* 24KB on sun4i/sun7i */ #define LOW_LEVEL_SRAM_STACK 0x00008000 /* End of sram */ #endif

diff --git a/scripts/Makefile.spl b/scripts/Makefile.spl index eb24292..250649a 100644 --- a/scripts/Makefile.spl +++ b/scripts/Makefile.spl @@ -304,7 +304,8 @@ $(obj)/$(SPL_BIN).sfp: $(obj)/$(SPL_BIN).bin FORCE $(call if_changed,mkimage)

quiet_cmd_mksunxiboot = MKSUNXI $@ -cmd_mksunxiboot = $(objtree)/tools/mksunxiboot $< $@ +cmd_mksunxiboot = $(objtree)/tools/mksunxiboot \ + --default-dt $(CONFIG_DEFAULT_DEVICE_TREE) $< $@ $(obj)/sunxi-spl.bin: $(obj)/$(SPL_BIN).bin FORCE $(call if_changed,mksunxiboot)

diff --git a/tools/mksunxiboot.c b/tools/mksunxiboot.c index 111d74a..db0f10e 100644 --- a/tools/mksunxiboot.c +++ b/tools/mksunxiboot.c @@ -70,11 +70,40 @@ int main(int argc, char *argv[]) struct boot_img img; unsigned file_size; int count; + char *tool_name = argv[0]; + char *default_dt = NULL;

- if (argc < 2) { - printf("\tThis program makes an input bin file to sun4i " \ - "bootable image.\n" \ - "\tUsage: %s input_file out_putfile\n", argv[0]); + /* a sanity check */ + if ((sizeof(img.header) % 32) != 0) { + fprintf(stderr, "ERROR: the SPL header must be a multiple "); + fprintf(stderr, "of 32 bytes.\n"); + return EXIT_FAILURE; + } + + /* process optional command line switches */ + while (argc >= 2 && argv[1][0] == '-') { + if (strcmp(argv[1], "--default-dt") == 0) { + if (argc >= 3) { + default_dt = argv[2]; + argv += 2; + argc -= 2; + continue; + } + fprintf(stderr, "ERROR: no --default-dt arg\n"); + return EXIT_FAILURE; + } else { + fprintf(stderr, "ERROR: bad option '%s'\n", argv[1]); + return EXIT_FAILURE; + } + } + + if (argc < 3) { + printf("This program converts an input binary file to a sunxi bootable image.\n"); + printf("\nUsage: %s [options] input_file output_file\n", + tool_name); + printf("Where [options] may be:\n"); + printf(" --default-dt arg - 'arg' is the default device tree name\n"); + printf(" (CONFIG_DEFAULT_DEVICE_TREE).\n"); return EXIT_FAILURE; }

@@ -122,6 +151,18 @@ int main(int argc, char *argv[]) memcpy(img.header.spl_signature, SPL_SIGNATURE, 3); /* "sunxi" marker */ img.header.spl_signature[3] = SPL_HEADER_VERSION;

+ if (default_dt) { + if (strlen(default_dt) + 1 <= sizeof(img.header.string_pool)) { + strcpy((char *)img.header.string_pool, default_dt); + img.header.dt_name_offset = + cpu_to_le32(offsetof(struct boot_file_head, + string_pool)); + } else { + printf("WARNING: The SPL header is too small\n"); + printf(" and has no space to store the dt name.\n"); + } + } + gen_check_sum(&img.header);

count = write(fd_out, &img, le32_to_cpu(img.header.length));

With the DRAM init code and the SPL's ability to load the ATF binary as well, we can now officially get rid of the boot0 boot method, which involed a closed-source proprietary blob to be used. Rework the Pine64 README file to document how to build the firmware. Also since these instructions now cover more boards, rename the file to README.sunxi64 to reflect this.

Signed-off-by: Andre Przywara andre.przywara@arm.com --- board/sunxi/README.pine64 | 98 --------------------------- board/sunxi/README.sunxi64 | 165 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+), 98 deletions(-) delete mode 100644 board/sunxi/README.pine64 create mode 100644 board/sunxi/README.sunxi64

diff --git a/board/sunxi/README.pine64 b/board/sunxi/README.pine64 deleted file mode 100644 index 5553415..0000000 --- a/board/sunxi/README.pine64 +++ /dev/null @@ -1,98 +0,0 @@ -Pine64 board README -==================== - -The Pine64(+) is a single board computer equipped with an AArch64 capable ARMv8 -compliant Allwinner A64 SoC. -This chip has ARM Cortex A-53 cores and thus can run both in AArch32 -(compatible to 32-bit ARMv7) and AArch64 modes. Upon reset the SoC starts -in AArch32 mode and executes 32-bit code from the Boot ROM (BROM). -This has some implications on U-Boot. - -Quick start -============ -- Get hold of a boot0.img file (see below for more details). -- Get the boot0img tool source from the tools directory in [1] and compile - that on your host. -- Build U-Boot: -$ export CROSS_COMPILE=aarch64-linux-gnu- -$ make pine64_plus_defconfig -$ make -- You also need a compiled ARM Trusted Firmware (ATF) binary. Checkout the - "allwinner" branch from the github repository [2] and build it: -$ export CROSS_COMPILE=aarch64-linux-gnu- -$ make PLAT=sun50iw1p1 DEBUG=1 bl31 - The resulting binary is build/sun50iw1p1/debug/bl31.bin. - -Now put an empty (or disposable) micro SD card in your card reader and learn -its device file name, replacing /dev/sd<x> below with the result (that could -be /dev/mmcblk<x> as well): - -$ ./boot0img --device /dev/sd<x> -e -u u-boot.bin -B boot0.img \ - -d trampoline64:0x44000 -s bl31.bin -a 0x44008 -p 100 -(either copying the respective files to the working directory or specifying -the paths directly) - -This will create a new partition table (with a 100 MB FAT boot partition), -copies boot0.img, ATF and U-Boot to the proper locations on the SD card and -will fill in the magic Allwinner header to be recognized by boot0. -Prefix the above call with "sudo" if you don't have write access to the -uSD card. You can also use "-o output.img" instead of "--device /dev/sd<x>" -to create an image file and "dd" that to the uSD card. -Omitting the "-p" option will skip the partition table. - -Now put this uSD card in the board and power it on. You should be greeted by -the U-Boot prompt. - - -Main U-Boot -============ -The main U-Boot proper is a real 64-bit ARMv8 port and runs entirely in the -64-bit AArch64 mode. It can load any AArch64 code, EFI applications or arm64 -Linux kernel images (often named "Image") using the booti command. -Launching 32-bit code and kernels is technically possible, though not without -drawbacks (or hacks to avoid them) and currently not implemented. - -SPL support -============ -The main task of the SPL support is to bring up the DRAM controller and make -DRAM actually accessible. At the moment there is no documentation or source -code available which would do this. -There are currently two ways to overcome this situation: using a tainted 32-bit -SPL (involving some hacks and resulting in a non-redistributable binary, thus -not described here) or using the Allwinner boot0 blob. - -boot0 method -------------- -boot0 is Allwiner's secondary program loader and it can be used as some kind -of SPL replacement to get U-Boot up and running. -The binary is a 32 KByte blob and contained on every Pine64 image distributed -so far. It can be easily extracted from a micro SD card or an image file: -# dd if=/dev/sd<x> of=boot0.bin bs=8k skip=1 count=4 -where /dev/sd<x> is the device name of the uSD card or the name of the image -file. Apparently Allwinner allows re-distribution of this proprietary code -as-is. -For the time being this boot0 blob is the only redistributable way of making -U-Boot work on the Pine64. Beside loading the various parts of the (original) -firmware it also switches the core into AArch64 mode. -The original boot0 code looks for U-Boot at a certain place on an uSD card -(at 19096 KB), also it expects a header with magic bytes and a checksum. -There is a tool called boot0img[1] which takes a boot0.bin image and a compiled -U-Boot binary (plus other binaries) and will populate that header accordingly. -To make space for the magic header, the pine64_plus_defconfig will make sure -there is sufficient space at the beginning of the U-Boot binary. -boot0img will also take care of putting the different binaries at the right -places on the uSD card and works around unused, but mandatory parts by using -trampoline code. See the output of "boot0img -h" for more information. -boot0img can also patch boot0 to avoid loading U-Boot from 19MB, instead -fetching it from just behind the boot0 binary (-B option). - -FEL boot -========= -FEL is the name of the Allwinner defined USB boot protocol built-in the -mask ROM of most Allwinner SoCs. It allows to bootstrap a board solely -by using the USB-OTG interface and a host port on another computer. -Since FEL boot does not work with boot0, it requires the libdram hack, which -is not described here. - -[1] https://github.com/apritzel/pine64/ -[2] https://github.com/apritzel/arm-trusted-firmware.git diff --git a/board/sunxi/README.sunxi64 b/board/sunxi/README.sunxi64 new file mode 100644 index 0000000..c492f74 --- /dev/null +++ b/board/sunxi/README.sunxi64 @@ -0,0 +1,165 @@ +Allwinner 64-bit boards README +============================== + +Newer Allwinner SoCs feature ARMv8 cores (ARM Cortex-A53) with support for +both the 64-bit AArch64 mode and the ARMv7 compatible 32-bit AArch32 mode. +Examples are the Allwinner A64 (used for instance on the Pine64 board) or +the Allwinner H5 SoC (as used on the OrangePi PC 2). +These SoCs are wired to start in AArch32 mode on reset and execute 32-bit +code from the Boot ROM (BROM). As this has some implications on U-Boot, this +file describes how to make full use of the 64-bit capabilities. + +Quick Start / Overview +====================== +- Build the ARM Trusted Firmware binary (see "ARM Trusted Firmware (ATF)" below) +- Build U-Boot (see "SPL/U-Boot" below) +- Transfer to an uSD card (see "microSD card" below) +- Boot and enjoy! + +Building the firmware +===================== + +The Allwinner A64/H5 firmware consists of three parts: U-Boot's SPL, an +ARM Trusted Firmware (ATF) build and the U-Boot proper. +The SPL will load both ATF and U-Boot proper along with the right device +tree blob (.dtb) and will pass execution to ATF (in EL3), which in turn will +drop into the U-Boot proper (in EL2). +As the ATF binary will become part of the U-Boot image file, you will need +to build it first. + + ARM Trusted Firmware (ATF) +---------------------------- +Checkout the "allwinner" branch from the github repository [1] and build it: +$ export CROSS_COMPILE=aarch64-linux-gnu- +$ make PLAT=sun50iw1p1 DEBUG=1 bl31 +The resulting binary is build/sun50iw1p1/debug/bl31.bin. Either put the +location of this file into the BL31 environment variable or copy this to +the root of your U-Boot build directory (or create a symbolic link). +$ export BL31=/src/arm-trusted-firmware/build/sun50iw1p1/debug/bl31.bin + (adjust the actual path accordingly) + + SPL/U-Boot +------------ +Both U-Boot proper and the SPL are using the 64-bit mode. As the boot ROM +enters the SPL still in AArch32 secure SVC mode, there is some shim code to +enter AArch64 very early. The rest of the SPL runs in AArch64 EL3. +U-Boot proper runs in EL2 and can load any AArch64 code (using the "go" +command), EFI applications (with "bootefi") or arm64 Linux kernel images +(often named "Image"), using the "booti" command. + +$ make clean +$ export CROSS_COMPILE=aarch64-linux-gnu- +$ make pine64_plus_defconfig +$ make + +This will build the SPL in spl/sunxi-spl.bin and a FIT image called u-boot.itb, +which contains the rest of the firmware. + + +Boot process +============ +The on-die BROM code will try several methods to load and execute the firmware. +On a typical board like the Pine64 this will result in the following boot order: + +1) Reading 32KB from sector 16 (@8K) of the microSD card to SRAM A1. If the +BROM finds the magic "eGON" header in the first bytes, it will execute that +code. If not (no SD card at all or invalid magic), it will: +2) Try to read 32KB from sector 16 (@8K) of memory connected to the MMC2 +controller, typically an on-board eMMC chip. If there is no eMMC or it does +not contain a valid boot header, it will: +3) Initialize the SPI0 controller and try to access a NOR flash connected to +it (using the CS0 pin). If a flash chip is found, the BROM will load the +first 32KB (from offset 0) into SRAM A1. Now it checks for the magic eGON +header and checksum and will execute the code upon finding it. If not, it will: +4) Initialize the USB OTG controller and will wait for a host to connect to +it, speaking the Allwinner proprietary (but deciphered) "FEL" USB protocol. + + +To boot the Pine64 board, you can use U-Boot and any of the described methods. + +FEL boot (USB OTG) +------------------ +FEL is the name of the Allwinner defined USB boot protocol built in the +mask ROM of most Allwinner SoCs. It allows to bootstrap a board solely +by using the USB-OTG interface and a host port on another computer. +As the FEL mode is controlled by the boot ROM, it expects to be running in +AArch32. For now the AArch64 SPL cannot properly return into FEL mode, so the +feature is disabled in the configuration at the moment. + +microSD card +------------ +Transfer the SPL and the U-Boot FIT image directly to an uSD card: +# dd if=spl/sunxi-spl.bin of=/dev/sdx bs=8k seek=1 +# dd if=u-boot.itb of=/dev/sdx bs=8k seek=5 +# sync +(replace /dev/sdx with you SD card device file name, which could be +/dev/mmcblk[x] as well). + +Alternatively you can concatenate the SPL and the U-Boot FIT image into a +single file and transfer that instead: +$ cat spl/sunxi-spl.bin u-boot.itb > u-boot-sunxi-with-spl.bin +# dd if=u-boot-sunxi-with-spl.bin of=/dev/sdx bs=8k seek=1 + +You can partition the microSD card, but leave the first MB unallocated (most +partitioning tools will do this anyway). + +NOR flash +--------- +Some boards (like the SoPine, Pinebook or the OrangePi PC2) come with a +soldered SPI NOR flash chip. On other boards like the Pine64 such a chip +can be connected to the SPI0/CS0 pins on the PI-2 headers. +Create the SPL and FIT image like described above for the SD card. +Now connect either an "A to A" USB cable to the upper USB port on the Pine64 +or get an adaptor and use a regular A-microB cable connected to it. Other +boards often have a proper micro-B USB socket connected to the USB OTB port. +Remove a microSD card from the slot and power on the board. +On your host computer download and build the sunxi-tools package[2], then +use "sunxi-fel" to access the board: +$ ./sunxi-fel ver -v -p +This should give you an output starting with: AWUSBFEX soc=00001689(A64) ... +Now use the sunxi-fel tool to write to the NOR flash: +$ ./sunxi-fel spiflash-write 0 spl/sunxi-spl.bin +$ ./sunxi-fel spiflash-write 32768 u-boot.itb +Now boot the board without an SD card inserted and you should see the +U-Boot prompt on the serial console. + +(Legacy) boot0 method +--------------------- +boot0 is Allwiner's secondary program loader and it can be used as some kind +of SPL replacement to get U-Boot up and running from an microSD card. +For some time using boot0 was the only option to get the Pine64 booted. +With working DRAM init code in U-Boot's SPL this is no longer necessary, +but this method is described here for the sake of completeness. +Please note that this method works only with the boot0 files shipped with +A64 based boards, the H5 uses an incompatible layout which is not supported +by this method. + +The boot0 binary is a 32 KByte blob and contained in the official Pine64 images +distributed by Pine64 or Allwinner. It can be easily extracted from a micro +SD card or an image file: +# dd if=/dev/sd<x> of=boot0.bin bs=8k skip=1 count=4 +where /dev/sd<x> is the device name of the uSD card or the name of the image +file. Apparently Allwinner allows re-distribution of this proprietary code +"as-is". +This boot0 blob takes care of DRAM initialisation and loads the remaining +firmware parts, then switches the core into AArch64 mode. +The original boot0 code looks for U-Boot at a certain place on an uSD card +(at 19096 KB), also it expects a header with magic bytes and a checksum. +There is a tool called boot0img[3] which takes a boot0.bin image and a compiled +U-Boot binary (plus other binaries) and will populate that header accordingly. +To make space for the magic header, the pine64_plus_defconfig will make sure +there is sufficient space at the beginning of the U-Boot binary. +boot0img will also take care of putting the different binaries at the right +places on the uSD card and works around unused, but mandatory parts by using +trampoline code. See the output of "boot0img -h" for more information. +boot0img can also patch boot0 to avoid loading U-Boot from 19MB, instead +fetching it from just behind the boot0 binary (-B option). +$ ./boot0img -o firmware.img -B boot0.img -u u-boot-dtb.bin -e -s bl31.bin \ +-a 0x44008 -d trampoline64:0x44000 +Then write this image to a microSD card, replacing /dev/sdx with the right +device file (see above): +$ dd if=firmware.img of=/dev/sdx bs=8k seek=1 + +[1] https://github.com/apritzel/arm-trusted-firmware.git +[2] git://github.com/linux-sunxi/sunxi-tools.git +[3] https://github.com/apritzel/pine64/