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