[U-Boot] [PATCH v2 1/2] Add README for the "Falcon" mode
Stefano Babic
sbabic at denx.de
Tue Nov 13 12:11:35 CET 2012
Simple howto to add support to a board
for booting the kernel from SPL ("Falcon" mode).
Signed-off-by: Stefano Babic <sbabic at 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
+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
+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 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:
+
+http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf
--
1.7.9.5
More information about the U-Boot
mailing list