doc/develop/falcon.rst

   1 .. SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 Falcon Mode
   4 ===========
   5
   6 Introduction
   7 ------------
   8
   9 This document provides an overview of how to add support for Falcon Mode
  10 to a board.
  11
  12 Falcon Mode is introduced to speed up the booting process, allowing
  13 to boot a Linux kernel (or whatever image) without a full blown U-Boot.
  14
  15 Falcon Mode relies on the SPL framework. In fact, to make booting faster,
  16 U-Boot is split into two parts: the SPL (Secondary Program Loader) and U-Boot
  17 image. In most implementations, SPL is used to start U-Boot when booting from
  18 a mass storage, such as NAND or SD-Card. SPL has now support for other media,
  19 and can generally be seen as a way to start an image performing the minimum
  20 required initialization. SPL mainly initializes the RAM controller, and then
  21 copies U-Boot image into the memory.
  22
  23 The Falcon Mode extends this way allowing to start the Linux kernel directly
  24 from SPL. A new command is added to U-Boot to prepare the parameters that SPL
  25 must pass to the kernel, using ATAGS or Device Tree.
  26
  27 In normal mode, these parameters are generated each time before
  28 loading the kernel, passing to Linux the address in memory where
  29 the parameters can be read.
  30 With Falcon Mode, this snapshot can be saved into persistent storage and SPL is
  31 informed to load it before running the kernel.
  32
  33 To boot the kernel, these steps under a Falcon-aware U-Boot are required:
  34
  35 1. Boot the board into U-Boot.
  36     After loading the desired legacy-format kernel image into memory (and DT as
  37     well, if used), use the "spl export" command to generate the kernel
  38     parameters area or the DT.  U-Boot runs as when it boots the kernel, but
  39     stops before passing the control to the kernel.
  40
  41 2. Save the prepared snapshot into persistent media.
  42     The address where to save it must be configured into board configuration
  43     file (CONFIG_CMD_SPL_NAND_OFS for NAND).
  44
  45 3. Boot the board into Falcon Mode. SPL will load the kernel and copy
  46     the parameters which are saved in the persistent area to the required
  47     address. If a valid uImage is not found at the defined location, U-Boot
  48     will be booted instead.
  49
  50 It is required to implement a custom mechanism to select if SPL loads U-Boot
  51 or another image.
  52
  53 The value of a GPIO is a simple way to operate the selection, as well as
  54 reading a character from the SPL console if CONFIG_SPL_CONSOLE is set.
  55
  56 Falcon Mode is generally activated by setting CONFIG_SPL_OS_BOOT. This tells
  57 SPL that U-Boot is not the only available image that SPL is able to start.
  58
  59 Configuration
  60 -------------
  61
  62 CONFIG_CMD_SPL
  63     Enable the "spl export" command.
  64     The command "spl export" is then available in U-Boot mode.
  65
  66 CONFIG_SPL_PAYLOAD_ARGS_ADDR
  67     Address in RAM where the parameters must be copied by SPL.
  68     In most cases, it is <start_of_ram> + 0x100.
  69
  70 CONFIG_SYS_NAND_SPL_KERNEL_OFFS
  71     Offset in NAND where the kernel is stored
  72
  73 CONFIG_CMD_SPL_NAND_OFS
  74     Offset in NAND where the parameters area was saved.
  75
  76 CONFIG_CMD_SPL_NOR_OFS
  77     Offset in NOR where the parameters area was saved.
  78
  79 CONFIG_CMD_SPL_WRITE_SIZE
  80     Size of the parameters area to be copied
  81
  82 CONFIG_SPL_OS_BOOT
  83     Activate Falcon Mode.
  84
  85 Function that a board must implement
  86 ------------------------------------
  87
  88 void spl_board_prepare_for_linux(void)
  89     optional, called from SPL before starting the kernel
  90
  91 spl_start_uboot()
  92     required, returns "0" if SPL should start the kernel, "1" if U-Boot
  93     must be started.
  94
  95 Environment variables
  96 ---------------------
  97
  98 A board may chose to look at the environment for decisions about falcon
  99 mode.  In this case the following variables may be supported:
 100
 101 boot_os
 102     Set to yes/Yes/true/True/1 to enable booting to OS,
 103     any other value to fall back to U-Boot (including unset)
 104
 105 falcon_args_file
 106     Filename to load as the 'args' portion of falcon mode rather than the
 107     hard-coded value.
 108
 109 falcon_image_file
 110     Filename to load as the OS image portion of falcon mode rather than the
 111     hard-coded value.
 112
 113 Using spl command
 114 -----------------
 115
 116 spl - SPL configuration
 117
 118 Usage::
 119
 120     spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr ]
 121
 122 img
 123     "atags" or "fdt"
 124
 125 kernel_addr
 126     kernel is loaded as part of the boot process, but it is not started.
 127     This is the address where a kernel image is stored.
 128
 129 initrd_addr
 130     Address of initial ramdisk
 131     can be set to "-" if fdt_addr without initrd_addr is used
 132
 133 fdt_addr
 134     in case of fdt, the address of the device tree.
 135
 136 The *spl export* command does not write to a storage media. The user is
 137 responsible to transfer the gathered information (assembled ATAGS list
 138 or prepared FDT) from temporary storage in RAM into persistent storage
 139 after each run of *spl export*. Unfortunately the position of temporary
 140 storage can not be predicted nor provided at command line, it depends
 141 highly on your system setup and your provided data (ATAGS or FDT).
 142 However at the end of an successful *spl export* run it will print the
 143 RAM address of temporary storage. The RAM address of FDT will also be
 144 set in the environment variable *fdtargsaddr*, the new length of the
 145 prepared FDT will be set in the environment variable *fdtargslen*.
 146 These environment variables can be used in scripts for writing updated
 147 FDT to persistent storage.
 148
 149 Now the user have to save the generated BLOB from that printed address
 150 to the pre-defined address in persistent storage
 151 (CONFIG_CMD_SPL_NAND_OFS in case of NAND).
 152 The following example shows how to prepare the data for Falcon Mode on
 153 twister board with ATAGS BLOB.
 154
 155 The *spl export* command is prepared to work with ATAGS and FDT. However,
 156 using FDT is at the moment untested. The ppc port (see a3m071 example
 157 later) prepares the fdt blob with the fdt command instead.
 158
 159
 160 Usage on the twister board
 161 --------------------------
 162
 163 Using mtd names with the following (default) configuration
 164 for mtdparts::
 165
 166     device nand0 <omap2-nand.0>, # parts = 9
 167      #: name        size        offset      mask_flags
 168      0: MLO                 0x00080000      0x00000000      0
 169      1: u-boot              0x00100000      0x00080000      0
 170      2: env1                0x00040000      0x00180000      0
 171      3: env2                0x00040000      0x001c0000      0
 172      4: kernel              0x00600000      0x00200000      0
 173      5: bootparms           0x00040000      0x00800000      0
 174      6: splashimg           0x00200000      0x00840000      0
 175      7: mini                0x02800000      0x00a40000      0
 176      8: rootfs              0x1cdc0000      0x03240000      0
 177
 178 ::
 179
 180     twister => nand read 82000000 kernel
 181
 182     NAND read: device 0 offset 0x200000, size 0x600000
 183     6291456 bytes read: OK
 184
 185 Now the kernel is in RAM at address 0x82000000::
 186
 187     twister => spl export atags 0x82000000
 188     ## Booting kernel from Legacy Image at 82000000 ...
 189        Image Name:   Linux-3.5.0-rc4-14089-gda0b7f4
 190        Image Type:   ARM Linux Kernel Image (uncompressed)
 191        Data Size:    3654808 Bytes = 3.5 MiB
 192        Load Address: 80008000
 193        Entry Point:  80008000
 194        Verifying Checksum ... OK
 195        Loading Kernel Image ... OK
 196     OK
 197     cmdline subcommand not supported
 198     bdt subcommand not supported
 199     Argument image is now in RAM at: 0x80000100
 200
 201 The result can be checked at address 0x80000100::
 202
 203     twister => md 0x80000100
 204     80000100: 00000005 54410001 00000000 00000000    ......AT........
 205     80000110: 00000000 00000067 54410009 746f6f72    ....g.....ATroot
 206     80000120: 65642f3d 666e2f76 77722073 73666e20    =/dev/nfs rw nfs
 207
 208 The parameters generated with this step can be saved into NAND at the offset
 209 0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS)::
 210
 211     nand erase.part bootparms
 212     nand write 0x80000100 bootparms 0x4000
 213
 214 Now the parameters are stored into the NAND flash at the address
 215 CONFIG_CMD_SPL_NAND_OFS (=0x800000).
 216
 217 Next time, the board can be started into Falcon Mode moving the
 218 setting the GPIO (on twister GPIO 55 is used) to kernel mode.
 219
 220 The kernel is loaded directly by the SPL without passing through U-Boot.
 221
 222 Example with FDT: a3m071 board
 223 ------------------------------
 224
 225 To boot the Linux kernel from the SPL, the DT blob (fdt) needs to get
 226 prepared/patched first. U-Boot usually inserts some dynamic values into
 227 the DT binary (blob), e.g. autodetected memory size, MAC addresses,
 228 clocks speeds etc. To generate this patched DT blob, you can use
 229 the following command:
 230
 231 1. Load fdt blob to SDRAM::
 232
 233         => tftp 1800000 a3m071/a3m071.dtb
 234
 235 2. Set bootargs as desired for Linux booting (e.g. flash_mtd)::
 236
 237         => run mtdargs addip2 addtty
 238
 239 3. Use "fdt" commands to patch the DT blob::
 240
 241         => fdt addr 1800000
 242         => fdt boardsetup
 243         => fdt chosen
 244
 245 4. Display patched DT blob (optional)::
 246
 247         => fdt print
 248
 249 5. Save fdt to NOR flash::
 250
 251         => erase fc060000 fc07ffff
 252         => cp.b 1800000 fc060000 10000
 253         ...
 254
 255
 256 Falcon Mode was presented at the RMLL 2012. Slides are available at:
 257
 258 http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf
 259
 260 Falcon Mode Boot on RISC-V
 261 --------------------------
 262
 263 Introduction
 264 ~~~~~~~~~~~~
 265
 266 In the RISC-V environment, OpenSBI is required to enable a supervisor mode
 267 binary to execute certain privileged operations. The typical boot sequence on
 268 RISC-V is SPL -> OpenSBI -> U-Boot -> Linux kernel. SPL will load and start
 269 the OpenSBI initializations, then OpenSBI will bring up the next image, U-Boot
 270 proper. The OpenSBI binary must be prepared in advance of the U-Boot build
 271 process and it will be packed together with U-Boot into a file called
 272 u-boot.itb.
 273
 274 The Falcon Mode on RISC-V platforms is a distinct boot sequence. Borrowing
 275 ideas from the U-Boot Falcon Mode on ARM, it skips the U-Boot proper phase
 276 in the normal boot process and allows OpenSBI to load and start the Linux
 277 kernel. Its boot sequence is SPL -> OpenSBI -> Linux kernel. The OpenSBI
 278 binary and Linux kernel binary must be prepared prior to the U-Boot build
 279 process and they will be packed together as a FIT image named linux.itb in
 280 this process.
 281
 282 CONFIG_SPL_LOAD_FIT_OPENSBI_OS_BOOT enables the Falcon Mode boot on RISC-V.
 283 This configuration setting tells OpenSBI that Linux kernel is its next OS
 284 image and makes it load and start the kernel afterwards.
 285
 286 Note that the Falcon Mode boot bypasses a lot of initializations by U-Boot.
 287 If the Linux kernel expects hardware initializations by U-Boot, make sure to
 288 port the relevant code to the SPL build process.
 289
 290 Configuration
 291 ~~~~~~~~~~~~~
 292
 293 CONFIG_SPL_LOAD_FIT_ADDRESS
 294     Specifies the address to load u-boot.itb in a normal boot. When the Falcon
 295     Mode boot is enabled, it specifies the load address of linux.itb.
 296
 297 CONFIG_SYS_TEXT_BASE
 298     Specifies the address of the text section for a u-boot proper in a normal
 299     boot. When the Falcon Mode boot is enabled, it specifies the text section
 300     address for the Linux kernel image.
 301
 302 CONFIG_SPL_PAYLOAD_ARGS_ADDR
 303     The address in the RAM to which the FDT blob is to be moved by the SPL.
 304     SPL places the FDT blob right after the kernel. As the kernel does not
 305     include the BSS section in its size calculation, SPL ends up placing
 306     the FDT blob within the BSS section of the kernel. This may cause the
 307     FDT blob to be cleared during kernel BSS initialization. To avoid the
 308     issue, be sure to move the FDT blob out of the kernel first.
 309
 310 CONFIG_SPL_LOAD_FIT_OPENSBI_OS_BOOT
 311     Activates the Falcon Mode boot on RISC-V.
 312
 313 Example for Andes AE350 Board
 314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 315
 316 A FDT blob is required to boot the Linux kernel from the SPL. Andes AE350
 317 platforms generally come with a builtin dtb. To load a custom DTB, follow
 318 these steps:
 319
 320 1. Load the custom DTB to SDRAM::
 321
 322         => fatload mmc 0:1 0x20000000 user_custom.dtb
 323
 324 2. Set the SPI speed::
 325
 326         => sf probe 0:0 50000000 0
 327
 328 3. Erase sectors from the SPI Flash::
 329
 330         => sf erase 0xf0000 0x10000
 331
 332 4. Write the FDT blob to the erased sectors of the Flash::
 333
 334         => sf write 0x20000000 0xf0000 0x10000
 335
 336 Console Log of AE350 Falcon Mode Boot
 337 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 338
 339 ::
 340
 341         U-Boot SPL 2023.01-00031-g777ecdea66 (Oct 31 2023 - 18:41:36 +0800)
 342         Trying to boot from RAM
 343
 344         OpenSBI v1.2-51-g7304e42
 345            ____                    _____ ____ _____
 346           / __ \                  / ____|  _ \_   _|
 347          | |  | |_ __   ___ _ __ | (___ | |_) || |
 348          | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
 349          | |__| | |_) |  __/ | | |____) | |_) || |_
 350           \____/| .__/ \___|_| |_|_____/|____/_____|
 351                 | |
 352                 |_|
 353
 354         Platform Name             : andestech,ax25
 355         Platform Features         : medeleg
 356         Platform HART Count       : 1
 357         Platform IPI Device       : andes_plicsw
 358         Platform Timer Device     : andes_plmt @ 60000000Hz
 359         Platform Console Device   : uart8250
 360         Platform HSM Device       : andes_smu
 361         Platform PMU Device       : andes_pmu
 362         Platform Reboot Device    : atcwdt200
 363         Platform Shutdown Device  : ---
 364         Firmware Base             : 0x0
 365         Firmware Size             : 196 KB
 366         Runtime SBI Version       : 1.0
 367
 368         Domain0 Name              : root
 369         Domain0 Boot HART         : 0
 370         Domain0 HARTs             : 0*
 371         Domain0 Region00          : 0x0000000000000000-0x000000000003ffff ()
 372         Domain0 Region01          : 0x00000000e6000000-0x00000000e60fffff (I,R)
 373         Domain0 Region02          : 0x00000000e6400000-0x00000000e67fffff (I)
 374         Domain0 Region03          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
 375         Domain0 Next Address      : 0x0000000001800000
 376         Domain0 Next Arg1         : 0x0000000001700000
 377         Domain0 Next Mode         : S-mode
 378         Domain0 SysReset          : yes
 379
 380         Boot HART ID              : 0
 381         Boot HART Domain          : root
 382         Boot HART Priv Version    : v1.11
 383         Boot HART Base ISA        : rv64imafdcx
 384         Boot HART ISA Extensions  : none
 385         Boot HART PMP Count       : 8
 386         Boot HART PMP Granularity : 4
 387         Boot HART PMP Address Bits: 31
 388         Boot HART MHPM Count      : 4
 389         Boot HART MHPM Bits       : 64
 390         Boot HART MIDELEG         : 0x0000000000000222
 391         Boot HART MEDELEG         : 0x000000000000b109
 392         [    0.000000] Linux version 6.1.47-09019-g0584b09ad862-dirty
 393         [    0.000000] OF: fdt: Ignoring memory range 0x0 - 0x1800000
 394         [    0.000000] Machine model: andestech,ax25
 395         [    0.000000] earlycon: sbi0 at I/O port 0x0 (options '')
 396         [    0.000000] printk: bootconsole [sbi0] enabled
 397         [    0.000000] Disabled 4-level and 5-level paging
 398         [    0.000000] efi: UEFI not found.
 399         [    0.000000] Zone ranges:
 400         [    0.000000]   DMA32    [mem 0x0000000001800000-0x000000003fffffff]
 401         [    0.000000]   Normal   empty
 402         [    0.000000] Movable zone start for each node
 403         [    0.000000] Early memory node ranges
 404         [    0.000000]   node   0: [mem 0x0000000001800000-0x000000003fffffff]
 405         [    0.000000] Initmem setup node 0 [mem 0x0000000001800000-0x000000003fffffff]
 406         [    0.000000] SBI specification v1.0 detected
 407         [    0.000000] SBI implementation ID=0x1 Version=0x10002
 408         [    0.000000] SBI TIME extension detected
 409         [    0.000000] SBI IPI extension detected
 410         [    0.000000] SBI RFENCE extension detected
 411         [    0.000000] SBI SRST extension detected
 412         [    0.000000] SBI HSM extension detected
 413         [    0.000000] riscv: base ISA extensions acim
 414         [    0.000000] riscv: ELF capabilities acim
 415         [    0.000000] percpu: Embedded 18 pages/cpu s35000 r8192 d30536 u73728
 416         [    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 252500