[U-Boot] [PATCH v2 1/2] Add README for the "Falcon" mode

[Thomas Weber <thomas.weber.linux@googlemail.com>]

Hello Stefano,

there are some inconsistency for the writing of the Falcon mode:
"Falcon" mode, Falcon mode, Falcon, falcon, "Falcon mode"

On 11/13/2012 12:11 PM, Stefano Babic wrote:
> Simple howto to add support to a board
> for booting the kernel from SPL ("Falcon" mode).
>
> Signed-off-by: Stefano Babic <sbabic@denx.de>
> ---
> Changes in v2:
> - spelling, language fixes (Andreas Biessman)
> - rewrite some unclear sentences
> - drop CONFIG_SPL_OS_BOOT_KEY
> - make example with twister more exhaustive
>
>  doc/README.falcon |  163 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 163 insertions(+)
>  create mode 100644 doc/README.falcon
>
> diff --git a/doc/README.falcon b/doc/README.falcon
> new file mode 100644
> index 0000000..94126fd
> --- /dev/null
> +++ b/doc/README.falcon
> @@ -0,0 +1,163 @@
> +U-Boot "Falcon" Mode
> +====================
> +
> +Introduction
> +------------
> +
> +This documents provides an overview how to add support for "Falcon" mode
This document provides ...
> +to a board.
> +Falcon mode is introduced to speed up the booting process, allowing
> +to boot a Linux kernel (or whatever image) without a full blown U-Boot.
> +
> +Falcon mode relies on the SPL framework. In fact, to make booting faster,
> +U-Boot is split into two parts: the SPL (Secondary Program Loader) and U-Boot
> +image. In most implementations, SPL is used to start U-Boot when booting from
> +a mass storage, such as NAND or SD-Card. SPL has now support for other media,
> +and can be generalized seen as a way to start an image performing the minimum
> +required initialization. SPL initializes mainly the RAM controller, and after
> +that copies U-Boot image into the memory. The "Falcon" mode extends this way
> +allowing to start the Linux kernel directly from SPL. A new command is added
> +to U-Boot to prepare the parameters that SPL must pass to the kernel, using
> +ATAGS or Device Tree.
> +
> +Falcon adds a command under U-Boot to reuse all code responsible to prepare
> +the interface with the kernel. In usual U-boot systems, these parameters are
U-boot => U-Boot
> +generated each time before loading the kernel, passing to Linux the address
> +in memory where the parameters can be read.
> +With falcon, this snapshot can be saved into persistent storage and SPL is
> +informed to load it before running the kernel.
> +
> +To boot the kernel, these steps under a Falcon-aware U-Boot are required:
> +
> +1. Boot the board into U-Boot.
> +Use the "spl export" command to generate the kernel parameters area or the DT.
> +U-boot runs as when it boots the kernel, but stops before passing the control
> +to the kernel.
> +
> +2. Saves the prepared snapshot into persistent media.
Saves => Save
> +The address where to save it must be configured into board configuration
> +file (CONFIG_CMD_SPL_NAND_OFS for NAND).
> +
> +3. Boot the board into "Falcon" mode. SPL will load the kernel and copy
> +the parameters area to the required address.
> +
> +It is required to implement a custom mechanism to select if SPL loads U-Boot
> +or another image.
> +The value of a GPIO is a simple way to operate the selection, as well as
> +reading a character from the SPL console if CONFIG_SPL_CONSOLE is set.
> +
> +Falcon mode is generally activated by setting CONFIG_SPL_OS_BOOT. This tells
> +SPL that U-Boot is not the only available image that SPL is able to start.
> +
> +Configuration
> +----------------------------
> +CONFIG_CMD_SPL		Enable the "spl export" command.
> +			The command "spl export" is then available in U-Boot
> +			mode
> +CONFIG_SPL_OS_BOOT	Activate Falcon mode.
> +			A board should implement the following functions:
> +
> +CONFIG_SYS_SPL_ARGS_ADDR	Address in RAM where the parameters must be
> +				copied by SPL.
> +				In most cases, it is <start_of_ram> + 0x100
> +
> +CONFIG_SYS_NAND_SPL_KERNEL_OFFS	Offset in NAND where the kernel is stored
> +
> +CONFIG_CMD_SPL_NAND_OFS	Offset in NAND where the parameters area was saved.
> +
> +CONFIG_CMD_SPL_WRITE_SIZE 	Size of the parameters area to be copied
> +
> +Function that a board must implement
> +------------------------------------
> +
> +void spl_board_prepare_for_linux(void) : optional
> +	Called from SPL before starting the kernel
> +
> +spl_start_uboot() : required
> +		Returns "0" if SPL starts the kernel, "1" if U-Boot
> +		must be started.
> +
> +
> +Using spl command
> +-----------------
> +
> +spl - SPL configuration
> +
> +Usage:
> +
> +spl export <img=atags|fdt> [kernel_addr] [fdt_addr if <img> = fdt] - export a kernel parameter image
> +
> +img		: "atags" or "fdt"
> +kernel_addr	: kernel is loaded as part of the boot process, but it is not started.
> +		  This is the address where a kernel image is stored.
> +fdt_addr	: in case of fdt, the address of the device tree.
> +
> +
> +The spl puts its result at a self gained position. The position is defined at compile
> +time or when generating the uImage but not at command line for 'spl export'
> +(see spl_export(): gd->bd->bi_boot_params vs. images.ft_addr).
> +
> +Example (for the twister board):
> +--------------------------------
> +
> +Using mtd names and with the following (default) configuration
> +for mtdparts:
> +
> +device nand0 <omap2-nand.0>, # parts = 9
> + #: name		size		offset		mask_flags
> + 0: MLO                 0x00080000      0x00000000      0
> + 1: u-boot              0x00100000      0x00080000      0
> + 2: env1                0x00040000      0x00180000      0
> + 3: env2                0x00040000      0x001c0000      0
> + 4: kernel              0x00600000      0x00200000      0
> + 5: bootparms           0x00040000      0x00800000      0
> + 6: splashimg           0x00200000      0x00840000      0
> + 7: mini                0x02800000      0x00a40000      0
> + 8: rootfs              0x1cdc0000      0x03240000      0
> +
> +
> +twister => nand read 82000000 kernel
> +
> +NAND read: device 0 offset 0x200000, size 0x600000
> + 6291456 bytes read: OK
> +
> +Now the kernel is in RAM at address 0x82000000
> +
> +twister => spl export atags 0x82000000
> +## Booting kernel from Legacy Image at 82000000 ...
> +   Image Name:   Linux-3.5.0-rc4-14089-gda0b7f4
> +   Image Type:   ARM Linux Kernel Image (uncompressed)
> +   Data Size:    3654808 Bytes = 3.5 MiB
> +   Load Address: 80008000
> +   Entry Point:  80008000
> +   Verifying Checksum ... OK
> +   Loading Kernel Image ... OK
> +OK
> +cmdline subcommand not supported
> +bdt subcommand not supported
> +Argument image is now in RAM at: 0x80000100
> +
> +The result can be checked at address 0x80000100:
> +
> +twister => md 0x80000100
> +80000100: 00000005 54410001 00000000 00000000    ......AT........
> +80000110: 00000000 00000067 54410009 746f6f72    ....g.....ATroot
> +80000120: 65642f3d 666e2f76 77722073 73666e20    =/dev/nfs rw nfs
> +
> +The parameters generated with this step can be saved into NAND at the offset
> +0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS)
> +
> +nand erase.part bootparms
> +nand write 0x80000100 bootparms 0x4000
> +
> +Now the parameters are stored into the NAND flash at the address
> +CONFIG_CMD_SPL_NAND_OFS (=0x800000).
> +
> +Next time, the board can be started into "Falcon mode" moving the
> +setting the gpio (on twister gpio 55 is used) to kernel mode.
> +
> +The kernel is loaded directly by the SPL without passing through U-Boot.
> +
> +Falcon mode was presented at the RMLL 2011. Slides are available at:
I think it was in 2012.
> +
> +http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf

Regards,
Thomas