FEL/USBBoot

On Allwinner SoCs it is possible to boot over USB OTG. This requires only minimal changes compared to the build steps in the manual build howto, and these changes are explained on this wiki page.

By booting over USB OTG, it is possible to forgo the SD-Card entirely, and it is especially useful for devices where no UART can be found, or where the UART is multiplexed with the SD-Card. You can then use a micro-SD breakout adapter to access the serial port.

= Install the tools =

There is a utility in the sunxi-tools repository called 'fel'. This utility is used for booting the system over USB and it needs to be installed first.

The command line syntax of the 'fel' utility: Usage: fel command arguments... [command...] hex[dump] address length	Dumps memory region in hex dump address length		Binary memory dump exe[cute] address		Call function address read address length file	Write memory contents into file write address file		Store file contents into memory ver[sion]			Show BROM version clear address length		Clear memory fill address length value	Fill memory

= Switch your device into FEL mode =

Before the 'fel' tool can actually talk to your device, the device needs to be connected to your PC using a "USB A to USB mini/micro B" cable.

And then the device needs to be switched into FEL mode. Please refer to the FEL howto for information on how to boot to FEL mode. Device pages should mention the button which triggers FEL mode as well.

If you run: fel version

and it returns something like: AWUSBFEX soc=00162500(A13) 00000001 ver=0001 44 08 scratchpad=00007e00 00000000 00000000

Then you have successfully switched the device into FEL mode and it is ready to accept commands or load the system over USB.

= Boot the system over USB =

Getting the mainline U-Boot sources
To obtain the U-Boot sources, clone the current U-Boot master branch:

git clone git://git.denx.de/u-boot.git cd u-boot

Or alternatively the 'next' branch from the sunxi custodian tree:

git clone -b next git://git.denx.de/u-boot-sunxi.git cd u-boot-sunxi

Both of these branches are bleeding edge and may contain bugs from time to time. If you encounter troubles, try a tarball with the latest formal U-Boot release before giving up.

Old method of booting U-Boot over USB (u-boot v2015.04 and older versions)
The U-Boot needs to be configured using "*_felconfig" option (instead of "*_defconfig") before compiling. For example, in the case of a Cubietruck board, that would be: make CROSS_COMPILE=arm-none-linux-gnueabi- Cubietruck_felconfig make CROSS_COMPILE=arm-none-linux-gnueabi- -j$(nproc)

Then just use the 'fel' tool to upload various pieces to certain magic addresses (the magic CONFIG_SPL_TEXT_BASE=0x2000 and CONFIG_SYS_TEXT_BASE=0x4a000000 values can be found in the U-Boot sources). And execute them in a certain order:

echo == upload the SPL to SRAM and execute it == fel write 0x2000 spl/u-boot-spl.bin fel exe  0x2000

sleep 1 # wait for DRAM initialization to complete

echo == upload the main u-boot binary to DRAM == fel write 0x4a000000 u-boot.bin

echo == execute the main u-boot binary == fel exe  0x4a000000

This boots U-Boot over USB. And after U-Boot takes control, it starts scanning various default locations for the boot.scr file in order to boot the rest of the system.

New method of booting U-Boot over USB (u-boot v2015.04-rc2 and later versions)
This needs an up to date 'fel' tool (with the 'spl' command added) from the sunxi-tools repository and U-Boot v2015.04-rc2 or newer.

Then just do a regular u-boot build (note that the special '*_felconfig' is not needed anymore):  make CROSS_COMPILE=arm-none-linux-gnueabi- Cubietruck_defconfig make CROSS_COMPILE=arm-none-linux-gnueabi- -j$(nproc)

And boot it over USB:  echo == upload the SPL to SRAM and execute it == fel spl u-boot-sunxi-with-spl.bin

echo == upload the main u-boot binary to DRAM == fel write 0x4a000000 u-boot.bin

echo == execute the main u-boot binary == fel exe  0x4a000000 The advantage of this new method is that the same 'u-boot-sunxi-with-spl.bin' binary can be written to the SD card. We don't need separate builds for the FEL boot and the SD card boot configurations. Moreover, the old ~16 KiB size limitation for the FEL mode SPL does not apply anymore.

Current U-Boot (after switch to device model)
The most recent U-Boot versions (2015.07 release candidates and later) have moved to the device tree model. This means that a DTB with device information needs to be included, otherwise U-Boot won't start up properly.

A typical symptom is that U-Boot doesn't get past the initial "U-Boot SPL" output (including version, DRAM and CPU information). In this case double-check that you're pointing to the correct u-boot-dtb.bin. See: http://lists.denx.de/pipermail/u-boot/2015-June/217476.html

Boot the whole system over USB (U-Boot + kernel + initramfs)
It is also possible to boot the whole system over USB, including the kernel and initramfs. To do this, we first need to patch U-Boot: Here is the patch (click on the 'Expand' link to see it): diff --git a/include/configs/sunxi-common.h b/include/configs/sunxi-common.h index 30ff17c..c92afd3 100644 --- a/include/configs/sunxi-common.h +++ b/include/configs/sunxi-common.h @@ -308,6 +308,9 @@ CONSOLE_STDIN_SETTINGS \ CONSOLE_STDOUT_SETTINGS +#undef BOOTENV +#define BOOTENV "bootcmd=source ${scriptaddr}\0" + 	CONSOLE_ENV_SETTINGS \ MEM_LAYOUT_ENV_SETTINGS \
 * 1) define CONFIG_EXTRA_ENV_SETTINGS \

This patch just tells U-Boot to pick the boot.scr from memory instead of searching for it everywhere. Then we use the following sequence of the 'fel' tool calls, which refer to another bunch of magic addresses from the U-Boot sources (kernel_addr_r=0x42000000, fdt_addr_r=0x43000000, scriptaddr=0x43100000, ramdisk_addr_r=0x43300000): echo == upload the SPL to SRAM and execute it == fel write 0x2000 spl/u-boot-spl.bin fel exe  0x2000

sleep 1 # wait for DRAM initialization to complete

echo == upload the main u-boot binary to DRAM == fel write 0x4a000000 u-boot.bin

echo == upload the kernel == fel write 0x42000000 uImage

echo == upload the DTB file == fel write 0x43000000 sun7i-a20-cubietruck.dtb

echo == upload the boot.scr file == fel write 0x43100000 boot.scr

echo == upload initramfs == fel write 0x43300000 rootfs.cpio.lzma.uboot

echo == execute the main u-boot binary == fel exe  0x4a000000

Please note that the main U-Boot binary is always executed as the very last step (after uploading everything to the device memory)!

Preparing U-Boot
U-boot needs to be built specifically for booting over USB. This is called FEL mode, and enabling this disables the full SD card (for u-boot, script.bin and the kernel might re-enable it later on).

Just follow the guide to compile u-boot, but  select a target whose name has _FEL.

Manual loading
While the script from the next section is perhaps better, you can now choose to load u-boot manually:

fel write 0x2000 ../u-boot/spl/u-boot-spl.bin fel exe 0x2000 sleep 1 # Wait for DRAM initialization to complete fel write 0x4a000000 ../u-boot/u-boot.bin fel exe 0x4a000000

usb-boot script
There is a script in the sunxi-tools repository called  usb-boot. You can use it as follows:

Usage: ./usb-boot u-boot-spl.bin u-boot.bin [boot.scr] [kernel script.bin [initramfs]]

u-boot-spl.bin and u-boot.bin are the u-boot binaries which are FEL enabled.

boot.scr is the u-boot script. If you do not specify a file ending with .scr the default is used.

uImage is your compiled kernel image.

script.bin is your hw configuration converted to binary from .fex.

initramfs is an optional initramfs/initrd image in u-boot mkimage format.

= Potential future improvements for U-Boot v2015.07 =

There is quite a lot of room for improvement:
 * Make  recognize and handle both parts (SPL + main binary) of u-boot-sunxi-with-spl.bin instead of only the SPL - as this would avoid the "u-boot-dtb.bin vs. u-boot.bin" issue. A possible syntax could be , where   would indicate the destination address for the main binary.   comes first to be consistent with other fel commands, and might be optional. (If missing, fel could fall back to the previous behaviour, i.e. upload the SPL only.)
 * Allow the 'fel spl' command to also use raw SD card images in addition to just recognizing 'u-boot-sunxi-with-spl.bin' format.
 * Store the magic addresses (CONFIG_SYS_TEXT_BASE, kernel_addr_r, fdt_addr_r, scriptaddr, ramdisk_addr_r) in the EGON header extension in order to avoid the need of passing them to the 'fel' tool as command line parameters.
 * A convenient shortcut command for the 'fel' tool to handle all the pieces in a single command line for booting the whole system. Maybe inspired by the U-Boot 'bootm' command.
 * Single U-Boot binary for both the regular UART serial console and the UART over the MicroSD Breakout configurations. The configuration option can be provided to the 'fel' tool in a command line argument and handed over to to U-Boot in the eGON header extension.

The exact eGON header extension format needs to be formalized. We should also check whether it can provide backwards/forward compatibility with the Allwinner's BOOT0 bootloader.

= Known issues =

Please report problems to https://github.com/linux-sunxi/sunxi-tools/issues

= See also =


 * FEL
 * miniroot