Currently the SPL FIT loader uses the spl_fit_select_fdt() function to find the offset to the right DTB within the FIT image. For this it iterates over all subnodes of the /configuration node in the FIT tree and compares all "description" strings therein using a board specific matching function. If that finds a match, it uses the string in the "fdt" property of that subnode to locate the matching subnode in the /images node, which points to the DTB data. Now this works very well, but is quite specific to cover this particular use case. To open up the door for a more generic usage, let's split this function into: 1) a function that just returns the node offset for the matching configuration node (spl_fit_find_config_node()) 2) a function that returns the image data any given property in a given configuration node points to, additionally using a given index into a possbile list of strings (spl_fit_select_index()) This allows us to replace the specific function above by asking for the image the _first string of the "fdt" property_ in the matching configuration subnode points to.

This patch introduces no functional changes, it just refactors the code to allow reusing it later.

(diff is overly clever here and produces a hard-to-read patch, so I recommend to throw a look at the result instead).

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Lokesh Vutla lokeshvuta@ti.com --- common/spl/spl_fit.c | 88 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 57 insertions(+), 31 deletions(-)

diff --git a/common/spl/spl_fit.c b/common/spl/spl_fit.c index aae556f..bf9fbb6 100644 --- a/common/spl/spl_fit.c +++ b/common/spl/spl_fit.c @@ -22,13 +22,16 @@ static ulong fdt_getprop_u32(const void *fdt, int node, const char *prop) return fdt32_to_cpu(*cell); }

-static int spl_fit_select_fdt(const void *fdt, int images, int *fdt_offsetp) +/* + * Iterate over all /configurations subnodes and call a platform specific + * function to find the matching configuration. + * Returns the node offset. + */ +static int spl_fit_find_config_node(const void *fdt) { - const char *name, *fdt_name; - int conf, node, fdt_node; - int len; + const char *name; + int conf, node, len;

- *fdt_offsetp = 0; conf = fdt_path_offset(fdt, FIT_CONFS_PATH); if (conf < 0) { debug("%s: Cannot find /configurations node: %d\n", __func__, @@ -50,39 +53,61 @@ static int spl_fit_select_fdt(const void *fdt, int images, int *fdt_offsetp) continue;

debug("Selecting config '%s'", name); - fdt_name = fdt_getprop(fdt, node, FIT_FDT_PROP, &len); - if (!fdt_name) { - debug("%s: Cannot find fdt name property: %d\n", - __func__, len); - return -EINVAL; - }

- debug(", fdt '%s'\n", fdt_name); - fdt_node = fdt_subnode_offset(fdt, images, fdt_name); - if (fdt_node < 0) { - debug("%s: Cannot find fdt node '%s': %d\n", - __func__, fdt_name, fdt_node); - return -EINVAL; + return node; + } + + return -1; +} + +static int spl_fit_select_index(const void *fit, int images, int *offsetp, + const char *type, int index) +{ + const char *name, *str; + int node, conf_node; + int len, i; + + *offsetp = 0; + conf_node = spl_fit_find_config_node(fit); + if (conf_node < 0) { +#ifdef CONFIG_SPL_LIBCOMMON_SUPPORT + printf("No matching DT out of these options:\n"); + for (node = fdt_first_subnode(fit, conf_node); + node >= 0; + node = fdt_next_subnode(fit, node)) { + name = fdt_getprop(fit, node, "description", &len); + printf(" %s\n", name); } +#endif + return -ENOENT; + }

- *fdt_offsetp = fdt_getprop_u32(fdt, fdt_node, "data-offset"); - len = fdt_getprop_u32(fdt, fdt_node, "data-size"); - debug("FIT: Selected '%s'\n", name); + name = fdt_getprop(fit, conf_node, type, &len); + if (!name) { + debug("cannot find property '%s': %d\n", type, len); + return -EINVAL; + }

- return len; + str = name; + for (i = 0; i < index; i++) { + str = strchr(str, '\0') + 1; + if (!str || (str - name >= len)) { + debug("no string for index %d\n", index); + return -E2BIG; + } }

-#ifdef CONFIG_SPL_LIBCOMMON_SUPPORT - printf("No matching DT out of these options:\n"); - for (node = fdt_first_subnode(fdt, conf); - node >= 0; - node = fdt_next_subnode(fdt, node)) { - name = fdt_getprop(fdt, node, "description", &len); - printf(" %s\n", name); + debug("%s: '%s'\n", type, str); + node = fdt_subnode_offset(fit, images, str); + if (node < 0) { + debug("cannot find image node '%s': %d\n", str, node); + return -EINVAL; } -#endif

- return -ENOENT; + *offsetp = fdt_getprop_u32(fit, node, "data-offset"); + len = fdt_getprop_u32(fit, node, "data-size"); + + return len; }

static int get_aligned_image_offset(struct spl_load_info *info, int offset) @@ -218,7 +243,8 @@ int spl_load_simple_fit(struct spl_image_info *spl_image, memcpy(dst, src, data_size);

/* Figure out which device tree the board wants to use */ - fdt_len = spl_fit_select_fdt(fit, images, &fdt_offset); + fdt_len = spl_fit_select_index(fit, images, &fdt_offset, + FIT_FDT_PROP, 0); if (fdt_len < 0) return fdt_len;

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 --- 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 a4ac27b..55da37a 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); }

@@ -221,7 +224,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 -1; data_size = fdt_getprop_u32(fit, node, "data-size"); + if (data_size == FDT_ERROR) + return -1; load = fdt_getprop_u32(fit, node, "load"); debug("data_offset=%x, data_size=%x\n", data_offset, data_size); spl_image->load_addr = load; @@ -264,6 +271,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 -1; + }

/* * 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.

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Lokesh Vutla lokeshvuta@ti.com --- common/spl/spl_fit.c | 42 ++++++++++++++++++++++++++++++++++++++++-- doc/uImage.FIT/howto.txt | 21 +++++++++++++++++++++ 2 files changed, 61 insertions(+), 2 deletions(-)

diff --git a/common/spl/spl_fit.c b/common/spl/spl_fit.c index cfcb1fe..edf4a43 100644 --- a/common/spl/spl_fit.c +++ b/common/spl/spl_fit.c @@ -231,6 +231,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 @@ -275,6 +276,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", @@ -302,6 +308,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 -----------------------------------------------

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 b95e105..5733430 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 --- 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 171cea2..b7eb95e 100644 --- a/include/configs/sunxi-common.h +++ b/include/configs/sunxi-common.h @@ -182,7 +182,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 --- board/sunxi/board.c | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)

diff --git a/board/sunxi/board.c b/board/sunxi/board.c index a510422..2ddff28 100644 --- a/board/sunxi/board.c +++ b/board/sunxi/board.c @@ -725,3 +725,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 A64 boards. 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.

This requires to copy the ARM Trusted Firmware build (bl31.bin) into the U-Boot source directory (or to create a symlink to it).

Signed-off-by: Andre Przywara andre.przywara@arm.com Reviewed-by: Simon Glass sjg@chromium.org --- board/sunxi/mksunxi_fit_atf.sh | 73 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 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..afa22e8 --- /dev/null +++ b/board/sunxi/mksunxi_fit_atf.sh @@ -0,0 +1,73 @@ +#!/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] ...] + +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.bin"); + 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 1982063..65f0f69 100644 --- a/include/configs/sunxi-common.h +++ b/include/configs/sunxi-common.h @@ -184,8 +184,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 @@ -193,8 +193,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 d01af3b..d134b74 100644 --- a/scripts/Makefile.spl +++ b/scripts/Makefile.spl @@ -294,7 +294,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 6bb649c..4ac2791 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.

Signed-off-by: Andre Przywara andre.przywara@arm.com --- board/sunxi/README.pine64 | 177 ++++++++++++++++++++++++++++++---------------- 1 file changed, 115 insertions(+), 62 deletions(-)

diff --git a/board/sunxi/README.pine64 b/board/sunxi/README.pine64 index 5553415..41fb58e 100644 --- a/board/sunxi/README.pine64 +++ b/board/sunxi/README.pine64 @@ -8,75 +8,130 @@ This chip has ARM Cortex A-53 cores and thus can run both in AArch32 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: +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 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. Copy this to the + root of the U-Boot source tree (or create a symbolic link). + + 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, EFI applications 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 -- 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): +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. +

-$ ./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) +Boot process +============ +The on-die BROM code will try several methods to load and execute the firmware. +On 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, it will: +2) 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 will execute the code upon finding it. If not, it will: +3) 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.

-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. +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.

-Now put this uSD card in the board and power it on. You should be greeted by -the U-Boot prompt. +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).

+Alternative 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

-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. +You can partition the microSD card, but leave the first MB unallocated (most +partitioning tools will do this anyway).

-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 -------------- +NOR flash +--------- +The Pine64 board can be booted via an SPI NOR flash chip connected to SPI0/CS0 +on the PI-2 headers. The SoPine module and the Pinebook notebook come with +a SPI flash soldered already. +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. +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. -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: +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. + +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. -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. +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[1] which takes a boot0.bin image and a compiled +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. @@ -85,14 +140,12 @@ 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

-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 +[1] https://github.com/apritzel/arm-trusted-firmware.git +[2] git://github.com/linux-sunxi/sunxi-tools.git +[3] https://github.com/apritzel/pine64/