jcs.org
"Das U-Boot" Source Tree
1.. SPDX-License-Identifier: GPL-2.0-or-later
2
3Falcon Mode
4===========
5
6Introduction
7------------
8
9This document provides an overview of how to add support for Falcon Mode
10to a board.
11
12Falcon Mode is introduced to speed up the booting process, allowing
13to boot a Linux kernel (or whatever image) without a full blown U-Boot.
14
15Falcon Mode relies on the SPL framework. In fact, to make booting faster,
16U-Boot is split into two parts: the SPL (Secondary Program Loader) and U-Boot
17image. In most implementations, SPL is used to start U-Boot when booting from
18a mass storage, such as NAND or SD-Card. SPL has now support for other media,
19and can generally be seen as a way to start an image performing the minimum
20required initialization. SPL mainly initializes the RAM controller, and then
21copies U-Boot image into the memory.
22
23The Falcon Mode extends this way allowing to start the Linux kernel directly
24from SPL. A new command is added to U-Boot to prepare the parameters that SPL
25must pass to the kernel, using ATAGS or Device Tree.
26
27In normal mode, these parameters are generated each time before
28loading the kernel, passing to Linux the address in memory where
29the parameters can be read.
30With Falcon Mode, this snapshot can be saved into persistent storage and SPL is
31informed to load it before running the kernel.
32
33To boot the kernel, these steps under a Falcon-aware U-Boot are required:
34
351. 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
412. 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
453. 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
50It is required to implement a custom mechanism to select if SPL loads U-Boot
51or another image.
52
53The value of a GPIO is a simple way to operate the selection, as well as
54reading a character from the SPL console if CONFIG_SPL_CONSOLE is set.
55
56Falcon Mode is generally activated by setting CONFIG_SPL_OS_BOOT. This tells
57SPL that U-Boot is not the only available image that SPL is able to start.
58
59Configuration
60-------------
61
62CONFIG_CMD_SPL
63 Enable the "spl export" command.
64 The command "spl export" is then available in U-Boot mode.
65
66CONFIG_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
70CONFIG_SYS_NAND_SPL_KERNEL_OFFS
71 Offset in NAND where the kernel is stored
72
73CONFIG_CMD_SPL_NAND_OFS
74 Offset in NAND where the parameters area was saved.
75
76CONFIG_CMD_SPL_NOR_OFS
77 Offset in NOR where the parameters area was saved.
78
79CONFIG_CMD_SPL_WRITE_SIZE
80 Size of the parameters area to be copied
81
82CONFIG_SPL_OS_BOOT
83 Activate Falcon Mode.
84
85Function that a board must implement
86------------------------------------
87
88void spl_board_prepare_for_linux(void)
89 optional, called from SPL before starting the kernel
90
91spl_start_uboot()
92 required, returns "0" if SPL should start the kernel, "1" if U-Boot
93 must be started.
94
95Environment variables
96---------------------
97
98A board may chose to look at the environment for decisions about falcon
99mode. In this case the following variables may be supported:
100
101boot_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
105falcon_args_file
106 Filename to load as the 'args' portion of falcon mode rather than the
107 hard-coded value.
108
109falcon_image_file
110 Filename to load as the OS image portion of falcon mode rather than the
111 hard-coded value.
112
113Using spl command
114-----------------
115
116spl - SPL configuration
117
118Usage::
119
120 spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr ]
121
122img
123 "atags" or "fdt"
124
125kernel_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
129initrd_addr
130 Address of initial ramdisk
131 can be set to "-" if fdt_addr without initrd_addr is used
132
133fdt_addr
134 in case of fdt, the address of the device tree.
135
136The *spl export* command does not write to a storage media. The user is
137responsible to transfer the gathered information (assembled ATAGS list
138or prepared FDT) from temporary storage in RAM into persistent storage
139after each run of *spl export*. Unfortunately the position of temporary
140storage can not be predicted nor provided at command line, it depends
141highly on your system setup and your provided data (ATAGS or FDT).
142However at the end of an successful *spl export* run it will print the
143RAM address of temporary storage. The RAM address of FDT will also be
144set in the environment variable *fdtargsaddr*, the new length of the
145prepared FDT will be set in the environment variable *fdtargslen*.
146These environment variables can be used in scripts for writing updated
147FDT to persistent storage.
148
149Now the user have to save the generated BLOB from that printed address
150to the pre-defined address in persistent storage
151(CONFIG_CMD_SPL_NAND_OFS in case of NAND).
152The following example shows how to prepare the data for Falcon Mode on
153twister board with ATAGS BLOB.
154
155The *spl export* command is prepared to work with ATAGS and FDT. However,
156using FDT is at the moment untested. The ppc port (see a3m071 example
157later) prepares the fdt blob with the fdt command instead.
158
159
160Usage on the twister board
161--------------------------
162
163Using mtd names with the following (default) configuration
164for 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
185Now 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
201The 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
208The parameters generated with this step can be saved into NAND at the offset
2090x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS)::
210
211 nand erase.part bootparms
212 nand write 0x80000100 bootparms 0x4000
213
214Now the parameters are stored into the NAND flash at the address
215CONFIG_CMD_SPL_NAND_OFS (=0x800000).
216
217Next time, the board can be started into Falcon Mode moving the
218setting the GPIO (on twister GPIO 55 is used) to kernel mode.
219
220The kernel is loaded directly by the SPL without passing through U-Boot.
221
222Example with FDT: a3m071 board
223------------------------------
224
225To boot the Linux kernel from the SPL, the DT blob (fdt) needs to get
226prepared/patched first. U-Boot usually inserts some dynamic values into
227the DT binary (blob), e.g. autodetected memory size, MAC addresses,
228clocks speeds etc. To generate this patched DT blob, you can use
229the following command:
230
2311. Load fdt blob to SDRAM::
232
233 => tftp 1800000 a3m071/a3m071.dtb
234
2352. Set bootargs as desired for Linux booting (e.g. flash_mtd)::
236
237 => run mtdargs addip2 addtty
238
2393. Use "fdt" commands to patch the DT blob::
240
241 => fdt addr 1800000
242 => fdt boardsetup
243 => fdt chosen
244
2454. Display patched DT blob (optional)::
246
247 => fdt print
248
2495. Save fdt to NOR flash::
250
251 => erase fc060000 fc07ffff
252 => cp.b 1800000 fc060000 10000
253 ...
254
255
256Falcon Mode was presented at the RMLL 2012. Slides are available at:
257
258http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf
259
260Falcon Mode Boot on RISC-V
261--------------------------
262
263Introduction
264~~~~~~~~~~~~
265
266In the RISC-V environment, OpenSBI is required to enable a supervisor mode
267binary to execute certain privileged operations. The typical boot sequence on
268RISC-V is SPL -> OpenSBI -> U-Boot -> Linux kernel. SPL will load and start
269the OpenSBI initializations, then OpenSBI will bring up the next image, U-Boot
270proper. The OpenSBI binary must be prepared in advance of the U-Boot build
271process and it will be packed together with U-Boot into a file called
272u-boot.itb.
273
274The Falcon Mode on RISC-V platforms is a distinct boot sequence. Borrowing
275ideas from the U-Boot Falcon Mode on ARM, it skips the U-Boot proper phase
276in the normal boot process and allows OpenSBI to load and start the Linux
277kernel. Its boot sequence is SPL -> OpenSBI -> Linux kernel. The OpenSBI
278binary and Linux kernel binary must be prepared prior to the U-Boot build
279process and they will be packed together as a FIT image named linux.itb in
280this process.
281
282CONFIG_SPL_LOAD_FIT_OPENSBI_OS_BOOT enables the Falcon Mode boot on RISC-V.
283This configuration setting tells OpenSBI that Linux kernel is its next OS
284image and makes it load and start the kernel afterwards.
285
286Note that the Falcon Mode boot bypasses a lot of initializations by U-Boot.
287If the Linux kernel expects hardware initializations by U-Boot, make sure to
288port the relevant code to the SPL build process.
289
290Configuration
291~~~~~~~~~~~~~
292
293CONFIG_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
297CONFIG_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
302CONFIG_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
310CONFIG_SPL_LOAD_FIT_OPENSBI_OS_BOOT
311 Activates the Falcon Mode boot on RISC-V.
312
313Example for Andes AE350 Board
314~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
315
316A FDT blob is required to boot the Linux kernel from the SPL. Andes AE350
317platforms generally come with a builtin dtb. To load a custom DTB, follow
318these steps:
319
3201. Load the custom DTB to SDRAM::
321
322 => fatload mmc 0:1 0x20000000 user_custom.dtb
323
3242. Set the SPI speed::
325
326 => sf probe 0:0 50000000 0
327
3283. Erase sectors from the SPI Flash::
329
330 => sf erase 0xf0000 0x10000
331
3324. Write the FDT blob to the erased sectors of the Flash::
333
334 => sf write 0x20000000 0xf0000 0x10000
335
336Console 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