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 [options] command arguments... [command...] -v, --verbose			Verbose logging

spl file			Load and execute U-Boot SPL If file additionally contains a main U-Boot binary (u-boot-sunxi-with-spl.bin), this command also transfers that to memory (default address from image), but won't execute it.

uboot file-with-spl		like "spl", but actually starts U-Boot U-Boot execution will take place when the fel utility exits. This allows combining "uboot" with further "write" commands (to transfer other files needed for the boot).

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

Warning: some Linux distributions are already providing packaging for sunxi-tools. However they are also removing certain tools and renaming executables at their discretion. If you encounter troubles with the sunxi-tools package from your distro, then getting sunxi-tools directly from the github repository is always an option.

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

Booting U-Boot over USB
Then just do a regular u-boot build: make CROSS_COMPILE=arm-linux-gnueabihf- Cubietruck_defconfig make CROSS_COMPILE=arm-linux-gnueabihf- -j$(nproc)

And boot it over USB (the 'fel uboot' command requires an up to date version of sunxi-tools): fel uboot u-boot-sunxi-with-spl.bin

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.

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 spl u-boot-sunxi-with-spl.bin

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)!

Alternatively, it is possible to do all of this with just a single 'fel' tool invocation (making the use of the new 'fel uboot' command): fel uboot u-boot-sunxi-with-spl.bin \ write 0x42000000 uImage \ write 0x43000000 sun7i-a20-cubietruck.dtb \ write 0x43100000 boot.scr \ write 0x43300000 rootfs.cpio.lzma.uboot

Legacy mainline U-Boot (v2015.04 and older versions)
Is here for historical reference only (click on the 'Expand' link to see it):

The U-Boot had 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-linux-gnueabihf- Cubietruck_felconfig make CROSS_COMPILE=arm-linux-gnueabihf- -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.

Legacy u-boot-sunxi
Is here for historical reference only (click on the 'Expand' link to see it):

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 =

There is quite a lot of room for improvement:
 * 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.
 * 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 =


 * Allwinner A33 is not supported yet ("MMU not enabled by BROM" error message) - http://irclog.whitequark.org/linux-sunxi/2015-08-15
 * Allwinner H3 is not supported yet (the same "MMU not enabled by BROM" error message)
 * Allwinner A80 is not supported yet

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

= See also =


 * FEL
 * miniroot