Patchwork [U-Boot] Add README for the "Falcon" mode

login
register
mail settings
Submitter Stefano Babic
Date Nov. 12, 2012, 10:59 a.m.
Message ID <1352717979-6284-1-git-send-email-sbabic@denx.de>
Download mbox | patch
Permalink /patch/198359/
State Superseded
Delegated to: Tom Rini
Headers show

Comments

Stefano Babic - Nov. 12, 2012, 10:59 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>
CC: Marek Vasut <marex@denx.de>
CC: Otavio Salvador <otavio@ossystems.com.br>
CC: Tom Rini <trini@ti.com>
---
 doc/README.falcon |  124 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 doc/README.falcon
Andreas Bießmann - Nov. 12, 2012, 11:35 a.m.
Dear Stefano Babic,

On 12.11.2012 11:59, 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>
> CC: Marek Vasut <marex@denx.de>
> CC: Otavio Salvador <otavio@ossystems.com.br>
> CC: Tom Rini <trini@ti.com>
> ---
>  doc/README.falcon |  124 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 124 insertions(+)
>  create mode 100644 doc/README.falcon
> 
> diff --git a/doc/README.falcon b/doc/README.falcon
> new file mode 100644
> index 0000000..d50b8c3
> --- /dev/null
> +++ b/doc/README.falcon
> @@ -0,0 +1,124 @@
> +U-Boot "Falcon" Mode
> +====================
> +
> +Introduction
> +------------
> +
> +This documents 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 mostly implementations, SPL is used to start U-Boot when booting from
-----------------^
In most implementations?

> +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 any kind of image, an in particular a Linux kernel, preparing
------------------------------------------^
and in particular?
------------------------------------------------------------------------^
to achieve that, to be able to boot linux, ... ?
The 'preparing a snapshot...' part of this sentence sounds weird to me.

> +a snapshot of the parameters (ATAG or DT) required by the kernel to boot.
> +
> +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
> +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.
> +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 address required address.
--------------------------------^
first address is not necessary here

> +
> +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_SPL_OS_BOOT_KEY	Common name for GPIO used to select between U-Boot
> +			and kernel image. Optional.
> +
> +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.

In which way interact the CONFIG_SPL_OS_BOOT_KEY with the
spl_start_uboot()? Is both required, can one use one or the other?

> +
> +
> +Using spl command
> +-----------------
> +
> +twister => spl
> +spl - SPL configuration
> +
> +Usage:
> +spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr if <img> = fdt] - export a kernel parameter image
> +	 initrd_img can be set to "-" if fdt_addr without initrd img isused
> +
> +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.
-------------------------------------------------------------^
persistently?
This is the place in mass storage, right?

> +init_addr	: optional for atags - the address where the parameters area is generated into RAM
how about the initrd_addr mentioned above?

> +fdt_addr	: in case of fdt, the address of the device tree.
> +
> +Example (for the twister board):
> +
> +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 parameters generated with this step can be saved into NAND at the offset
> +0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS)
> +
> +Next time, the board can be started into "Falcon mode" moving the
> +CONFIG_SPL_OS_BOOT_KEY GPIO.
> +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:
> +
> +http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf
> 

Best regards

Andreas Bießmann
Stefano Babic - Nov. 12, 2012, 1:02 p.m.
On 12/11/2012 12:35, Andreas Bießmann wrote:

Hi Andreas,

>> +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 mostly implementations, SPL is used to start U-Boot when booting from
> -----------------^
> In most implementations?

Thanks, I fix it.

> 
>> +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 any kind of image, an in particular a Linux kernel, preparing
> ------------------------------------------^
> and in particular?
> ------------------------------------------------------------------------^
> to achieve that, to be able to boot linux, ... ?
> The 'preparing a snapshot...' part of this sentence sounds weird to me.

I am a specialist to write weird sentences. I rewrite this part for V2,
hoping to clarify what I like to explain.

>> +3. Boot the board into "Falcon" mode. SPL will load the kernel and copy
>> +the parameters area to the address required address.
> --------------------------------^
> first address is not necessary here

Right

>> +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.
> 
> In which way interact the CONFIG_SPL_OS_BOOT_KEY with the
> spl_start_uboot()? Is both required, can one use one or the other?

Really checking the implementation, it should be better to remove
CONFIG_SPL_OS_BOOT_KEY. There is not a weak function for
spl_start_uboot(), and I think it is better so. But
CONFIG_SPL_OS_BOOT_KEY is used only inside spl_start_uboot() in the
board's implementation. IMHO it will be better to use a local define for
the GPIOs inside board files, and drop CONFIG_SPL_OS_BOOT_KEY (in
another patch, I mean).

>> +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.
> -------------------------------------------------------------^
> persistently?
> This is the place in mass storage, right?

No, but it could be (for NOR flash, for example). It is the address
where a uImage can be found. It could be in RAM after loading it with
tftp, or in a NOR flash.

In any case, the spl command does not call itself utilities to copy the
kernel from mass storage - such as "nand read" or "fatload", for example.

> 
>> +init_addr	: optional for atags - the address where the parameters area is generated into RAM
> how about the initrd_addr mentioned above?

What is not clear ? init_addr is the destination address, where spl puts
its result. Is it not clear from the description ?

Best regards,
Stefano Babic
Andreas Bießmann - Nov. 12, 2012, 1:33 p.m.
Hi Stefano,

On 12.11.2012 14:02, Stefano Babic wrote:
> On 12/11/2012 12:35, Andreas Bießmann wrote:

<snip>

>>> +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.
>>
>> In which way interact the CONFIG_SPL_OS_BOOT_KEY with the
>> spl_start_uboot()? Is both required, can one use one or the other?
> 
> Really checking the implementation, it should be better to remove
> CONFIG_SPL_OS_BOOT_KEY. There is not a weak function for
> spl_start_uboot(), and I think it is better so. But
> CONFIG_SPL_OS_BOOT_KEY is used only inside spl_start_uboot() in the
> board's implementation. IMHO it will be better to use a local define for
> the GPIOs inside board files, and drop CONFIG_SPL_OS_BOOT_KEY (in
> another patch, I mean).

sounds good to me.

>>> +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.
>> -------------------------------------------------------------^
>> persistently?
>> This is the place in mass storage, right?
> 
> No, but it could be (for NOR flash, for example). It is the address
> where a uImage can be found. It could be in RAM after loading it with
> tftp, or in a NOR flash.
> 
> In any case, the spl command does not call itself utilities to copy the
> kernel from mass storage - such as "nand read" or "fatload", for example.

Ok, thats what I thought. But on first read of this README it was not
clear to me which address I should write there. The step by step example
should have some 'nand read' in it to clarify.

>>> +init_addr	: optional for atags - the address where the parameters area is generated into RAM
>> how about the initrd_addr mentioned above?
> 
> What is not clear ? init_addr is the destination address, where spl puts
> its result. Is it not clear from the description ?

Well, the usage() for spl does not have a 'init_addr' but an
'initrd_addr'. Also your example line states:

---8<---
Usage:
spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr if
<img> = fdt] - export a kernel parameter image
	 initrd_img can be set to "-" if fdt_addr without initrd img isused
--->8---

So for me it is not clear where the 'init_addr' come from.
BTW: I find your detailed description way better than current usage() of
spl command. Would IMHO be useful to add it there in another patch.
another BTW: is there a typo in usage() for spl cmd? One line states
'initrd_addr' but some later it says 'initrd_img'.

And last: 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).

Best regards

Andreas Bießmann
Otavio Salvador - Feb. 11, 2013, 9:12 p.m.
On Mon, Nov 12, 2012 at 8:59 AM, Stefano Babic <sbabic@denx.de> 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>

Could this be updated and resend? This is an interesting feature which
lacks documentation currently.

Regards,
Stefano Babic - Feb. 12, 2013, 8:23 a.m.
On 11/02/2013 22:12, Otavio Salvador wrote:
> On Mon, Nov 12, 2012 at 8:59 AM, Stefano Babic <sbabic@denx.de> 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>
> 
> Could this be updated and resend? This is an interesting feature which
> lacks documentation currently.

Hi Otavio,

you are right, and thanks to point out that the documentation is not yet
merged. I will push a V5 as I promised with fixes for the last comments.

Regards,
Stefano

Patch

diff --git a/doc/README.falcon b/doc/README.falcon
new file mode 100644
index 0000000..d50b8c3
--- /dev/null
+++ b/doc/README.falcon
@@ -0,0 +1,124 @@ 
+U-Boot "Falcon" Mode
+====================
+
+Introduction
+------------
+
+This documents 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 mostly 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 any kind of image, an in particular a Linux kernel, preparing
+a snapshot of the parameters (ATAG or DT) required by the kernel to boot.
+
+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
+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.
+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 address 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_SPL_OS_BOOT_KEY	Common name for GPIO used to select between U-Boot
+			and kernel image. Optional.
+
+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
+-----------------
+
+twister => spl
+spl - SPL configuration
+
+Usage:
+spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr if <img> = fdt] - export a kernel parameter image
+	 initrd_img can be set to "-" if fdt_addr without initrd img isused
+
+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.
+init_addr	: optional for atags - the address where the parameters area is generated into RAM
+fdt_addr	: in case of fdt, the address of the device tree.
+
+Example (for the twister board):
+
+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 parameters generated with this step can be saved into NAND at the offset
+0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS)
+
+Next time, the board can be started into "Falcon mode" moving the
+CONFIG_SPL_OS_BOOT_KEY GPIO.
+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:
+
+http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf