]>
Commit | Line | Data |
---|---|---|
4039feb5 PA |
1 | THE LINUX/x86 BOOT PROTOCOL |
2 | --------------------------- | |
1da177e4 | 3 | |
4039feb5 | 4 | On the x86 platform, the Linux kernel uses a rather complicated boot |
1da177e4 LT |
5 | convention. This has evolved partially due to historical aspects, as |
6 | well as the desire in the early days to have the kernel itself be a | |
7 | bootable image, the complicated PC memory model and due to changed | |
8 | expectations in the PC industry caused by the effective demise of | |
9 | real-mode DOS as a mainstream operating system. | |
10 | ||
4039feb5 | 11 | Currently, the following versions of the Linux/x86 boot protocol exist. |
1da177e4 LT |
12 | |
13 | Old kernels: zImage/Image support only. Some very early kernels | |
14 | may not even support a command line. | |
15 | ||
16 | Protocol 2.00: (Kernel 1.3.73) Added bzImage and initrd support, as | |
17 | well as a formalized way to communicate between the | |
18 | boot loader and the kernel. setup.S made relocatable, | |
19 | although the traditional setup area still assumed | |
20 | writable. | |
21 | ||
22 | Protocol 2.01: (Kernel 1.3.76) Added a heap overrun warning. | |
23 | ||
24 | Protocol 2.02: (Kernel 2.4.0-test3-pre3) New command line protocol. | |
25 | Lower the conventional memory ceiling. No overwrite | |
26 | of the traditional setup area, thus making booting | |
27 | safe for systems which use the EBDA from SMM or 32-bit | |
28 | BIOS entry points. zImage deprecated but still | |
29 | supported. | |
30 | ||
31 | Protocol 2.03: (Kernel 2.4.18-pre1) Explicitly makes the highest possible | |
32 | initrd address available to the bootloader. | |
33 | ||
f8eeaaf4 | 34 | Protocol 2.04: (Kernel 2.6.14) Extend the syssize field to four bytes. |
8f9aeca7 | 35 | |
be274eea VG |
36 | Protocol 2.05: (Kernel 2.6.20) Make protected mode kernel relocatable. |
37 | Introduce relocatable_kernel and kernel_alignment fields. | |
f8eeaaf4 | 38 | |
8f9aeca7 | 39 | Protocol 2.06: (Kernel 2.6.22) Added a field that contains the size of |
4c0587e6 | 40 | the boot command line. |
8f9aeca7 | 41 | |
4c0587e6 IC |
42 | Protocol 2.07: (Kernel 2.6.24) Added paravirtualised boot protocol. |
43 | Introduced hardware_subarch and hardware_subarch_data | |
44 | and KEEP_SEGMENTS flag in load_flags. | |
45 | ||
46 | Protocol 2.08: (Kernel 2.6.26) Added crc32 checksum and ELF format | |
2f6de3a1 | 47 | payload. Introduced payload_offset and payload_length |
4c0587e6 IC |
48 | fields to aid in locating the payload. |
49 | ||
50 | Protocol 2.09: (Kernel 2.6.26) Added a field of 64-bit physical | |
fb884381 | 51 | pointer to single linked list of struct setup_data. |
1da177e4 | 52 | |
5031296c | 53 | Protocol 2.10: (Kernel 2.6.31) Added a protocol for relaxed alignment |
d297366b | 54 | beyond the kernel_alignment added, new init_size and |
5031296c | 55 | pref_address fields. Added extended boot loader IDs. |
d297366b | 56 | |
9ca8f72a MF |
57 | Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover |
58 | protocol entry point. | |
59 | ||
1da177e4 LT |
60 | **** MEMORY LAYOUT |
61 | ||
62 | The traditional memory map for the kernel loader, used for Image or | |
63 | zImage kernels, typically looks like: | |
64 | ||
65 | | | | |
66 | 0A0000 +------------------------+ | |
67 | | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. | |
68 | 09A000 +------------------------+ | |
dec04cff PA |
69 | | Command line | |
70 | | Stack/heap | For use by the kernel real-mode code. | |
1da177e4 LT |
71 | 098000 +------------------------+ |
72 | | Kernel setup | The kernel real-mode code. | |
73 | 090200 +------------------------+ | |
74 | | Kernel boot sector | The kernel legacy boot sector. | |
75 | 090000 +------------------------+ | |
76 | | Protected-mode kernel | The bulk of the kernel image. | |
77 | 010000 +------------------------+ | |
78 | | Boot loader | <- Boot sector entry point 0000:7C00 | |
79 | 001000 +------------------------+ | |
80 | | Reserved for MBR/BIOS | | |
81 | 000800 +------------------------+ | |
82 | | Typically used by MBR | | |
83 | 000600 +------------------------+ | |
84 | | BIOS use only | | |
85 | 000000 +------------------------+ | |
86 | ||
87 | ||
88 | When using bzImage, the protected-mode kernel was relocated to | |
89 | 0x100000 ("high memory"), and the kernel real-mode block (boot sector, | |
90 | setup, and stack/heap) was made relocatable to any address between | |
dec04cff PA |
91 | 0x10000 and end of low memory. Unfortunately, in protocols 2.00 and |
92 | 2.01 the 0x90000+ memory range is still used internally by the kernel; | |
93 | the 2.02 protocol resolves that problem. | |
1da177e4 LT |
94 | |
95 | It is desirable to keep the "memory ceiling" -- the highest point in | |
96 | low memory touched by the boot loader -- as low as possible, since | |
97 | some newer BIOSes have begun to allocate some rather large amounts of | |
98 | memory, called the Extended BIOS Data Area, near the top of low | |
99 | memory. The boot loader should use the "INT 12h" BIOS call to verify | |
100 | how much low memory is available. | |
101 | ||
102 | Unfortunately, if INT 12h reports that the amount of memory is too | |
103 | low, there is usually nothing the boot loader can do but to report an | |
104 | error to the user. The boot loader should therefore be designed to | |
105 | take up as little space in low memory as it reasonably can. For | |
106 | zImage or old bzImage kernels, which need data written into the | |
107 | 0x90000 segment, the boot loader should make sure not to use memory | |
108 | above the 0x9A000 point; too many BIOSes will break above that point. | |
109 | ||
dec04cff PA |
110 | For a modern bzImage kernel with boot protocol version >= 2.02, a |
111 | memory layout like the following is suggested: | |
112 | ||
113 | ~ ~ | |
114 | | Protected-mode kernel | | |
115 | 100000 +------------------------+ | |
116 | | I/O memory hole | | |
117 | 0A0000 +------------------------+ | |
118 | | Reserved for BIOS | Leave as much as possible unused | |
119 | ~ ~ | |
120 | | Command line | (Can also be below the X+10000 mark) | |
121 | X+10000 +------------------------+ | |
122 | | Stack/heap | For use by the kernel real-mode code. | |
123 | X+08000 +------------------------+ | |
124 | | Kernel setup | The kernel real-mode code. | |
125 | | Kernel boot sector | The kernel legacy boot sector. | |
126 | X +------------------------+ | |
127 | | Boot loader | <- Boot sector entry point 0000:7C00 | |
128 | 001000 +------------------------+ | |
129 | | Reserved for MBR/BIOS | | |
130 | 000800 +------------------------+ | |
131 | | Typically used by MBR | | |
132 | 000600 +------------------------+ | |
133 | | BIOS use only | | |
134 | 000000 +------------------------+ | |
135 | ||
136 | ... where the address X is as low as the design of the boot loader | |
137 | permits. | |
138 | ||
1da177e4 LT |
139 | |
140 | **** THE REAL-MODE KERNEL HEADER | |
141 | ||
142 | In the following text, and anywhere in the kernel boot sequence, "a | |
143 | sector" refers to 512 bytes. It is independent of the actual sector | |
144 | size of the underlying medium. | |
145 | ||
146 | The first step in loading a Linux kernel should be to load the | |
147 | real-mode code (boot sector and setup code) and then examine the | |
148 | following header at offset 0x01f1. The real-mode code can total up to | |
149 | 32K, although the boot loader may choose to load only the first two | |
150 | sectors (1K) and then examine the bootup sector size. | |
151 | ||
152 | The header looks like: | |
153 | ||
154 | Offset Proto Name Meaning | |
155 | /Size | |
156 | ||
f8eeaaf4 | 157 | 01F1/1 ALL(1 setup_sects The size of the setup in sectors |
1da177e4 | 158 | 01F2/2 ALL root_flags If set, the root is mounted readonly |
f8eeaaf4 | 159 | 01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras |
1da177e4 LT |
160 | 01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only |
161 | 01FA/2 ALL vid_mode Video mode control | |
162 | 01FC/2 ALL root_dev Default root device number | |
163 | 01FE/2 ALL boot_flag 0xAA55 magic number | |
164 | 0200/2 2.00+ jump Jump instruction | |
165 | 0202/4 2.00+ header Magic signature "HdrS" | |
166 | 0206/2 2.00+ version Boot protocol version supported | |
167 | 0208/4 2.00+ realmode_swtch Boot loader hook (see below) | |
e56d0cfe | 168 | 020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete) |
1da177e4 LT |
169 | 020E/2 2.00+ kernel_version Pointer to kernel version string |
170 | 0210/1 2.00+ type_of_loader Boot loader identifier | |
171 | 0211/1 2.00+ loadflags Boot protocol option flags | |
172 | 0212/2 2.00+ setup_move_size Move to high memory size (used with hooks) | |
173 | 0214/4 2.00+ code32_start Boot loader hook (see below) | |
174 | 0218/4 2.00+ ramdisk_image initrd load address (set by boot loader) | |
175 | 021C/4 2.00+ ramdisk_size initrd size (set by boot loader) | |
176 | 0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only | |
177 | 0224/2 2.01+ heap_end_ptr Free memory after setup end | |
5031296c PA |
178 | 0226/1 2.02+(3 ext_loader_ver Extended boot loader version |
179 | 0227/1 2.02+(3 ext_loader_type Extended boot loader ID | |
1da177e4 | 180 | 0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line |
e56d0cfe | 181 | 022C/4 2.03+ ramdisk_max Highest legal initrd address |
d263b213 VG |
182 | 0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel |
183 | 0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not | |
d297366b | 184 | 0235/1 2.10+ min_alignment Minimum alignment, as a power of two |
e56d0cfe | 185 | 0236/2 N/A pad3 Unused |
8f9aeca7 | 186 | 0238/4 2.06+ cmdline_size Maximum size of the kernel command line |
e5371ac5 RR |
187 | 023C/4 2.07+ hardware_subarch Hardware subarchitecture |
188 | 0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data | |
87253d1b IC |
189 | 0248/4 2.08+ payload_offset Offset of kernel payload |
190 | 024C/4 2.08+ payload_length Length of kernel payload | |
fb884381 HY |
191 | 0250/8 2.09+ setup_data 64-bit physical pointer to linked list |
192 | of struct setup_data | |
d297366b PA |
193 | 0258/8 2.10+ pref_address Preferred loading address |
194 | 0260/4 2.10+ init_size Linear memory required during initialization | |
9ca8f72a | 195 | 0264/4 2.11+ handover_offset Offset of handover entry point |
1da177e4 | 196 | |
f8eeaaf4 PA |
197 | (1) For backwards compatibility, if the setup_sects field contains 0, the |
198 | real value is 4. | |
199 | ||
200 | (2) For boot protocol prior to 2.04, the upper two bytes of the syssize | |
201 | field are unusable, which means the size of a bzImage kernel | |
202 | cannot be determined. | |
1da177e4 | 203 | |
5031296c PA |
204 | (3) Ignored, but safe to set, for boot protocols 2.02-2.09. |
205 | ||
1da177e4 LT |
206 | If the "HdrS" (0x53726448) magic number is not found at offset 0x202, |
207 | the boot protocol version is "old". Loading an old kernel, the | |
208 | following parameters should be assumed: | |
209 | ||
210 | Image type = zImage | |
211 | initrd not supported | |
212 | Real-mode kernel must be located at 0x90000. | |
213 | ||
214 | Otherwise, the "version" field contains the protocol version, | |
215 | e.g. protocol version 2.01 will contain 0x0201 in this field. When | |
216 | setting fields in the header, you must make sure only to set fields | |
217 | supported by the protocol version in use. | |
218 | ||
dec04cff PA |
219 | |
220 | **** DETAILS OF HEADER FIELDS | |
221 | ||
222 | For each field, some are information from the kernel to the bootloader | |
223 | ("read"), some are expected to be filled out by the bootloader | |
224 | ("write"), and some are expected to be read and modified by the | |
225 | bootloader ("modify"). | |
226 | ||
227 | All general purpose boot loaders should write the fields marked | |
228 | (obligatory). Boot loaders who want to load the kernel at a | |
229 | nonstandard address should fill in the fields marked (reloc); other | |
230 | boot loaders can ignore those fields. | |
231 | ||
db2668fd PA |
232 | The byte order of all fields is littleendian (this is x86, after all.) |
233 | ||
e5371ac5 | 234 | Field name: setup_sects |
dec04cff PA |
235 | Type: read |
236 | Offset/size: 0x1f1/1 | |
237 | Protocol: ALL | |
238 | ||
239 | The size of the setup code in 512-byte sectors. If this field is | |
240 | 0, the real value is 4. The real-mode code consists of the boot | |
241 | sector (always one 512-byte sector) plus the setup code. | |
242 | ||
243 | Field name: root_flags | |
244 | Type: modify (optional) | |
245 | Offset/size: 0x1f2/2 | |
246 | Protocol: ALL | |
247 | ||
248 | If this field is nonzero, the root defaults to readonly. The use of | |
249 | this field is deprecated; use the "ro" or "rw" options on the | |
250 | command line instead. | |
251 | ||
252 | Field name: syssize | |
253 | Type: read | |
254 | Offset/size: 0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL) | |
255 | Protocol: 2.04+ | |
256 | ||
257 | The size of the protected-mode code in units of 16-byte paragraphs. | |
258 | For protocol versions older than 2.04 this field is only two bytes | |
259 | wide, and therefore cannot be trusted for the size of a kernel if | |
260 | the LOAD_HIGH flag is set. | |
261 | ||
262 | Field name: ram_size | |
263 | Type: kernel internal | |
264 | Offset/size: 0x1f8/2 | |
265 | Protocol: ALL | |
266 | ||
267 | This field is obsolete. | |
268 | ||
269 | Field name: vid_mode | |
270 | Type: modify (obligatory) | |
271 | Offset/size: 0x1fa/2 | |
272 | ||
273 | Please see the section on SPECIAL COMMAND LINE OPTIONS. | |
274 | ||
275 | Field name: root_dev | |
276 | Type: modify (optional) | |
277 | Offset/size: 0x1fc/2 | |
278 | Protocol: ALL | |
279 | ||
280 | The default root device device number. The use of this field is | |
281 | deprecated, use the "root=" option on the command line instead. | |
282 | ||
283 | Field name: boot_flag | |
284 | Type: read | |
285 | Offset/size: 0x1fe/2 | |
286 | Protocol: ALL | |
287 | ||
288 | Contains 0xAA55. This is the closest thing old Linux kernels have | |
289 | to a magic number. | |
290 | ||
291 | Field name: jump | |
292 | Type: read | |
293 | Offset/size: 0x200/2 | |
294 | Protocol: 2.00+ | |
295 | ||
296 | Contains an x86 jump instruction, 0xEB followed by a signed offset | |
297 | relative to byte 0x202. This can be used to determine the size of | |
298 | the header. | |
299 | ||
300 | Field name: header | |
301 | Type: read | |
302 | Offset/size: 0x202/4 | |
303 | Protocol: 2.00+ | |
304 | ||
305 | Contains the magic number "HdrS" (0x53726448). | |
306 | ||
307 | Field name: version | |
308 | Type: read | |
309 | Offset/size: 0x206/2 | |
310 | Protocol: 2.00+ | |
311 | ||
db2668fd PA |
312 | Contains the boot protocol version, in (major << 8)+minor format, |
313 | e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version | |
314 | 10.17. | |
dec04cff | 315 | |
e56d0cfe | 316 | Field name: realmode_swtch |
dec04cff PA |
317 | Type: modify (optional) |
318 | Offset/size: 0x208/4 | |
319 | Protocol: 2.00+ | |
320 | ||
db2668fd | 321 | Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.) |
dec04cff | 322 | |
e56d0cfe | 323 | Field name: start_sys_seg |
dec04cff | 324 | Type: read |
a021e512 | 325 | Offset/size: 0x20c/2 |
dec04cff PA |
326 | Protocol: 2.00+ |
327 | ||
328 | The load low segment (0x1000). Obsolete. | |
329 | ||
330 | Field name: kernel_version | |
331 | Type: read | |
332 | Offset/size: 0x20e/2 | |
333 | Protocol: 2.00+ | |
334 | ||
335 | If set to a nonzero value, contains a pointer to a NUL-terminated | |
336 | human-readable kernel version number string, less 0x200. This can | |
337 | be used to display the kernel version to the user. This value | |
db2668fd PA |
338 | should be less than (0x200*setup_sects). |
339 | ||
340 | For example, if this value is set to 0x1c00, the kernel version | |
341 | number string can be found at offset 0x1e00 in the kernel file. | |
342 | This is a valid value if and only if the "setup_sects" field | |
343 | contains the value 15 or higher, as: | |
344 | ||
345 | 0x1c00 < 15*0x200 (= 0x1e00) but | |
346 | 0x1c00 >= 14*0x200 (= 0x1c00) | |
347 | ||
348 | 0x1c00 >> 9 = 14, so the minimum value for setup_secs is 15. | |
dec04cff PA |
349 | |
350 | Field name: type_of_loader | |
351 | Type: write (obligatory) | |
352 | Offset/size: 0x210/1 | |
353 | Protocol: 2.00+ | |
354 | ||
355 | If your boot loader has an assigned id (see table below), enter | |
356 | 0xTV here, where T is an identifier for the boot loader and V is | |
357 | a version number. Otherwise, enter 0xFF here. | |
358 | ||
5031296c PA |
359 | For boot loader IDs above T = 0xD, write T = 0xE to this field and |
360 | write the extended ID minus 0x10 to the ext_loader_type field. | |
361 | Similarly, the ext_loader_ver field can be used to provide more than | |
362 | four bits for the bootloader version. | |
363 | ||
364 | For example, for T = 0x15, V = 0x234, write: | |
365 | ||
366 | type_of_loader <- 0xE4 | |
367 | ext_loader_type <- 0x05 | |
368 | ext_loader_ver <- 0x23 | |
369 | ||
c5e5c42a PA |
370 | Assigned boot loader ids (hexadecimal): |
371 | ||
de372ecd | 372 | 0 LILO (0x00 reserved for pre-2.00 bootloader) |
1da177e4 | 373 | 1 Loadlin |
de372ecd | 374 | 2 bootsect-loader (0x20, all other values reserved) |
5031296c PA |
375 | 3 Syslinux |
376 | 4 Etherboot/gPXE | |
1da177e4 | 377 | 5 ELILO |
9ee670fd | 378 | 7 GRUB |
5031296c | 379 | 8 U-Boot |
354332ee | 380 | 9 Xen |
c229ec5d | 381 | A Gujin |
dec04cff | 382 | B Qemu |
5031296c | 383 | C Arcturus Networks uCbootloader |
4bfe24ac | 384 | D kexec-tools |
5031296c PA |
385 | E Extended (see ext_loader_type) |
386 | F Special (0xFF = undefined) | |
c5e5c42a PA |
387 | 10 Reserved |
388 | 11 Minimal Linux Bootloader <http://sebastian-plotz.blogspot.de> | |
1da177e4 | 389 | |
dec04cff PA |
390 | Please contact <hpa@zytor.com> if you need a bootloader ID |
391 | value assigned. | |
392 | ||
393 | Field name: loadflags | |
394 | Type: modify (obligatory) | |
395 | Offset/size: 0x211/1 | |
396 | Protocol: 2.00+ | |
397 | ||
398 | This field is a bitmask. | |
399 | ||
400 | Bit 0 (read): LOADED_HIGH | |
401 | - If 0, the protected-mode code is loaded at 0x10000. | |
402 | - If 1, the protected-mode code is loaded at 0x100000. | |
403 | ||
4039feb5 PA |
404 | Bit 5 (write): QUIET_FLAG |
405 | - If 0, print early messages. | |
406 | - If 1, suppress early messages. | |
407 | This requests to the kernel (decompressor and early | |
408 | kernel) to not write early messages that require | |
409 | accessing the display hardware directly. | |
410 | ||
e5371ac5 RR |
411 | Bit 6 (write): KEEP_SEGMENTS |
412 | Protocol: 2.07+ | |
4039feb5 PA |
413 | - If 0, reload the segment registers in the 32bit entry point. |
414 | - If 1, do not reload the segment registers in the 32bit entry point. | |
e5371ac5 RR |
415 | Assume that %cs %ds %ss %es are all set to flat segments with |
416 | a base of 0 (or the equivalent for their environment). | |
417 | ||
dec04cff PA |
418 | Bit 7 (write): CAN_USE_HEAP |
419 | Set this bit to 1 to indicate that the value entered in the | |
420 | heap_end_ptr is valid. If this field is clear, some setup code | |
421 | functionality will be disabled. | |
422 | ||
423 | Field name: setup_move_size | |
424 | Type: modify (obligatory) | |
425 | Offset/size: 0x212/2 | |
426 | Protocol: 2.00-2.01 | |
427 | ||
428 | When using protocol 2.00 or 2.01, if the real mode kernel is not | |
429 | loaded at 0x90000, it gets moved there later in the loading | |
430 | sequence. Fill in this field if you want additional data (such as | |
431 | the kernel command line) moved in addition to the real-mode kernel | |
432 | itself. | |
433 | ||
434 | The unit is bytes starting with the beginning of the boot sector. | |
435 | ||
436 | This field is can be ignored when the protocol is 2.02 or higher, or | |
437 | if the real-mode code is loaded at 0x90000. | |
438 | ||
439 | Field name: code32_start | |
440 | Type: modify (optional, reloc) | |
441 | Offset/size: 0x214/4 | |
442 | Protocol: 2.00+ | |
443 | ||
444 | The address to jump to in protected mode. This defaults to the load | |
445 | address of the kernel, and can be used by the boot loader to | |
446 | determine the proper load address. | |
447 | ||
448 | This field can be modified for two purposes: | |
449 | ||
db2668fd | 450 | 1. as a boot loader hook (see ADVANCED BOOT LOADER HOOKS below.) |
dec04cff PA |
451 | |
452 | 2. if a bootloader which does not install a hook loads a | |
453 | relocatable kernel at a nonstandard address it will have to modify | |
454 | this field to point to the load address. | |
455 | ||
456 | Field name: ramdisk_image | |
457 | Type: write (obligatory) | |
458 | Offset/size: 0x218/4 | |
459 | Protocol: 2.00+ | |
460 | ||
461 | The 32-bit linear address of the initial ramdisk or ramfs. Leave at | |
462 | zero if there is no initial ramdisk/ramfs. | |
463 | ||
464 | Field name: ramdisk_size | |
465 | Type: write (obligatory) | |
466 | Offset/size: 0x21c/4 | |
467 | Protocol: 2.00+ | |
468 | ||
469 | Size of the initial ramdisk or ramfs. Leave at zero if there is no | |
470 | initial ramdisk/ramfs. | |
471 | ||
472 | Field name: bootsect_kludge | |
473 | Type: kernel internal | |
474 | Offset/size: 0x220/4 | |
475 | Protocol: 2.00+ | |
476 | ||
477 | This field is obsolete. | |
478 | ||
479 | Field name: heap_end_ptr | |
480 | Type: write (obligatory) | |
481 | Offset/size: 0x224/2 | |
482 | Protocol: 2.01+ | |
483 | ||
484 | Set this field to the offset (from the beginning of the real-mode | |
485 | code) of the end of the setup stack/heap, minus 0x0200. | |
486 | ||
5031296c PA |
487 | Field name: ext_loader_ver |
488 | Type: write (optional) | |
489 | Offset/size: 0x226/1 | |
490 | Protocol: 2.02+ | |
491 | ||
492 | This field is used as an extension of the version number in the | |
493 | type_of_loader field. The total version number is considered to be | |
494 | (type_of_loader & 0x0f) + (ext_loader_ver << 4). | |
495 | ||
496 | The use of this field is boot loader specific. If not written, it | |
497 | is zero. | |
498 | ||
499 | Kernels prior to 2.6.31 did not recognize this field, but it is safe | |
500 | to write for protocol version 2.02 or higher. | |
501 | ||
502 | Field name: ext_loader_type | |
503 | Type: write (obligatory if (type_of_loader & 0xf0) == 0xe0) | |
504 | Offset/size: 0x227/1 | |
505 | Protocol: 2.02+ | |
506 | ||
507 | This field is used as an extension of the type number in | |
508 | type_of_loader field. If the type in type_of_loader is 0xE, then | |
509 | the actual type is (ext_loader_type + 0x10). | |
510 | ||
511 | This field is ignored if the type in type_of_loader is not 0xE. | |
512 | ||
513 | Kernels prior to 2.6.31 did not recognize this field, but it is safe | |
514 | to write for protocol version 2.02 or higher. | |
515 | ||
dec04cff PA |
516 | Field name: cmd_line_ptr |
517 | Type: write (obligatory) | |
518 | Offset/size: 0x228/4 | |
519 | Protocol: 2.02+ | |
520 | ||
521 | Set this field to the linear address of the kernel command line. | |
522 | The kernel command line can be located anywhere between the end of | |
523 | the setup heap and 0xA0000; it does not have to be located in the | |
524 | same 64K segment as the real-mode code itself. | |
525 | ||
526 | Fill in this field even if your boot loader does not support a | |
527 | command line, in which case you can point this to an empty string | |
528 | (or better yet, to the string "auto".) If this field is left at | |
529 | zero, the kernel will assume that your boot loader does not support | |
530 | the 2.02+ protocol. | |
531 | ||
e56d0cfe | 532 | Field name: ramdisk_max |
dec04cff PA |
533 | Type: read |
534 | Offset/size: 0x22c/4 | |
535 | Protocol: 2.03+ | |
536 | ||
537 | The maximum address that may be occupied by the initial | |
538 | ramdisk/ramfs contents. For boot protocols 2.02 or earlier, this | |
539 | field is not present, and the maximum address is 0x37FFFFFF. (This | |
540 | address is defined as the address of the highest safe byte, so if | |
541 | your ramdisk is exactly 131072 bytes long and this field is | |
542 | 0x37FFFFFF, you can start your ramdisk at 0x37FE0000.) | |
543 | ||
544 | Field name: kernel_alignment | |
d297366b | 545 | Type: read/modify (reloc) |
dec04cff | 546 | Offset/size: 0x230/4 |
d297366b PA |
547 | Protocol: 2.05+ (read), 2.10+ (modify) |
548 | ||
549 | Alignment unit required by the kernel (if relocatable_kernel is | |
550 | true.) A relocatable kernel that is loaded at an alignment | |
551 | incompatible with the value in this field will be realigned during | |
552 | kernel initialization. | |
dec04cff | 553 | |
d297366b PA |
554 | Starting with protocol version 2.10, this reflects the kernel |
555 | alignment preferred for optimal performance; it is possible for the | |
556 | loader to modify this field to permit a lesser alignment. See the | |
557 | min_alignment and pref_address field below. | |
dec04cff PA |
558 | |
559 | Field name: relocatable_kernel | |
560 | Type: read (reloc) | |
561 | Offset/size: 0x234/1 | |
562 | Protocol: 2.05+ | |
563 | ||
564 | If this field is nonzero, the protected-mode part of the kernel can | |
565 | be loaded at any address that satisfies the kernel_alignment field. | |
566 | After loading, the boot loader must set the code32_start field to | |
567 | point to the loaded code, or to a boot loader hook. | |
568 | ||
d297366b PA |
569 | Field name: min_alignment |
570 | Type: read (reloc) | |
571 | Offset/size: 0x235/1 | |
572 | Protocol: 2.10+ | |
573 | ||
574 | This field, if nonzero, indicates as a power of two the minimum | |
575 | alignment required, as opposed to preferred, by the kernel to boot. | |
576 | If a boot loader makes use of this field, it should update the | |
577 | kernel_alignment field with the alignment unit desired; typically: | |
578 | ||
579 | kernel_alignment = 1 << min_alignment | |
580 | ||
581 | There may be a considerable performance cost with an excessively | |
582 | misaligned kernel. Therefore, a loader should typically try each | |
583 | power-of-two alignment from kernel_alignment down to this alignment. | |
584 | ||
dec04cff PA |
585 | Field name: cmdline_size |
586 | Type: read | |
587 | Offset/size: 0x238/4 | |
588 | Protocol: 2.06+ | |
589 | ||
590 | The maximum size of the command line without the terminating | |
591 | zero. This means that the command line can contain at most | |
592 | cmdline_size characters. With protocol version 2.05 and earlier, the | |
593 | maximum size was 255. | |
8f9aeca7 | 594 | |
e5371ac5 | 595 | Field name: hardware_subarch |
4039feb5 | 596 | Type: write (optional, defaults to x86/PC) |
e5371ac5 RR |
597 | Offset/size: 0x23c/4 |
598 | Protocol: 2.07+ | |
599 | ||
600 | In a paravirtualized environment the hardware low level architectural | |
601 | pieces such as interrupt handling, page table handling, and | |
602 | accessing process control registers needs to be done differently. | |
603 | ||
604 | This field allows the bootloader to inform the kernel we are in one | |
605 | one of those environments. | |
606 | ||
607 | 0x00000000 The default x86/PC environment | |
608 | 0x00000001 lguest | |
609 | 0x00000002 Xen | |
162bc7ab | 610 | 0x00000003 Moorestown MID |
c751e17b | 611 | 0x00000004 CE4100 TV Platform |
e5371ac5 RR |
612 | |
613 | Field name: hardware_subarch_data | |
4039feb5 | 614 | Type: write (subarch-dependent) |
e5371ac5 RR |
615 | Offset/size: 0x240/8 |
616 | Protocol: 2.07+ | |
617 | ||
618 | A pointer to data that is specific to hardware subarch | |
4039feb5 PA |
619 | This field is currently unused for the default x86/PC environment, |
620 | do not modify. | |
e5371ac5 | 621 | |
87253d1b | 622 | Field name: payload_offset |
099e1377 IC |
623 | Type: read |
624 | Offset/size: 0x248/4 | |
625 | Protocol: 2.08+ | |
626 | ||
e1286f2c PK |
627 | If non-zero then this field contains the offset from the beginning |
628 | of the protected-mode code to the payload. | |
87253d1b IC |
629 | |
630 | The payload may be compressed. The format of both the compressed and | |
631 | uncompressed data should be determined using the standard magic | |
ee287587 | 632 | numbers. The currently supported compression formats are gzip |
30314804 LC |
633 | (magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A), LZMA |
634 | (magic number 5D 00), and XZ (magic number FD 37). The uncompressed | |
635 | payload is currently always ELF (magic number 7F 45 4C 46). | |
099e1377 | 636 | |
87253d1b | 637 | Field name: payload_length |
099e1377 IC |
638 | Type: read |
639 | Offset/size: 0x24c/4 | |
640 | Protocol: 2.08+ | |
641 | ||
87253d1b | 642 | The length of the payload. |
1da177e4 | 643 | |
4039feb5 PA |
644 | Field name: setup_data |
645 | Type: write (special) | |
646 | Offset/size: 0x250/8 | |
647 | Protocol: 2.09+ | |
648 | ||
649 | The 64-bit physical pointer to NULL terminated single linked list of | |
650 | struct setup_data. This is used to define a more extensible boot | |
651 | parameters passing mechanism. The definition of struct setup_data is | |
652 | as follow: | |
653 | ||
654 | struct setup_data { | |
655 | u64 next; | |
656 | u32 type; | |
657 | u32 len; | |
658 | u8 data[0]; | |
659 | }; | |
660 | ||
661 | Where, the next is a 64-bit physical pointer to the next node of | |
662 | linked list, the next field of the last node is 0; the type is used | |
663 | to identify the contents of data; the len is the length of data | |
664 | field; the data holds the real payload. | |
665 | ||
666 | This list may be modified at a number of points during the bootup | |
667 | process. Therefore, when modifying this list one should always make | |
668 | sure to consider the case where the linked list already contains | |
669 | entries. | |
670 | ||
d297366b PA |
671 | Field name: pref_address |
672 | Type: read (reloc) | |
673 | Offset/size: 0x258/8 | |
674 | Protocol: 2.10+ | |
675 | ||
676 | This field, if nonzero, represents a preferred load address for the | |
677 | kernel. A relocating bootloader should attempt to load at this | |
678 | address if possible. | |
679 | ||
680 | A non-relocatable kernel will unconditionally move itself and to run | |
681 | at this address. | |
682 | ||
683 | Field name: init_size | |
684 | Type: read | |
11e48fee | 685 | Offset/size: 0x260/4 |
d297366b PA |
686 | |
687 | This field indicates the amount of linear contiguous memory starting | |
688 | at the kernel runtime start address that the kernel needs before it | |
689 | is capable of examining its memory map. This is not the same thing | |
690 | as the total amount of memory the kernel needs to boot, but it can | |
691 | be used by a relocating boot loader to help select a safe load | |
692 | address for the kernel. | |
693 | ||
694 | The kernel runtime start address is determined by the following algorithm: | |
695 | ||
696 | if (relocatable_kernel) | |
697 | runtime_start = align_up(load_address, kernel_alignment) | |
698 | else | |
699 | runtime_start = pref_address | |
700 | ||
9ca8f72a MF |
701 | Field name: handover_offset |
702 | Type: read | |
703 | Offset/size: 0x264/4 | |
704 | ||
705 | This field is the offset from the beginning of the kernel image to | |
706 | the EFI handover protocol entry point. Boot loaders using the EFI | |
707 | handover protocol to boot the kernel should jump to this offset. | |
708 | ||
709 | See EFI HANDOVER PROTOCOL below for more details. | |
710 | ||
4039feb5 | 711 | |
7d6e737c IC |
712 | **** THE IMAGE CHECKSUM |
713 | ||
714 | From boot protocol version 2.08 onwards the CRC-32 is calculated over | |
715 | the entire file using the characteristic polynomial 0x04C11DB7 and an | |
716 | initial remainder of 0xffffffff. The checksum is appended to the | |
717 | file; therefore the CRC of the file up to the limit specified in the | |
718 | syssize field of the header is always 0. | |
719 | ||
4039feb5 | 720 | |
1da177e4 LT |
721 | **** THE KERNEL COMMAND LINE |
722 | ||
723 | The kernel command line has become an important way for the boot | |
724 | loader to communicate with the kernel. Some of its options are also | |
725 | relevant to the boot loader itself, see "special command line options" | |
726 | below. | |
727 | ||
8f9aeca7 BW |
728 | The kernel command line is a null-terminated string. The maximum |
729 | length can be retrieved from the field cmdline_size. Before protocol | |
730 | version 2.06, the maximum was 255 characters. A string that is too | |
731 | long will be automatically truncated by the kernel. | |
1da177e4 LT |
732 | |
733 | If the boot protocol version is 2.02 or later, the address of the | |
734 | kernel command line is given by the header field cmd_line_ptr (see | |
f8eeaaf4 PA |
735 | above.) This address can be anywhere between the end of the setup |
736 | heap and 0xA0000. | |
1da177e4 LT |
737 | |
738 | If the protocol version is *not* 2.02 or higher, the kernel | |
739 | command line is entered using the following protocol: | |
740 | ||
741 | At offset 0x0020 (word), "cmd_line_magic", enter the magic | |
742 | number 0xA33F. | |
743 | ||
744 | At offset 0x0022 (word), "cmd_line_offset", enter the offset | |
745 | of the kernel command line (relative to the start of the | |
746 | real-mode kernel). | |
747 | ||
748 | The kernel command line *must* be within the memory region | |
749 | covered by setup_move_size, so you may need to adjust this | |
750 | field. | |
751 | ||
752 | ||
de372ecd PA |
753 | **** MEMORY LAYOUT OF THE REAL-MODE CODE |
754 | ||
755 | The real-mode code requires a stack/heap to be set up, as well as | |
756 | memory allocated for the kernel command line. This needs to be done | |
757 | in the real-mode accessible memory in bottom megabyte. | |
758 | ||
759 | It should be noted that modern machines often have a sizable Extended | |
760 | BIOS Data Area (EBDA). As a result, it is advisable to use as little | |
761 | of the low megabyte as possible. | |
762 | ||
763 | Unfortunately, under the following circumstances the 0x90000 memory | |
764 | segment has to be used: | |
765 | ||
766 | - When loading a zImage kernel ((loadflags & 0x01) == 0). | |
767 | - When loading a 2.01 or earlier boot protocol kernel. | |
768 | ||
769 | -> For the 2.00 and 2.01 boot protocols, the real-mode code | |
770 | can be loaded at another address, but it is internally | |
771 | relocated to 0x90000. For the "old" protocol, the | |
772 | real-mode code must be loaded at 0x90000. | |
773 | ||
774 | When loading at 0x90000, avoid using memory above 0x9a000. | |
775 | ||
776 | For boot protocol 2.02 or higher, the command line does not have to be | |
777 | located in the same 64K segment as the real-mode setup code; it is | |
778 | thus permitted to give the stack/heap the full 64K segment and locate | |
779 | the command line above it. | |
780 | ||
781 | The kernel command line should not be located below the real-mode | |
782 | code, nor should it be located in high memory. | |
783 | ||
784 | ||
1da177e4 LT |
785 | **** SAMPLE BOOT CONFIGURATION |
786 | ||
787 | As a sample configuration, assume the following layout of the real | |
de372ecd PA |
788 | mode segment: |
789 | ||
790 | When loading below 0x90000, use the entire segment: | |
791 | ||
792 | 0x0000-0x7fff Real mode kernel | |
793 | 0x8000-0xdfff Stack and heap | |
794 | 0xe000-0xffff Kernel command line | |
1da177e4 | 795 | |
de372ecd PA |
796 | When loading at 0x90000 OR the protocol version is 2.01 or earlier: |
797 | ||
798 | 0x0000-0x7fff Real mode kernel | |
799 | 0x8000-0x97ff Stack and heap | |
800 | 0x9800-0x9fff Kernel command line | |
1da177e4 LT |
801 | |
802 | Such a boot loader should enter the following fields in the header: | |
803 | ||
804 | unsigned long base_ptr; /* base address for real-mode segment */ | |
805 | ||
806 | if ( setup_sects == 0 ) { | |
807 | setup_sects = 4; | |
808 | } | |
809 | ||
810 | if ( protocol >= 0x0200 ) { | |
811 | type_of_loader = <type code>; | |
812 | if ( loading_initrd ) { | |
813 | ramdisk_image = <initrd_address>; | |
814 | ramdisk_size = <initrd_size>; | |
815 | } | |
de372ecd PA |
816 | |
817 | if ( protocol >= 0x0202 && loadflags & 0x01 ) | |
818 | heap_end = 0xe000; | |
819 | else | |
820 | heap_end = 0x9800; | |
821 | ||
1da177e4 | 822 | if ( protocol >= 0x0201 ) { |
de372ecd | 823 | heap_end_ptr = heap_end - 0x200; |
1da177e4 LT |
824 | loadflags |= 0x80; /* CAN_USE_HEAP */ |
825 | } | |
de372ecd | 826 | |
1da177e4 | 827 | if ( protocol >= 0x0202 ) { |
de372ecd PA |
828 | cmd_line_ptr = base_ptr + heap_end; |
829 | strcpy(cmd_line_ptr, cmdline); | |
1da177e4 LT |
830 | } else { |
831 | cmd_line_magic = 0xA33F; | |
de372ecd PA |
832 | cmd_line_offset = heap_end; |
833 | setup_move_size = heap_end + strlen(cmdline)+1; | |
834 | strcpy(base_ptr+cmd_line_offset, cmdline); | |
1da177e4 LT |
835 | } |
836 | } else { | |
837 | /* Very old kernel */ | |
838 | ||
de372ecd PA |
839 | heap_end = 0x9800; |
840 | ||
1da177e4 | 841 | cmd_line_magic = 0xA33F; |
de372ecd | 842 | cmd_line_offset = heap_end; |
1da177e4 LT |
843 | |
844 | /* A very old kernel MUST have its real-mode code | |
845 | loaded at 0x90000 */ | |
846 | ||
847 | if ( base_ptr != 0x90000 ) { | |
848 | /* Copy the real-mode kernel */ | |
849 | memcpy(0x90000, base_ptr, (setup_sects+1)*512); | |
1da177e4 LT |
850 | base_ptr = 0x90000; /* Relocated */ |
851 | } | |
852 | ||
de372ecd PA |
853 | strcpy(0x90000+cmd_line_offset, cmdline); |
854 | ||
1da177e4 LT |
855 | /* It is recommended to clear memory up to the 32K mark */ |
856 | memset(0x90000 + (setup_sects+1)*512, 0, | |
857 | (64-(setup_sects+1))*512); | |
858 | } | |
859 | ||
860 | ||
861 | **** LOADING THE REST OF THE KERNEL | |
862 | ||
f8eeaaf4 PA |
863 | The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 |
864 | in the kernel file (again, if setup_sects == 0 the real value is 4.) | |
865 | It should be loaded at address 0x10000 for Image/zImage kernels and | |
1da177e4 LT |
866 | 0x100000 for bzImage kernels. |
867 | ||
868 | The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 | |
869 | bit (LOAD_HIGH) in the loadflags field is set: | |
870 | ||
871 | is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01); | |
872 | load_address = is_bzImage ? 0x100000 : 0x10000; | |
873 | ||
874 | Note that Image/zImage kernels can be up to 512K in size, and thus use | |
875 | the entire 0x10000-0x90000 range of memory. This means it is pretty | |
876 | much a requirement for these kernels to load the real-mode part at | |
877 | 0x90000. bzImage kernels allow much more flexibility. | |
878 | ||
879 | ||
880 | **** SPECIAL COMMAND LINE OPTIONS | |
881 | ||
882 | If the command line provided by the boot loader is entered by the | |
883 | user, the user may expect the following command line options to work. | |
884 | They should normally not be deleted from the kernel command line even | |
885 | though not all of them are actually meaningful to the kernel. Boot | |
886 | loader authors who need additional command line options for the boot | |
887 | loader itself should get them registered in | |
888 | Documentation/kernel-parameters.txt to make sure they will not | |
889 | conflict with actual kernel options now or in the future. | |
890 | ||
891 | vga=<mode> | |
892 | <mode> here is either an integer (in C notation, either | |
893 | decimal, octal, or hexadecimal) or one of the strings | |
894 | "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask" | |
895 | (meaning 0xFFFD). This value should be entered into the | |
896 | vid_mode field, as it is used by the kernel before the command | |
897 | line is parsed. | |
898 | ||
899 | mem=<size> | |
de372ecd PA |
900 | <size> is an integer in C notation optionally followed by |
901 | (case insensitive) K, M, G, T, P or E (meaning << 10, << 20, | |
902 | << 30, << 40, << 50 or << 60). This specifies the end of | |
903 | memory to the kernel. This affects the possible placement of | |
904 | an initrd, since an initrd should be placed near end of | |
1da177e4 LT |
905 | memory. Note that this is an option to *both* the kernel and |
906 | the bootloader! | |
907 | ||
908 | initrd=<file> | |
909 | An initrd should be loaded. The meaning of <file> is | |
910 | obviously bootloader-dependent, and some boot loaders | |
911 | (e.g. LILO) do not have such a command. | |
912 | ||
913 | In addition, some boot loaders add the following options to the | |
914 | user-specified command line: | |
915 | ||
916 | BOOT_IMAGE=<file> | |
917 | The boot image which was loaded. Again, the meaning of <file> | |
918 | is obviously bootloader-dependent. | |
919 | ||
920 | auto | |
921 | The kernel was booted without explicit user intervention. | |
922 | ||
923 | If these options are added by the boot loader, it is highly | |
924 | recommended that they are located *first*, before the user-specified | |
925 | or configuration-specified command line. Otherwise, "init=/bin/sh" | |
926 | gets confused by the "auto" option. | |
927 | ||
928 | ||
929 | **** RUNNING THE KERNEL | |
930 | ||
931 | The kernel is started by jumping to the kernel entry point, which is | |
932 | located at *segment* offset 0x20 from the start of the real mode | |
933 | kernel. This means that if you loaded your real-mode kernel code at | |
934 | 0x90000, the kernel entry point is 9020:0000. | |
935 | ||
936 | At entry, ds = es = ss should point to the start of the real-mode | |
937 | kernel code (0x9000 if the code is loaded at 0x90000), sp should be | |
938 | set up properly, normally pointing to the top of the heap, and | |
939 | interrupts should be disabled. Furthermore, to guard against bugs in | |
940 | the kernel, it is recommended that the boot loader sets fs = gs = ds = | |
941 | es = ss. | |
942 | ||
943 | In our example from above, we would do: | |
944 | ||
945 | /* Note: in the case of the "old" kernel protocol, base_ptr must | |
946 | be == 0x90000 at this point; see the previous sample code */ | |
947 | ||
948 | seg = base_ptr >> 4; | |
949 | ||
950 | cli(); /* Enter with interrupts disabled! */ | |
951 | ||
952 | /* Set up the real-mode kernel stack */ | |
953 | _SS = seg; | |
de372ecd | 954 | _SP = heap_end; |
1da177e4 LT |
955 | |
956 | _DS = _ES = _FS = _GS = seg; | |
957 | jmp_far(seg+0x20, 0); /* Run the kernel */ | |
958 | ||
959 | If your boot sector accesses a floppy drive, it is recommended to | |
960 | switch off the floppy motor before running the kernel, since the | |
961 | kernel boot leaves interrupts off and thus the motor will not be | |
962 | switched off, especially if the loaded kernel has the floppy driver as | |
963 | a demand-loaded module! | |
964 | ||
965 | ||
db2668fd | 966 | **** ADVANCED BOOT LOADER HOOKS |
1da177e4 LT |
967 | |
968 | If the boot loader runs in a particularly hostile environment (such as | |
969 | LOADLIN, which runs under DOS) it may be impossible to follow the | |
970 | standard memory location requirements. Such a boot loader may use the | |
971 | following hooks that, if set, are invoked by the kernel at the | |
972 | appropriate time. The use of these hooks should probably be | |
973 | considered an absolutely last resort! | |
974 | ||
975 | IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and | |
976 | %edi across invocation. | |
977 | ||
978 | realmode_swtch: | |
979 | A 16-bit real mode far subroutine invoked immediately before | |
980 | entering protected mode. The default routine disables NMI, so | |
981 | your routine should probably do so, too. | |
982 | ||
983 | code32_start: | |
984 | A 32-bit flat-mode routine *jumped* to immediately after the | |
985 | transition to protected mode, but before the kernel is | |
de372ecd PA |
986 | uncompressed. No segments, except CS, are guaranteed to be |
987 | set up (current kernels do, but older ones do not); you should | |
988 | set them up to BOOT_DS (0x18) yourself. | |
1da177e4 LT |
989 | |
990 | After completing your hook, you should jump to the address | |
db2668fd PA |
991 | that was in this field before your boot loader overwrote it |
992 | (relocated, if appropriate.) | |
aa69432a HY |
993 | |
994 | ||
995 | **** 32-bit BOOT PROTOCOL | |
996 | ||
997 | For machine with some new BIOS other than legacy BIOS, such as EFI, | |
998 | LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel | |
999 | based on legacy BIOS can not be used, so a 32-bit boot protocol needs | |
1000 | to be defined. | |
1001 | ||
1002 | In 32-bit boot protocol, the first step in loading a Linux kernel | |
1003 | should be to setup the boot parameters (struct boot_params, | |
1004 | traditionally known as "zero page"). The memory for struct boot_params | |
1005 | should be allocated and initialized to all zero. Then the setup header | |
1006 | from offset 0x01f1 of kernel image on should be loaded into struct | |
1007 | boot_params and examined. The end of setup header can be calculated as | |
1008 | follow: | |
1009 | ||
1010 | 0x0202 + byte value at offset 0x0201 | |
1011 | ||
1012 | In addition to read/modify/write the setup header of the struct | |
1013 | boot_params as that of 16-bit boot protocol, the boot loader should | |
1014 | also fill the additional fields of the struct boot_params as that | |
1015 | described in zero-page.txt. | |
1016 | ||
1017 | After setupping the struct boot_params, the boot loader can load the | |
1018 | 32/64-bit kernel in the same way as that of 16-bit boot protocol. | |
1019 | ||
1020 | In 32-bit boot protocol, the kernel is started by jumping to the | |
1021 | 32-bit kernel entry point, which is the start address of loaded | |
1022 | 32/64-bit kernel. | |
1023 | ||
1024 | At entry, the CPU must be in 32-bit protected mode with paging | |
1025 | disabled; a GDT must be loaded with the descriptors for selectors | |
1026 | __BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat | |
1027 | segment; __BOOS_CS must have execute/read permission, and __BOOT_DS | |
1028 | must have read/write permission; CS must be __BOOT_CS and DS, ES, SS | |
1029 | must be __BOOT_DS; interrupt must be disabled; %esi must hold the base | |
1030 | address of the struct boot_params; %ebp, %edi and %ebx must be zero. | |
9ca8f72a MF |
1031 | |
1032 | **** EFI HANDOVER PROTOCOL | |
1033 | ||
1034 | This protocol allows boot loaders to defer initialisation to the EFI | |
1035 | boot stub. The boot loader is required to load the kernel/initrd(s) | |
1036 | from the boot media and jump to the EFI handover protocol entry point | |
1037 | which is hdr->handover_offset bytes from the beginning of | |
1038 | startup_{32,64}. | |
1039 | ||
1040 | The function prototype for the handover entry point looks like this, | |
1041 | ||
1042 | efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp) | |
1043 | ||
1044 | 'handle' is the EFI image handle passed to the boot loader by the EFI | |
1045 | firmware, 'table' is the EFI system table - these are the first two | |
1046 | arguments of the "handoff state" as described in section 2.3 of the | |
1047 | UEFI specification. 'bp' is the boot loader-allocated boot params. | |
1048 | ||
1049 | The boot loader *must* fill out the following fields in bp, | |
1050 | ||
1051 | o hdr.code32_start | |
1052 | o hdr.cmd_line_ptr | |
1053 | o hdr.cmdline_size | |
1054 | o hdr.ramdisk_image (if applicable) | |
1055 | o hdr.ramdisk_size (if applicable) | |
1056 | ||
1057 | All other fields should be zero. |