Add README for the "Falcon" mode
PATCH v6 1/3 Add README for the "Falcon" mode
Simple howto to add support to a board
for booting the kernel from SPL ("Falcon" mode).
---
Changes in v6:
- rephrasing some parts to make clearer (Otavio Salvador, Andreas Biessmann)
- including example with FDT from a3m071 (Stefan Roese)
- making clear that using "spl export" with FDT is untested
PPC port uses the fdt command to prepare the blob (Andreas Biessmann)
Changes in v5:
- several fixes for the language, rephrasing some unclear parts (Vikram Narayanan)
Changes in v4:
- fix capitalization, styling, in spl help (Andreas Biessmann)
- move CONFIG_SPL_OS_BOOT before function in doc (Andreas Biessmann)
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 | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 doc/README.falcon
doc/README.falcon new file +209 -0
@@ -0,0 +1,209 @@ +U-Boot Falcon Mode +==================== + +Introduction +------------ + +This document provides an overview of 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 generally be seen as a way to start an image performing the minimum +required initialization. SPL mainly initializes the RAM controller, and then +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. + +In normal mode, 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 which are saved in the persistent 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_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 + +CONFIG_SPL_OS_BOOT Activate Falcon Mode. + +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 should start 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_addr is used +fdt_addr : in case of fdt, the address of the device tree. + +The spl export command does not write to a storage media. The user is +responsible to transfer the gathered information (assembled ATAGS list +or prepared FDT) from temporary storage in RAM into persistant storage +after each run of 'spl export'. Unfortunately the position of temporary +storage can not be predicted nor provided at commandline, it depends +highly on your system setup and your provided data (ATAGS or FDT). +However at the end of an succesful 'spl export' run it will print the +RAM address of temporary storage. +Now the user have to save the generated BLOB from that printed address +to the pre-defined address in persistent storage +(CONFIG_CMD_SPL_NAND_OFS in case of NAND). +The following example shows how to prepare the data for Falcon Mode on +twister board with ATAGS BLOB. + +The "spl export" command is prepared to work with ATAGS and FDT. However, +using FDT is at the moment untested. The ppc port (see a3m071 example +later) prepares the fdt blob with the fdt command instead. + + +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. + +Example with FDT: a3m071 board +------------------------------- + +To boot the Linux kernel from the SPL, the DT blob (fdt) needs to get +prepard/patched first. U-Boot usually inserts some dynamic values into +the DT binary (blob), e.g. autodetected memory size, MAC addresses, +clocks speeds etc. To generate this patched DT blob, you can use +the following command: + +1. Load fdt blob to SDRAM: +=> tftp 1800000 a3m071/a3m071.dtb + +2. Set bootargs as desired for Linux booting (e.g. flash_mtd): +=> run mtdargs addip2 addtty + +3. Use "fdt" commands to patch the DT blob: +=> fdt addr 1800000 +=> fdt boardsetup +=> fdt chosen + +4. Display patched DT blob (optional): +=> fdt print + +5. Save fdt to NOR flash: +=> erase fc060000 fc07ffff +=> cp.b 1800000 fc060000 10000 +... + + +Falcon Mode was presented at the RMLL 2012. Slides are available at: + +http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf
Signature · 1 line
1.7.9.5
PATCH v6 2/3 OMAP3: drop CONFIG_SPL_OS_BOOT_KEY and use local define
CONFIG_SPL_OS_BOOT_KEY is used only in board files. It is not required to have a general CONFIG_ option. Rename it and define it in board directory.
---
Changes in v6: None
Changes in v5: None
Changes in v4: None
Changes in v3: None
Changes in v2: None
board/technexion/twister/twister.c | 8 ++++---- board/technexion/twister/twister.h | 2 ++ board/timll/devkit8000/devkit8000.c | 8 ++++---- board/timll/devkit8000/devkit8000.h | 3 +++ include/configs/devkit8000.h | 1 - include/configs/twister.h | 1 - 6 files changed, 13 insertions(+), 10 deletions(-)
board/technexion/twister/twister.c +4 -4
@@ -165,10 +165,10 @@ void spl_board_prepare_for_linux(void)int spl_start_uboot (void ) {int val =0 ; -if (!gpio_request (CONFIG_SPL_OS_BOOT_KEY ,"U-Boot key" )) { -gpio_direction_input (CONFIG_SPL_OS_BOOT_KEY ); - val =gpio_get_value (CONFIG_SPL_OS_BOOT_KEY ); -gpio_free (CONFIG_SPL_OS_BOOT_KEY ); +if (!gpio_request (SPL_OS_BOOT_KEY ,"U-Boot key" )) { +gpio_direction_input (SPL_OS_BOOT_KEY ); + val =gpio_get_value (SPL_OS_BOOT_KEY ); +gpio_free (SPL_OS_BOOT_KEY ); }return val; }
board/technexion/twister/twister.h +2 -0
@@ -38,6 +38,8 @@ const omap3_sysinfo sysinfo = {#define XR16L2751_UART1_BASE 0x21000000#define XR16L2751_UART2_BASE 0x23000000 +/* GPIO used to select between U-Boot and kernel */ +#define SPL_OS_BOOT_KEY 55/* * IEN - Input Enable
board/timll/devkit8000/devkit8000.c +4 -4
@@ -172,10 +172,10 @@ void spl_board_prepare_for_linux(void)int spl_start_uboot (void ) {int val =0 ; -if (!gpio_request (CONFIG_SPL_OS_BOOT_KEY ,"U-Boot key" )) { -gpio_direction_input (CONFIG_SPL_OS_BOOT_KEY ); - val =gpio_get_value (CONFIG_SPL_OS_BOOT_KEY ); -gpio_free (CONFIG_SPL_OS_BOOT_KEY ); +if (!gpio_request (SPL_OS_BOOT_KEY ,"U-Boot key" )) { +gpio_direction_input (SPL_OS_BOOT_KEY ); + val =gpio_get_value (SPL_OS_BOOT_KEY ); +gpio_free (SPL_OS_BOOT_KEY ); }return !val; }
board/timll/devkit8000/devkit8000.h +3 -0
@@ -32,6 +32,9 @@ const omap3_sysinfo sysinfo = { "NAND", }; +/* GPIO used to select between U-Boot and kernel */ +#define SPL_OS_BOOT_KEY 26 +/* * IEN - Input Enable * IDIS - Input Disable
include/configs/devkit8000.h +0 -1
@@ -354,7 +354,6 @@/* SPL OS boot options */ #define CONFIG_SPL_OS_BOOT -#define CONFIG_SPL_OS_BOOT_KEY 26#define CONFIG_CMD_SPL #define CONFIG_CMD_SPL_WRITE_SIZE 0x400/* 1024 byte */
include/configs/twister.h +0 -1
@@ -58,7 +58,6 @@#define CONFIG_CMD_SPL_NAND_OFS (CONFIG_SYS_NAND_SPL_KERNEL_OFFS+\ 0x600000)#define CONFIG_SPL_OS_BOOT -#define CONFIG_SPL_OS_BOOT_KEY 55#define CONFIG_SYS_SPL_ARGS_ADDR (PHYS_SDRAM_1 + 0x100)#define CONFIG_SPL_BOARD_INIT
Signature · 1 line
1.7.9.5
PATCH v6 2/3 OMAP3: drop CONFIG_SPL_OS_BOOT_KEY and use local define
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Quoted 5 lines · Stefano Babic
CONFIG_SPL_OS_BOOT_KEYis used only in board files. It is not required to have a generalCONFIG_option. Rename it and define it in board directory.Signed-off-by Stefano Babic <[email protected]>
- --
Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQIcBAEBAgAGBQJRKLyOAAoJENk4IS6UOR1WxnoQAKwtVT2wcw7k8IkhNwaT4fsl 5yackDMi+3J4XvLvg/G6FtRrigeQeJkuHzVwyoppgZMsw8/RDUmFPZPxAYstMWoB uwCiu/4dVZOb8XMi0nMiX9zlNhjDna9WwhRgw2ZlOxzCC+rWkIZhMrDRc3J54iBY ECTtHniXO6xYz+io/Et3zkX/f3XpNVNoL1LbTD/OiNvu+Nxo5lYW3VcGE8pUCohu iut7WNl4RWbe40IdbwAbb9I/4ptAUjhzBZj110NHrUNEkHr2NK9PqwPFWxImauBq eSWGQEyC6WfhIdamApmPJs4e4xoTYQh2tkvhn9RTxgq/hpQ4QBuU2oZ/P572mFKC WPuNwu9BxMbx0MAvhREAQ7/mcNXV3ZOcFCCpIY+O5p8qJjOzTSRjNzIBxIhuNVAZ OO2oQcjJ+iOya9eOXiXSOFfhXE5PiCi8XULafMBrx/yEOMcQE0K99q9RnVA8gKam 4nqCHRJry0wrZm5pbEA+aclSsMVqz87cezd46qWFhEEduUETaYcsIuTRUdi/maWj 8lM08b6aywHSML4dFhZCk/GOS37vd4mku94rPV0PO/s9oYPPgLbl0jtyUsOuqvCZ y4/Oyl3OmlhhKMIIc3RDNBuyakGnyuKO/twtgipizBbvu1ZdxT9o5pI7AArvQy4N 3sFaSB53uSHw4IDp8Nq9
=TX4b
-----END PGP SIGNATURE-----
PATCH v6 3/3 SPL: Change description for spl command
In reply to Stefano BabicAdd a more descriptive text to the help of the spl command.
---
Changes in v6: None
Changes in v5: None
Changes in v4: None
Changes in v3: None
Changes in v2: None
common/cmd_spl.c | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)
common/cmd_spl.c +8 -4
@@ -184,7 +184,11 @@ static int do_spl(cmd_tbl_t *cmdtp, int flag, int argc, char * const argv[])U_BOOT_CMD ( spl,6 ,1 , do_spl,"SPL configuration" , -"export <img=atags|fdt> [kernel_addr] [initrd_addr] " -"[fdt_addr if <img> = fdt] - export a kernel parameter image\n" -"\t initrd_img can be set to \"-\" if fdt_addr without initrd img is" -"used" ); +"export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr]\n" +"\timg\t\t\"atags\" or \"fdt\"\n" +"\tkernel_addr\taddress where a kernel image is stored.\n" +"\t\t\tkernel is loaded as part of the boot process, but it is not started.\n" +"\tinitrd_addr\taddress of initial ramdisk\n" +"\t\t\tcan be set to \"-\" if fdt_addr without initrd_addr is used.\n" +"\tfdt_addr\tin case of fdt, the address of the device tree.\n" + );
Signature · 1 line
1.7.9.5
PATCH v6 3/3 SPL: Change description for spl command
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Quoted 3 lines · Stefano Babic
Add a more descriptive text to the help of the spl command.
Signed-off-by Stefano Babic <[email protected]>
- --
Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQIcBAEBAgAGBQJRKLyjAAoJENk4IS6UOR1W/qIQAKx0BsNckAissLCbs+M6XH0S 9d4v+bb6d+CuLFSbmSaFmDUXxU1YblSIDyDYcFHeYYtQA9D5ClDOyI0jFswoAqLE J6jyyoEMCnp6uGJH/YtkNJqj5qkee+MCpuW8qiN0b8AKZ0MyC6gZDeJuHORl2FB+ +iIpjHbMqCs1qXKFQ+oVsnDZftq3lL44X7LvZJpBYkD+f2RBeJd8iB2lELmAN8uL cK9R/mtjzK7D0CbFSwxTt+9Dz3RTOuOVvMWbkG54sklEVmIXCnTW+99I65FK37tK yT/96PCFp9txtFNah0rK/kEcrvOeh9ZHlQPTWTOUjPiPltcfMEDd/bQF8vhcjvWM L8V88XqyNgmiqCbWgfG9JuyWDqXL7YMFnd15pieYEHizyW2EtfBcea3rMubIFOFV RVh+dhBXSPVU8Rn+WMzPut0VyRFTO+7skdGSYHTqz137CShSe1w9ag//RQ1rYdR+ MrEEbSk3B0YZb9/66nYXg5X/6cWqYyPBvXSWUNeOxkMyRP8EGU764XNflnJ+G19D fLjA4CvyLk/YCUQXEIgdlvoivd+B6jnwvqYoRufo83QSYDWB+U6fQvukke9xV4mM q1bKAbgqI2VCjjqv5qlfa09lNgwUV34+GJrtgdiIxftYP+0yKT958yPDdKQ4HQMM kDJgMsR80eut5rlYHTpH
=2h0L
-----END PGP SIGNATURE-----
PATCH v6 1/3 Add README for the "Falcon" mode
In reply to Stefano Babic-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Quoted 4 lines · Stefano Babic
Simple howto to add support to a board for booting the kernel from SPL ("Falcon" mode).
Signed-off-by Stefano Babic <[email protected]>
- --
Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQIcBAEBAgAGBQJRKLxyAAoJENk4IS6UOR1WrqkP/RQMNTPThP1orK8OeQ/Jg71R k/9MwCV9ALXtrmBEfoESMSw9ABjYszLEhCi89OyxfqMtqFj/IP8KCYFk4cuZYmIp 31RYdPO7+lzX4EW0J2YqZovqtR3odbq3FuipFTGnus8XttH2yqeIMrLZYuzwViqe krN5q2kuNUBwaNTImGWxidDjMzmDRXauI/g6VVsa5vaIb1ac1plH8S7QGSDhFhI+ Mo4cOLXd57W7u8SGKn+wUAhB+9UwBHhJpN9skoxozDy6V+IIINhMBzAYljjIbxB+ EHiCIodDDYnyJLwIDOyC73nKsqksJCckPKWoeoHjPooc6K2f7QJUG/udv2uwWCyd Vs54ddlRU2vhc4OWFmU0O7B+nFAILYvaU6SHsbs7S95fRVTFau1xbX1jlPb4BKtD vEAw0HjIPPfWeZY0/Q3c4PTiBU9hLZKZ71+Xg8HybYZCECXPuX4ZWF+PUs29sY5X cDT8ZyOT2bybprmM13siSheOgIWnrHFdM2VlfBP7qsviiUkaOD9zGyEzupUaEmay 58VW9p8kaPtG0BCgpapFSOkIoIYLgMCz6jtpx7O3kHlXXhRn4esEp+P/SKKffdPw EtWCIw9kSdyXP4aC1FvsmT/qZ/ihebCbrtBBNEhlqvUvF+8VMbqpqGpEWryLXt7Z d/JvBxl5i0xGBTYqyriL
=0xCH
-----END PGP SIGNATURE-----
PATCH v6 1/3 Add README for the "Falcon" mode
In reply to Stefano BabicQuoted 10 lines · Stefano Babic
Simple howto to add support to a board
for booting the kernel from SPL ("Falcon" mode).Signed-off-by Stefano Babic <[email protected]>---
Changes in v6:
- rephrasing some parts to make clearer (Otavio Salvador, Andreas Biessmann)
- including example with FDT from a3m071 (Stefan Roese)
- making clear that using "spl export" with FDT is untested
PPC port uses the fdt command to prepare the blob (Andreas Biessmann)
For the series, applied to u-boot/master. Thanks!
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 836 bytes Desc: Digital signature URL: <http://lists.denx.de/pipermail/u-boot/attachments/20130301/ee30809f/attachment.pgp>