[U-Boot] [PATCH] imx: ventana: update README with Falcon mode documentation

[Stefano Babic]

On 22/05/2015 00:59, Tim Harvey wrote:
> Signed-off-by: Tim Harvey <tharvey at gateworks.com>
> ---
>  board/gateworks/gw_ventana/README | 169 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 169 insertions(+)
> 
> diff --git a/board/gateworks/gw_ventana/README b/board/gateworks/gw_ventana/README
> index 74698b7..697e5c8 100644
> --- a/board/gateworks/gw_ventana/README
> +++ b/board/gateworks/gw_ventana/README
> @@ -149,3 +149,172 @@ This information is taken from:
>  
>  More details about the i.MX6 BOOT ROM can be found in the IMX6 reference manual.
>  
> +4. Falcon Mode
> +------------------------------
> +
> +The Gateworks Ventana board config enables Falcon mode (CONFIG_SPL_OS_BOOT)
> +which allows the SPL to boot directly to an OS instead of to U-Boot
> +(u-boot.img) thus acheiving a faster overall boot time. The time savings
> +depends on your boot medium (ie NAND Flash vs micro-SD) and size/storage
> +of the OS. The time savings can be anywhere from 2 seconds (256MB NAND Flash
> +with ~1MB kernel) to 6 seconds or more (2GB NAND Flash with ~6 kernel)
> +
> +The Gateworks Ventana board supports Falcon mode for the following boot
> +medium:
> + - NAND flash
> + - micro-SD
> +
> +For all boot mediums, raw mode is used. While support of more complex storage
> +such as files on top of FAT/EXT filesystem is possible but not practical
> +as the size of the SPL is fairly limitted (to 64KB based on the smallest
> +size of available IMX6 iRAM) as well as the fact that this would increase
> +OS load time which defeats the purpose of Falcon mode in the first place.
> +
> +The SPL decides to boot either U-Boot (u-boot.img) or the OS (args + kernel)
> +based on the return value of the spl_start_uboot() function. While often
> +this can simply be the state of a GPIO based pushbutton or DIP switch, for
> +Gateworks Ventana, we use the U-Boot environment 'boot_os' variable which if
> +set to '1' will choose to boot the OS rather than U-Boot. While the choice
> +of adding env support to the SPL adds a little bit of time to the boot
> +process as well as (significant really) SPL code space this was deemed most
> +flexible as within the large variety of Gateworks Ventana boards not all of
> +them have a user pushbutton and that pushbutton may be configured as a hard
> +reset per user configuration.
> +
> +To use Falcon mode it is required that you first 'prepare' the 'args' data
> +that is stored on your boot medium along with the kernel (which can be any
> +OS or bare-metal application). In the case of the Linux kernel the 'args'
> +is the flatenned device-tree which normally gets altered prior to booting linux
> +by U-Boot's 'bootm' command. To achieve this for SPL we use the
> +'spl export fdt' command in U-Boot after loading the kernel and dtb which
> +will go through the same process of modifying the device-tree for the board
> +being executed on but not jump to the kernel. This allows you to save the
> +args data to the location the SPL expects it and then enable Falcon mode.
> +
> +It is important to realize that there are certain values in the dtb that
> +are board model specific (IMX6Q vs IMX6DL for example) and board specific
> +(board serial number, MAC addrs) so you do not want to use the 'args'
> +data prepared from one board on another board.
> +
> +4.1. Falcon Mode on NAND flash
> +------------------------------
> +To prepare a Gateworks Ventana board that boots from NAND flash for Falcon
> +mode you must program your flash such that the 'args' and 'kernel' are
> +located where defined at compile time by the following:
> +   CONFIG_CMD_SPL_NAND_OFS         17MB - offset of 'args'
> +   CONFIG_SYS_NAND_SPL_KERNEL_OFFS 18MB - offset of 'kernel'
> +
> +The location offsets defined above are defaults chosen by Gateworks and are
> +flexible if you want to re-define them.
> +
> +The following steps executed in U-Boot will configure Falcon mode for NAND
> +using rootfs (ubi), kernel (uImage), and dtb from the network:
> +
> + # change mtd partitions to the above mapping
> + Ventana > setenv mtdparts 'mtdparts=nand:14m(spl),2m(uboot),1m(env),1m(args),10m(kernel),-(rootfs)'
> +
> + # flash rootfs (at 28MB)
> + Ventana > tftp ${loadaddr} rootfs_${flash_layout}.ubi && \
> +   nand erase.part rootfs && nand write ${loadaddr} rootfs ${filesize}
> +
> + # load the device-tree
> + Ventana > tftp ${fdt_addr} ventana/${fdt_file2}
> +
> + # load the kernel
> + Ventana > tftp ${loadaddr} ventana/uImage
> +
> + # flash kernel (at 18MB)
> + Ventana > nand erase.part kernel && nand write ${loadaddr} kernel ${filesize}
> +
> + # set kernel args for the console and rootfs (used by spl export)
> + Ventana > setenv bootargs 'console=ttymxc1,115200 root=ubi0:rootfs ubi.mtd=5 rootfstype=ubifs quiet'
> +
> + # create args based on env, board, EEPROM, and dtb
> + Ventana > spl export fdt ${loadaddr} - ${fdt_addr}
> +
> + # flash args (at 17MB)
> + Ventana > nand erase.part args && nand write 18000000 args 100000
> +
> + # set boot_os env var to enable booting to Linux
> + Ventana > setenv boot_os 1 && saveenv
> +
> +Be sure to adjust 'bootargs' above to your OS needs (this will be different
> +for various distros such as OpenWrt, Yocto, Android, etc). You can use the
> +value obtained from 'cat /proc/cmdline' when booted to Linux.
> +
> +This information is taken from:
> +  http://trac.gateworks.com/wiki/ventana/bootloader/falcon-mode#nand
> +
> +
> +4.2. Falcon Mode on micro-SD card
> +---------------------------------
> +
> +To prepare a Gateworks Ventana board with a primary boot device of micro-SD
> +you first need to make sure you build U-Boot with CONFIG_ENV_IS_IN_MMC
> +instead of CONFIG_ENV_IS_IN_NAND.
> +
> +For micro-SD based Falcon mode you must program your micro-SD such that
> +the 'args' and 'kernel' are located where defined at compile time
> +by the following:
> +   CONFIG_SYS_MMCSD_RAW_MODE_ARGS_SECTOR 0x800 (1MB) - offset of 'args'
> +   CONFIG_SYS_MMCSD_RAW_MODE_KERNEL_SECTOR 0x1000 (2MB) - offset of 'kernel'
> +
> +The location offsets defined above are defaults chosen by Gateworks and are
> +flexible if you want to re-define them.
> +
> +First you must prepare a micro-SD such that the SPL can be loaded by the
> +IMX6 BOOT ROM (fixed offset of 1KB), and U-Boot can be loaded by the SPL
> +(fixed offset of 69KB defined by CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR).
> +
> +The following shell commands are executed on a Linux host (adjust DEV to the
> +block storage device of your micro-SD):
> +
> + DEV=/dev/sdc
> + # zero out 1MB of device
> + sudo dd if=/dev/zero of=$DEV count=1 bs=1M oflag=sync status=none && sync
> + # copy SPL to 1KB offset
> + sudo dd if=SPL of=$DEV bs=1K seek=1 oflag=sync status=none && sync
> + # copy U-Boot to 69KB offset
> + sudo dd if=u-boot.img of=$DEV bs=1K seek=69 oflag=sync status=none && sync
> + # create a partition table with a single rootfs partition starting at 10MB
> + printf "10,,L\n" | sudo sfdisk --in-order --no-reread -L -uM $DEV && sync
> + # format partition
> + sudo mkfs.ext4 -L root ${DEV}1
> + # mount the partition
> + sudo udisks --mount ${DEV}1
> + # extract filesystem
> + sudo tar xvf rootfs.tar.gz -C /media/root
> + # flush and unmount
> + sync && sudo umount /media/root
> +
> +Now that your micro-SD partitioning has been adjusted to leave room for the
> +raw 'args' and 'kernel' data boot the board with the prepared micro-SD, break
> +out in U-Boot and use the following to enable Falcon mode:
> +
> + # load device-tree from rootfs
> + Ventana > ext2load mmc 0:1 ${fdt_addr} boot/${fdt_file2}
> +
> + # load kernel from rootfs
> + Ventana > ext2load mmc 0:1 ${loadaddr} boot/uImage
> +
> + # write kernel at 2MB offset
> + Ventana > mmc write ${loadaddr} 0x1000 0x4000
> +
> + # setup kernel bootargs
> + Ventana > setenv bootargs 'console=ttymxc1,115200 root=/dev/mmcblk0p1 rootfstype=ext4 rootwait rw'
> +
> + # prepare args
> + Ventana > spl export fdt ${loadaddr} - ${fdt_addr}
> +
> + # write args 1MB data (0x800 sectors) to 1MB offset (0x800 sectors)
> + Ventana > mmc write 18000000 0x800 0x800
> +
> + # set boot_os to enable falcon mode
> + Ventana > setenv boot_os 1 && saveenv
> +
> +Be sure to adjust 'bootargs' above to your OS needs (this will be different
> +for various distros such as OpenWrt, Yocto, Android, etc). You can use the
> +value obtained from 'cat /proc/cmdline' when booted to Linux.
> +
> +This information is taken from:
> +  http://trac.gateworks.com/wiki/ventana/bootloader/falcon-mode#microsd
> 

Applied to u-boot-imx, thanks!

Best regards,
Stefano Babic

-- 
=====================================================================
DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-53 Fax: +49-8142-66989-80 Email: sbabic at denx.de
=====================================================================