Patchwork [U-Boot,v3,1/3] Add README for the "Falcon" mode

login
register
mail settings
Submitter Stefano Babic
Date Nov. 19, 2012, 9:11 a.m.
Message ID <1353316265-24430-1-git-send-email-sbabic@denx.de>
Download mbox | patch
Permalink /patch/199954/
State Superseded
Delegated to: Tom Rini
Headers show

Comments

Stefano Babic - Nov. 19, 2012, 9:11 a.m.
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 v3:
- parameter initrd_addr was removed in V2 (Andreas Biessmann)
- added patch to fix help usage for spl export (Andreas Biessmann)
- Added empty lines (Otavio Salvador)
- add a more exhaustive description explaining that
  spl export does not save into media (Lukasz Majewski).

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 |  173 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 doc/README.falcon
Otavio Salvador - Nov. 19, 2012, 10:14 a.m.
On Mon, Nov 19, 2012 at 7:11 AM, Stefano Babic <sbabic@denx.de> wrote:

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

From the above text it seems the Falcon Mode is already available in
SD-Card however this is not truth. Please rework this so it is clear what
is already working and what needs to be done.
Andreas Bießmann - Nov. 19, 2012, 10:21 a.m.
Dear Stefano Babic,

On 19.11.2012 10:11, 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>

despite a small change

Acked-by: Andreas Bießmann <andreas.devel@googlemail.com>

> ---
> Changes in v3:
> - parameter initrd_addr was removed in V2 (Andreas Biessmann)
> - added patch to fix help usage for spl export (Andreas Biessmann)
> - Added empty lines (Otavio Salvador)
> - add a more exhaustive description explaining that
>   spl export does not save into media (Lukasz Majewski).
> 
> Changes in v2:
> - spelling, language fixes (Andreas Biessman)
> - rewrite some unclear sentences
> - drop CONFIG_SPL_OS_BOOT_KEY
> - make example with twister more exhaustive
> 

<snip>

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

shouldn't we reorder that thing here (move CONFIG_SPL_OS_BOOT down to
the functions)?

Best regards

Andreas Bießmann
Stefano Babic - Nov. 19, 2012, 10:36 a.m.
On 19/11/2012 11:14, Otavio Salvador wrote:
> On Mon, Nov 19, 2012 at 7:11 AM, Stefano Babic <sbabic@denx.de
> <mailto:sbabic@denx.de>> wrote:
> 
>     ... 
> 
>     +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.
> 
> 
> From the above text it seems the Falcon Mode is already available in
> SD-Card however this is not truth. Please rework this so it is clear
> what is already working and what needs to be done.

I reread the sentence, and I am really describing what SPL alone does,
not Falcon mode. SPL is already available for different storage and
there are some boards booting from SD. Check for CONFIG_SPL_MMC_SUPPORT
in include/configs, there are plenty of boards using it.

On the other side, Falcon Mode (SPL + CONFIG_SPL_OS_BOOT) is set only
for two boards, twister and devkit8000, bpth booting from NAND.

Best regards,
Stefano Babic
Stefano Babic - Nov. 19, 2012, 10:37 a.m.
On 19/11/2012 11:21, Andreas Bießmann wrote:
> Dear Stefano Babic,
> 
> On 19.11.2012 10:11, 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>
> 
> despite a small change
> 
> Acked-by: Andreas Bießmann <andreas.devel@googlemail.com>
> 
>> ---
>> Changes in v3:
>> - parameter initrd_addr was removed in V2 (Andreas Biessmann)
>> - added patch to fix help usage for spl export (Andreas Biessmann)
>> - Added empty lines (Otavio Salvador)
>> - add a more exhaustive description explaining that
>>   spl export does not save into media (Lukasz Majewski).
>>
>> Changes in v2:
>> - spelling, language fixes (Andreas Biessman)
>> - rewrite some unclear sentences
>> - drop CONFIG_SPL_OS_BOOT_KEY
>> - make example with twister more exhaustive
>>
> 
> <snip>
> 
>> +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.
>> +
>> +
> 
> shouldn't we reorder that thing here (move CONFIG_SPL_OS_BOOT down to
> the functions)?
> 

arghh..right, I missed this change - I will do in V4.

Best regards,
Stefano Babic

Patch

diff --git a/doc/README.falcon b/doc/README.falcon
new file mode 100644
index 0000000..87279e4
--- /dev/null
+++ b/doc/README.falcon
@@ -0,0 +1,173 @@ 
+U-Boot Falcon Mode
+====================
+
+Introduction
+------------
+
+This document provides an overview how to add support for Falcon Mode
+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 Mode 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
+generated each time before loading the kernel, passing to Linux the address
+in memory where the parameters can be read.
+With Falcon Mode, 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. Save the prepared snapshot into persistent media.
+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] [initrd_addr] [fdt_addr ]
+
+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.
+initrd_addr	: Address of initial ramdisk
+		  can be set to "-" if fdt_addr without initrd img is used
+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).
+
+spl export' does not write directly to a storage media. This command is intended to save
+the prepared information in RAM.  This information must then be transferred to a final destination
+where the SPL will load it, that is defined at compile time
+(CONFIG_CMD_SPL_NAND_OFS in case of NAND).
+
+The user is responsible to save the data into the required media, as described
+on the following example.
+
+Usage on the twister board:
+--------------------------------
+
+Using mtd names 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 2012. Slides are available at:
+
+http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf