]>
Commit | Line | Data |
---|---|---|
3e1b3939 SB |
1 | U-Boot Falcon Mode |
2 | ==================== | |
3 | ||
4 | Introduction | |
5 | ------------ | |
6 | ||
7 | This document provides an overview of how to add support for Falcon Mode | |
8 | to a board. | |
9 | ||
10 | Falcon Mode is introduced to speed up the booting process, allowing | |
11 | to boot a Linux kernel (or whatever image) without a full blown U-Boot. | |
12 | ||
13 | Falcon Mode relies on the SPL framework. In fact, to make booting faster, | |
14 | U-Boot is split into two parts: the SPL (Secondary Program Loader) and U-Boot | |
15 | image. In most implementations, SPL is used to start U-Boot when booting from | |
16 | a mass storage, such as NAND or SD-Card. SPL has now support for other media, | |
17 | and can generally be seen as a way to start an image performing the minimum | |
18 | required initialization. SPL mainly initializes the RAM controller, and then | |
19 | copies U-Boot image into the memory. | |
20 | ||
21 | The Falcon Mode extends this way allowing to start the Linux kernel directly | |
22 | from SPL. A new command is added to U-Boot to prepare the parameters that SPL | |
23 | must pass to the kernel, using ATAGS or Device Tree. | |
24 | ||
25 | In normal mode, these parameters are generated each time before | |
26 | loading the kernel, passing to Linux the address in memory where | |
27 | the parameters can be read. | |
28 | With Falcon Mode, this snapshot can be saved into persistent storage and SPL is | |
29 | informed to load it before running the kernel. | |
30 | ||
31 | To boot the kernel, these steps under a Falcon-aware U-Boot are required: | |
32 | ||
33 | 1. Boot the board into U-Boot. | |
34 | Use the "spl export" command to generate the kernel parameters area or the DT. | |
35 | U-Boot runs as when it boots the kernel, but stops before passing the control | |
36 | to the kernel. | |
37 | ||
38 | 2. Save the prepared snapshot into persistent media. | |
39 | The address where to save it must be configured into board configuration | |
40 | file (CONFIG_CMD_SPL_NAND_OFS for NAND). | |
41 | ||
42 | 3. Boot the board into Falcon Mode. SPL will load the kernel and copy | |
43 | the parameters which are saved in the persistent area to the required address. | |
d118d766 TR |
44 | If a valid uImage is not found at the defined location, U-Boot will be |
45 | booted instead. | |
3e1b3939 SB |
46 | |
47 | It is required to implement a custom mechanism to select if SPL loads U-Boot | |
48 | or another image. | |
49 | ||
50 | The value of a GPIO is a simple way to operate the selection, as well as | |
51 | reading a character from the SPL console if CONFIG_SPL_CONSOLE is set. | |
52 | ||
53 | Falcon Mode is generally activated by setting CONFIG_SPL_OS_BOOT. This tells | |
54 | SPL that U-Boot is not the only available image that SPL is able to start. | |
55 | ||
56 | Configuration | |
57 | ---------------------------- | |
58 | CONFIG_CMD_SPL Enable the "spl export" command. | |
59 | The command "spl export" is then available in U-Boot | |
60 | mode | |
61 | CONFIG_SYS_SPL_ARGS_ADDR Address in RAM where the parameters must be | |
62 | copied by SPL. | |
63 | In most cases, it is <start_of_ram> + 0x100 | |
64 | ||
65 | CONFIG_SYS_NAND_SPL_KERNEL_OFFS Offset in NAND where the kernel is stored | |
66 | ||
67 | CONFIG_CMD_SPL_NAND_OFS Offset in NAND where the parameters area was saved. | |
68 | ||
69 | CONFIG_CMD_SPL_WRITE_SIZE Size of the parameters area to be copied | |
70 | ||
71 | CONFIG_SPL_OS_BOOT Activate Falcon Mode. | |
72 | ||
73 | Function that a board must implement | |
74 | ------------------------------------ | |
75 | ||
76 | void spl_board_prepare_for_linux(void) : optional | |
77 | Called from SPL before starting the kernel | |
78 | ||
79 | spl_start_uboot() : required | |
80 | Returns "0" if SPL should start the kernel, "1" if U-Boot | |
81 | must be started. | |
82 | ||
3523df00 TR |
83 | Environment variables |
84 | --------------------- | |
85 | ||
86 | A board may chose to look at the environment for decisions about falcon | |
87 | mode. In this case the following variables may be supported: | |
88 | ||
89 | boot_os : Set to yes/Yes/true/True/1 to enable booting to OS, | |
90 | any other value to fall back to U-Boot (including | |
91 | unset) | |
ae1590ed TR |
92 | falcon_args_file : Filename to load as the 'args' portion of falcon mode |
93 | rather than the hard-coded value. | |
94 | falcon_image_file : Filename to load as the OS image portion of falcon | |
95 | mode rather than the hard-coded value. | |
3e1b3939 SB |
96 | |
97 | Using spl command | |
98 | ----------------- | |
99 | ||
100 | spl - SPL configuration | |
101 | ||
102 | Usage: | |
103 | ||
104 | spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr ] | |
105 | ||
106 | img : "atags" or "fdt" | |
107 | kernel_addr : kernel is loaded as part of the boot process, but it is not started. | |
108 | This is the address where a kernel image is stored. | |
109 | initrd_addr : Address of initial ramdisk | |
110 | can be set to "-" if fdt_addr without initrd_addr is used | |
111 | fdt_addr : in case of fdt, the address of the device tree. | |
112 | ||
113 | The spl export command does not write to a storage media. The user is | |
114 | responsible to transfer the gathered information (assembled ATAGS list | |
115 | or prepared FDT) from temporary storage in RAM into persistant storage | |
116 | after each run of 'spl export'. Unfortunately the position of temporary | |
117 | storage can not be predicted nor provided at commandline, it depends | |
118 | highly on your system setup and your provided data (ATAGS or FDT). | |
119 | However at the end of an succesful 'spl export' run it will print the | |
120 | RAM address of temporary storage. | |
121 | Now the user have to save the generated BLOB from that printed address | |
122 | to the pre-defined address in persistent storage | |
123 | (CONFIG_CMD_SPL_NAND_OFS in case of NAND). | |
124 | The following example shows how to prepare the data for Falcon Mode on | |
125 | twister board with ATAGS BLOB. | |
126 | ||
127 | The "spl export" command is prepared to work with ATAGS and FDT. However, | |
128 | using FDT is at the moment untested. The ppc port (see a3m071 example | |
129 | later) prepares the fdt blob with the fdt command instead. | |
130 | ||
131 | ||
132 | Usage on the twister board: | |
133 | -------------------------------- | |
134 | ||
135 | Using mtd names with the following (default) configuration | |
136 | for mtdparts: | |
137 | ||
138 | device nand0 <omap2-nand.0>, # parts = 9 | |
139 | #: name size offset mask_flags | |
140 | 0: MLO 0x00080000 0x00000000 0 | |
141 | 1: u-boot 0x00100000 0x00080000 0 | |
142 | 2: env1 0x00040000 0x00180000 0 | |
143 | 3: env2 0x00040000 0x001c0000 0 | |
144 | 4: kernel 0x00600000 0x00200000 0 | |
145 | 5: bootparms 0x00040000 0x00800000 0 | |
146 | 6: splashimg 0x00200000 0x00840000 0 | |
147 | 7: mini 0x02800000 0x00a40000 0 | |
148 | 8: rootfs 0x1cdc0000 0x03240000 0 | |
149 | ||
150 | ||
151 | twister => nand read 82000000 kernel | |
152 | ||
153 | NAND read: device 0 offset 0x200000, size 0x600000 | |
154 | 6291456 bytes read: OK | |
155 | ||
156 | Now the kernel is in RAM at address 0x82000000 | |
157 | ||
158 | twister => spl export atags 0x82000000 | |
159 | ## Booting kernel from Legacy Image at 82000000 ... | |
160 | Image Name: Linux-3.5.0-rc4-14089-gda0b7f4 | |
161 | Image Type: ARM Linux Kernel Image (uncompressed) | |
162 | Data Size: 3654808 Bytes = 3.5 MiB | |
163 | Load Address: 80008000 | |
164 | Entry Point: 80008000 | |
165 | Verifying Checksum ... OK | |
166 | Loading Kernel Image ... OK | |
167 | OK | |
168 | cmdline subcommand not supported | |
169 | bdt subcommand not supported | |
170 | Argument image is now in RAM at: 0x80000100 | |
171 | ||
172 | The result can be checked at address 0x80000100: | |
173 | ||
174 | twister => md 0x80000100 | |
175 | 80000100: 00000005 54410001 00000000 00000000 ......AT........ | |
176 | 80000110: 00000000 00000067 54410009 746f6f72 ....g.....ATroot | |
177 | 80000120: 65642f3d 666e2f76 77722073 73666e20 =/dev/nfs rw nfs | |
178 | ||
179 | The parameters generated with this step can be saved into NAND at the offset | |
180 | 0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS) | |
181 | ||
182 | nand erase.part bootparms | |
183 | nand write 0x80000100 bootparms 0x4000 | |
184 | ||
185 | Now the parameters are stored into the NAND flash at the address | |
186 | CONFIG_CMD_SPL_NAND_OFS (=0x800000). | |
187 | ||
188 | Next time, the board can be started into Falcon Mode moving the | |
189 | setting the gpio (on twister gpio 55 is used) to kernel mode. | |
190 | ||
191 | The kernel is loaded directly by the SPL without passing through U-Boot. | |
192 | ||
193 | Example with FDT: a3m071 board | |
194 | ------------------------------- | |
195 | ||
196 | To boot the Linux kernel from the SPL, the DT blob (fdt) needs to get | |
197 | prepard/patched first. U-Boot usually inserts some dynamic values into | |
198 | the DT binary (blob), e.g. autodetected memory size, MAC addresses, | |
199 | clocks speeds etc. To generate this patched DT blob, you can use | |
200 | the following command: | |
201 | ||
202 | 1. Load fdt blob to SDRAM: | |
203 | => tftp 1800000 a3m071/a3m071.dtb | |
204 | ||
205 | 2. Set bootargs as desired for Linux booting (e.g. flash_mtd): | |
206 | => run mtdargs addip2 addtty | |
207 | ||
208 | 3. Use "fdt" commands to patch the DT blob: | |
209 | => fdt addr 1800000 | |
210 | => fdt boardsetup | |
211 | => fdt chosen | |
212 | ||
213 | 4. Display patched DT blob (optional): | |
214 | => fdt print | |
215 | ||
216 | 5. Save fdt to NOR flash: | |
217 | => erase fc060000 fc07ffff | |
218 | => cp.b 1800000 fc060000 10000 | |
219 | ... | |
220 | ||
221 | ||
222 | Falcon Mode was presented at the RMLL 2012. Slides are available at: | |
223 | ||
224 | http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf |