]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | THE LINUX/I386 BOOT PROTOCOL |
2 | ---------------------------- | |
3 | ||
4 | H. Peter Anvin <hpa@zytor.com> | |
dec04cff | 5 | Last update 2007-05-16 |
1da177e4 LT |
6 | |
7 | On the i386 platform, the Linux kernel uses a rather complicated boot | |
8 | convention. This has evolved partially due to historical aspects, as | |
9 | well as the desire in the early days to have the kernel itself be a | |
10 | bootable image, the complicated PC memory model and due to changed | |
11 | expectations in the PC industry caused by the effective demise of | |
12 | real-mode DOS as a mainstream operating system. | |
13 | ||
de372ecd | 14 | Currently, the following versions of the Linux/i386 boot protocol exist. |
1da177e4 LT |
15 | |
16 | Old kernels: zImage/Image support only. Some very early kernels | |
17 | may not even support a command line. | |
18 | ||
19 | Protocol 2.00: (Kernel 1.3.73) Added bzImage and initrd support, as | |
20 | well as a formalized way to communicate between the | |
21 | boot loader and the kernel. setup.S made relocatable, | |
22 | although the traditional setup area still assumed | |
23 | writable. | |
24 | ||
25 | Protocol 2.01: (Kernel 1.3.76) Added a heap overrun warning. | |
26 | ||
27 | Protocol 2.02: (Kernel 2.4.0-test3-pre3) New command line protocol. | |
28 | Lower the conventional memory ceiling. No overwrite | |
29 | of the traditional setup area, thus making booting | |
30 | safe for systems which use the EBDA from SMM or 32-bit | |
31 | BIOS entry points. zImage deprecated but still | |
32 | supported. | |
33 | ||
34 | Protocol 2.03: (Kernel 2.4.18-pre1) Explicitly makes the highest possible | |
35 | initrd address available to the bootloader. | |
36 | ||
f8eeaaf4 | 37 | Protocol 2.04: (Kernel 2.6.14) Extend the syssize field to four bytes. |
8f9aeca7 | 38 | |
be274eea VG |
39 | Protocol 2.05: (Kernel 2.6.20) Make protected mode kernel relocatable. |
40 | Introduce relocatable_kernel and kernel_alignment fields. | |
f8eeaaf4 | 41 | |
8f9aeca7 BW |
42 | Protocol 2.06: (Kernel 2.6.22) Added a field that contains the size of |
43 | the boot command line | |
44 | ||
1da177e4 LT |
45 | |
46 | **** MEMORY LAYOUT | |
47 | ||
48 | The traditional memory map for the kernel loader, used for Image or | |
49 | zImage kernels, typically looks like: | |
50 | ||
51 | | | | |
52 | 0A0000 +------------------------+ | |
53 | | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. | |
54 | 09A000 +------------------------+ | |
dec04cff PA |
55 | | Command line | |
56 | | Stack/heap | For use by the kernel real-mode code. | |
1da177e4 LT |
57 | 098000 +------------------------+ |
58 | | Kernel setup | The kernel real-mode code. | |
59 | 090200 +------------------------+ | |
60 | | Kernel boot sector | The kernel legacy boot sector. | |
61 | 090000 +------------------------+ | |
62 | | Protected-mode kernel | The bulk of the kernel image. | |
63 | 010000 +------------------------+ | |
64 | | Boot loader | <- Boot sector entry point 0000:7C00 | |
65 | 001000 +------------------------+ | |
66 | | Reserved for MBR/BIOS | | |
67 | 000800 +------------------------+ | |
68 | | Typically used by MBR | | |
69 | 000600 +------------------------+ | |
70 | | BIOS use only | | |
71 | 000000 +------------------------+ | |
72 | ||
73 | ||
74 | When using bzImage, the protected-mode kernel was relocated to | |
75 | 0x100000 ("high memory"), and the kernel real-mode block (boot sector, | |
76 | setup, and stack/heap) was made relocatable to any address between | |
dec04cff PA |
77 | 0x10000 and end of low memory. Unfortunately, in protocols 2.00 and |
78 | 2.01 the 0x90000+ memory range is still used internally by the kernel; | |
79 | the 2.02 protocol resolves that problem. | |
1da177e4 LT |
80 | |
81 | It is desirable to keep the "memory ceiling" -- the highest point in | |
82 | low memory touched by the boot loader -- as low as possible, since | |
83 | some newer BIOSes have begun to allocate some rather large amounts of | |
84 | memory, called the Extended BIOS Data Area, near the top of low | |
85 | memory. The boot loader should use the "INT 12h" BIOS call to verify | |
86 | how much low memory is available. | |
87 | ||
88 | Unfortunately, if INT 12h reports that the amount of memory is too | |
89 | low, there is usually nothing the boot loader can do but to report an | |
90 | error to the user. The boot loader should therefore be designed to | |
91 | take up as little space in low memory as it reasonably can. For | |
92 | zImage or old bzImage kernels, which need data written into the | |
93 | 0x90000 segment, the boot loader should make sure not to use memory | |
94 | above the 0x9A000 point; too many BIOSes will break above that point. | |
95 | ||
dec04cff PA |
96 | For a modern bzImage kernel with boot protocol version >= 2.02, a |
97 | memory layout like the following is suggested: | |
98 | ||
99 | ~ ~ | |
100 | | Protected-mode kernel | | |
101 | 100000 +------------------------+ | |
102 | | I/O memory hole | | |
103 | 0A0000 +------------------------+ | |
104 | | Reserved for BIOS | Leave as much as possible unused | |
105 | ~ ~ | |
106 | | Command line | (Can also be below the X+10000 mark) | |
107 | X+10000 +------------------------+ | |
108 | | Stack/heap | For use by the kernel real-mode code. | |
109 | X+08000 +------------------------+ | |
110 | | Kernel setup | The kernel real-mode code. | |
111 | | Kernel boot sector | The kernel legacy boot sector. | |
112 | X +------------------------+ | |
113 | | Boot loader | <- Boot sector entry point 0000:7C00 | |
114 | 001000 +------------------------+ | |
115 | | Reserved for MBR/BIOS | | |
116 | 000800 +------------------------+ | |
117 | | Typically used by MBR | | |
118 | 000600 +------------------------+ | |
119 | | BIOS use only | | |
120 | 000000 +------------------------+ | |
121 | ||
122 | ... where the address X is as low as the design of the boot loader | |
123 | permits. | |
124 | ||
1da177e4 LT |
125 | |
126 | **** THE REAL-MODE KERNEL HEADER | |
127 | ||
128 | In the following text, and anywhere in the kernel boot sequence, "a | |
129 | sector" refers to 512 bytes. It is independent of the actual sector | |
130 | size of the underlying medium. | |
131 | ||
132 | The first step in loading a Linux kernel should be to load the | |
133 | real-mode code (boot sector and setup code) and then examine the | |
134 | following header at offset 0x01f1. The real-mode code can total up to | |
135 | 32K, although the boot loader may choose to load only the first two | |
136 | sectors (1K) and then examine the bootup sector size. | |
137 | ||
138 | The header looks like: | |
139 | ||
140 | Offset Proto Name Meaning | |
141 | /Size | |
142 | ||
f8eeaaf4 | 143 | 01F1/1 ALL(1 setup_sects The size of the setup in sectors |
1da177e4 | 144 | 01F2/2 ALL root_flags If set, the root is mounted readonly |
f8eeaaf4 | 145 | 01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras |
1da177e4 LT |
146 | 01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only |
147 | 01FA/2 ALL vid_mode Video mode control | |
148 | 01FC/2 ALL root_dev Default root device number | |
149 | 01FE/2 ALL boot_flag 0xAA55 magic number | |
150 | 0200/2 2.00+ jump Jump instruction | |
151 | 0202/4 2.00+ header Magic signature "HdrS" | |
152 | 0206/2 2.00+ version Boot protocol version supported | |
153 | 0208/4 2.00+ realmode_swtch Boot loader hook (see below) | |
154 | 020C/2 2.00+ start_sys The load-low segment (0x1000) (obsolete) | |
155 | 020E/2 2.00+ kernel_version Pointer to kernel version string | |
156 | 0210/1 2.00+ type_of_loader Boot loader identifier | |
157 | 0211/1 2.00+ loadflags Boot protocol option flags | |
158 | 0212/2 2.00+ setup_move_size Move to high memory size (used with hooks) | |
159 | 0214/4 2.00+ code32_start Boot loader hook (see below) | |
160 | 0218/4 2.00+ ramdisk_image initrd load address (set by boot loader) | |
161 | 021C/4 2.00+ ramdisk_size initrd size (set by boot loader) | |
162 | 0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only | |
163 | 0224/2 2.01+ heap_end_ptr Free memory after setup end | |
164 | 0226/2 N/A pad1 Unused | |
165 | 0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line | |
166 | 022C/4 2.03+ initrd_addr_max Highest legal initrd address | |
d263b213 VG |
167 | 0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel |
168 | 0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not | |
8f9aeca7 BW |
169 | 0235/3 N/A pad2 Unused |
170 | 0238/4 2.06+ cmdline_size Maximum size of the kernel command line | |
1da177e4 | 171 | |
f8eeaaf4 PA |
172 | (1) For backwards compatibility, if the setup_sects field contains 0, the |
173 | real value is 4. | |
174 | ||
175 | (2) For boot protocol prior to 2.04, the upper two bytes of the syssize | |
176 | field are unusable, which means the size of a bzImage kernel | |
177 | cannot be determined. | |
1da177e4 LT |
178 | |
179 | If the "HdrS" (0x53726448) magic number is not found at offset 0x202, | |
180 | the boot protocol version is "old". Loading an old kernel, the | |
181 | following parameters should be assumed: | |
182 | ||
183 | Image type = zImage | |
184 | initrd not supported | |
185 | Real-mode kernel must be located at 0x90000. | |
186 | ||
187 | Otherwise, the "version" field contains the protocol version, | |
188 | e.g. protocol version 2.01 will contain 0x0201 in this field. When | |
189 | setting fields in the header, you must make sure only to set fields | |
190 | supported by the protocol version in use. | |
191 | ||
dec04cff PA |
192 | |
193 | **** DETAILS OF HEADER FIELDS | |
194 | ||
195 | For each field, some are information from the kernel to the bootloader | |
196 | ("read"), some are expected to be filled out by the bootloader | |
197 | ("write"), and some are expected to be read and modified by the | |
198 | bootloader ("modify"). | |
199 | ||
200 | All general purpose boot loaders should write the fields marked | |
201 | (obligatory). Boot loaders who want to load the kernel at a | |
202 | nonstandard address should fill in the fields marked (reloc); other | |
203 | boot loaders can ignore those fields. | |
204 | ||
205 | Field name: setup_secs | |
206 | Type: read | |
207 | Offset/size: 0x1f1/1 | |
208 | Protocol: ALL | |
209 | ||
210 | The size of the setup code in 512-byte sectors. If this field is | |
211 | 0, the real value is 4. The real-mode code consists of the boot | |
212 | sector (always one 512-byte sector) plus the setup code. | |
213 | ||
214 | Field name: root_flags | |
215 | Type: modify (optional) | |
216 | Offset/size: 0x1f2/2 | |
217 | Protocol: ALL | |
218 | ||
219 | If this field is nonzero, the root defaults to readonly. The use of | |
220 | this field is deprecated; use the "ro" or "rw" options on the | |
221 | command line instead. | |
222 | ||
223 | Field name: syssize | |
224 | Type: read | |
225 | Offset/size: 0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL) | |
226 | Protocol: 2.04+ | |
227 | ||
228 | The size of the protected-mode code in units of 16-byte paragraphs. | |
229 | For protocol versions older than 2.04 this field is only two bytes | |
230 | wide, and therefore cannot be trusted for the size of a kernel if | |
231 | the LOAD_HIGH flag is set. | |
232 | ||
233 | Field name: ram_size | |
234 | Type: kernel internal | |
235 | Offset/size: 0x1f8/2 | |
236 | Protocol: ALL | |
237 | ||
238 | This field is obsolete. | |
239 | ||
240 | Field name: vid_mode | |
241 | Type: modify (obligatory) | |
242 | Offset/size: 0x1fa/2 | |
243 | ||
244 | Please see the section on SPECIAL COMMAND LINE OPTIONS. | |
245 | ||
246 | Field name: root_dev | |
247 | Type: modify (optional) | |
248 | Offset/size: 0x1fc/2 | |
249 | Protocol: ALL | |
250 | ||
251 | The default root device device number. The use of this field is | |
252 | deprecated, use the "root=" option on the command line instead. | |
253 | ||
254 | Field name: boot_flag | |
255 | Type: read | |
256 | Offset/size: 0x1fe/2 | |
257 | Protocol: ALL | |
258 | ||
259 | Contains 0xAA55. This is the closest thing old Linux kernels have | |
260 | to a magic number. | |
261 | ||
262 | Field name: jump | |
263 | Type: read | |
264 | Offset/size: 0x200/2 | |
265 | Protocol: 2.00+ | |
266 | ||
267 | Contains an x86 jump instruction, 0xEB followed by a signed offset | |
268 | relative to byte 0x202. This can be used to determine the size of | |
269 | the header. | |
270 | ||
271 | Field name: header | |
272 | Type: read | |
273 | Offset/size: 0x202/4 | |
274 | Protocol: 2.00+ | |
275 | ||
276 | Contains the magic number "HdrS" (0x53726448). | |
277 | ||
278 | Field name: version | |
279 | Type: read | |
280 | Offset/size: 0x206/2 | |
281 | Protocol: 2.00+ | |
282 | ||
283 | Contains the boot protocol version, e.g. 0x0204 for version 2.04. | |
284 | ||
285 | Field name: readmode_swtch | |
286 | Type: modify (optional) | |
287 | Offset/size: 0x208/4 | |
288 | Protocol: 2.00+ | |
289 | ||
290 | Boot loader hook (see separate chapter.) | |
291 | ||
292 | Field name: start_sys | |
293 | Type: read | |
294 | Offset/size: 0x20c/4 | |
295 | Protocol: 2.00+ | |
296 | ||
297 | The load low segment (0x1000). Obsolete. | |
298 | ||
299 | Field name: kernel_version | |
300 | Type: read | |
301 | Offset/size: 0x20e/2 | |
302 | Protocol: 2.00+ | |
303 | ||
304 | If set to a nonzero value, contains a pointer to a NUL-terminated | |
305 | human-readable kernel version number string, less 0x200. This can | |
306 | be used to display the kernel version to the user. This value | |
307 | should be less than (0x200*setup_sects). For example, if this value | |
308 | is set to 0x1c00, the kernel version number string can be found at | |
309 | offset 0x1e00 in the kernel file. This is a valid value if and only | |
310 | if the "setup_sects" field contains the value 14 or higher. | |
311 | ||
312 | Field name: type_of_loader | |
313 | Type: write (obligatory) | |
314 | Offset/size: 0x210/1 | |
315 | Protocol: 2.00+ | |
316 | ||
317 | If your boot loader has an assigned id (see table below), enter | |
318 | 0xTV here, where T is an identifier for the boot loader and V is | |
319 | a version number. Otherwise, enter 0xFF here. | |
320 | ||
321 | Assigned boot loader ids: | |
de372ecd | 322 | 0 LILO (0x00 reserved for pre-2.00 bootloader) |
1da177e4 | 323 | 1 Loadlin |
de372ecd | 324 | 2 bootsect-loader (0x20, all other values reserved) |
1da177e4 LT |
325 | 3 SYSLINUX |
326 | 4 EtherBoot | |
327 | 5 ELILO | |
328 | 7 GRuB | |
329 | 8 U-BOOT | |
354332ee | 330 | 9 Xen |
c229ec5d | 331 | A Gujin |
dec04cff | 332 | B Qemu |
1da177e4 | 333 | |
dec04cff PA |
334 | Please contact <hpa@zytor.com> if you need a bootloader ID |
335 | value assigned. | |
336 | ||
337 | Field name: loadflags | |
338 | Type: modify (obligatory) | |
339 | Offset/size: 0x211/1 | |
340 | Protocol: 2.00+ | |
341 | ||
342 | This field is a bitmask. | |
343 | ||
344 | Bit 0 (read): LOADED_HIGH | |
345 | - If 0, the protected-mode code is loaded at 0x10000. | |
346 | - If 1, the protected-mode code is loaded at 0x100000. | |
347 | ||
348 | Bit 7 (write): CAN_USE_HEAP | |
349 | Set this bit to 1 to indicate that the value entered in the | |
350 | heap_end_ptr is valid. If this field is clear, some setup code | |
351 | functionality will be disabled. | |
352 | ||
353 | Field name: setup_move_size | |
354 | Type: modify (obligatory) | |
355 | Offset/size: 0x212/2 | |
356 | Protocol: 2.00-2.01 | |
357 | ||
358 | When using protocol 2.00 or 2.01, if the real mode kernel is not | |
359 | loaded at 0x90000, it gets moved there later in the loading | |
360 | sequence. Fill in this field if you want additional data (such as | |
361 | the kernel command line) moved in addition to the real-mode kernel | |
362 | itself. | |
363 | ||
364 | The unit is bytes starting with the beginning of the boot sector. | |
365 | ||
366 | This field is can be ignored when the protocol is 2.02 or higher, or | |
367 | if the real-mode code is loaded at 0x90000. | |
368 | ||
369 | Field name: code32_start | |
370 | Type: modify (optional, reloc) | |
371 | Offset/size: 0x214/4 | |
372 | Protocol: 2.00+ | |
373 | ||
374 | The address to jump to in protected mode. This defaults to the load | |
375 | address of the kernel, and can be used by the boot loader to | |
376 | determine the proper load address. | |
377 | ||
378 | This field can be modified for two purposes: | |
379 | ||
380 | 1. as a boot loader hook (see separate chapter.) | |
381 | ||
382 | 2. if a bootloader which does not install a hook loads a | |
383 | relocatable kernel at a nonstandard address it will have to modify | |
384 | this field to point to the load address. | |
385 | ||
386 | Field name: ramdisk_image | |
387 | Type: write (obligatory) | |
388 | Offset/size: 0x218/4 | |
389 | Protocol: 2.00+ | |
390 | ||
391 | The 32-bit linear address of the initial ramdisk or ramfs. Leave at | |
392 | zero if there is no initial ramdisk/ramfs. | |
393 | ||
394 | Field name: ramdisk_size | |
395 | Type: write (obligatory) | |
396 | Offset/size: 0x21c/4 | |
397 | Protocol: 2.00+ | |
398 | ||
399 | Size of the initial ramdisk or ramfs. Leave at zero if there is no | |
400 | initial ramdisk/ramfs. | |
401 | ||
402 | Field name: bootsect_kludge | |
403 | Type: kernel internal | |
404 | Offset/size: 0x220/4 | |
405 | Protocol: 2.00+ | |
406 | ||
407 | This field is obsolete. | |
408 | ||
409 | Field name: heap_end_ptr | |
410 | Type: write (obligatory) | |
411 | Offset/size: 0x224/2 | |
412 | Protocol: 2.01+ | |
413 | ||
414 | Set this field to the offset (from the beginning of the real-mode | |
415 | code) of the end of the setup stack/heap, minus 0x0200. | |
416 | ||
417 | Field name: cmd_line_ptr | |
418 | Type: write (obligatory) | |
419 | Offset/size: 0x228/4 | |
420 | Protocol: 2.02+ | |
421 | ||
422 | Set this field to the linear address of the kernel command line. | |
423 | The kernel command line can be located anywhere between the end of | |
424 | the setup heap and 0xA0000; it does not have to be located in the | |
425 | same 64K segment as the real-mode code itself. | |
426 | ||
427 | Fill in this field even if your boot loader does not support a | |
428 | command line, in which case you can point this to an empty string | |
429 | (or better yet, to the string "auto".) If this field is left at | |
430 | zero, the kernel will assume that your boot loader does not support | |
431 | the 2.02+ protocol. | |
432 | ||
433 | Field name: initrd_addr_max | |
434 | Type: read | |
435 | Offset/size: 0x22c/4 | |
436 | Protocol: 2.03+ | |
437 | ||
438 | The maximum address that may be occupied by the initial | |
439 | ramdisk/ramfs contents. For boot protocols 2.02 or earlier, this | |
440 | field is not present, and the maximum address is 0x37FFFFFF. (This | |
441 | address is defined as the address of the highest safe byte, so if | |
442 | your ramdisk is exactly 131072 bytes long and this field is | |
443 | 0x37FFFFFF, you can start your ramdisk at 0x37FE0000.) | |
444 | ||
445 | Field name: kernel_alignment | |
446 | Type: read (reloc) | |
447 | Offset/size: 0x230/4 | |
448 | Protocol: 2.05+ | |
449 | ||
450 | Alignment unit required by the kernel (if relocatable_kernel is true.) | |
451 | ||
452 | Field name: relocatable_kernel | |
453 | Type: read (reloc) | |
454 | Offset/size: 0x234/1 | |
455 | Protocol: 2.05+ | |
456 | ||
457 | If this field is nonzero, the protected-mode part of the kernel can | |
458 | be loaded at any address that satisfies the kernel_alignment field. | |
459 | After loading, the boot loader must set the code32_start field to | |
460 | point to the loaded code, or to a boot loader hook. | |
461 | ||
462 | Field name: cmdline_size | |
463 | Type: read | |
464 | Offset/size: 0x238/4 | |
465 | Protocol: 2.06+ | |
466 | ||
467 | The maximum size of the command line without the terminating | |
468 | zero. This means that the command line can contain at most | |
469 | cmdline_size characters. With protocol version 2.05 and earlier, the | |
470 | maximum size was 255. | |
8f9aeca7 | 471 | |
1da177e4 LT |
472 | |
473 | **** THE KERNEL COMMAND LINE | |
474 | ||
475 | The kernel command line has become an important way for the boot | |
476 | loader to communicate with the kernel. Some of its options are also | |
477 | relevant to the boot loader itself, see "special command line options" | |
478 | below. | |
479 | ||
8f9aeca7 BW |
480 | The kernel command line is a null-terminated string. The maximum |
481 | length can be retrieved from the field cmdline_size. Before protocol | |
482 | version 2.06, the maximum was 255 characters. A string that is too | |
483 | long will be automatically truncated by the kernel. | |
1da177e4 LT |
484 | |
485 | If the boot protocol version is 2.02 or later, the address of the | |
486 | kernel command line is given by the header field cmd_line_ptr (see | |
f8eeaaf4 PA |
487 | above.) This address can be anywhere between the end of the setup |
488 | heap and 0xA0000. | |
1da177e4 LT |
489 | |
490 | If the protocol version is *not* 2.02 or higher, the kernel | |
491 | command line is entered using the following protocol: | |
492 | ||
493 | At offset 0x0020 (word), "cmd_line_magic", enter the magic | |
494 | number 0xA33F. | |
495 | ||
496 | At offset 0x0022 (word), "cmd_line_offset", enter the offset | |
497 | of the kernel command line (relative to the start of the | |
498 | real-mode kernel). | |
499 | ||
500 | The kernel command line *must* be within the memory region | |
501 | covered by setup_move_size, so you may need to adjust this | |
502 | field. | |
503 | ||
504 | ||
de372ecd PA |
505 | **** MEMORY LAYOUT OF THE REAL-MODE CODE |
506 | ||
507 | The real-mode code requires a stack/heap to be set up, as well as | |
508 | memory allocated for the kernel command line. This needs to be done | |
509 | in the real-mode accessible memory in bottom megabyte. | |
510 | ||
511 | It should be noted that modern machines often have a sizable Extended | |
512 | BIOS Data Area (EBDA). As a result, it is advisable to use as little | |
513 | of the low megabyte as possible. | |
514 | ||
515 | Unfortunately, under the following circumstances the 0x90000 memory | |
516 | segment has to be used: | |
517 | ||
518 | - When loading a zImage kernel ((loadflags & 0x01) == 0). | |
519 | - When loading a 2.01 or earlier boot protocol kernel. | |
520 | ||
521 | -> For the 2.00 and 2.01 boot protocols, the real-mode code | |
522 | can be loaded at another address, but it is internally | |
523 | relocated to 0x90000. For the "old" protocol, the | |
524 | real-mode code must be loaded at 0x90000. | |
525 | ||
526 | When loading at 0x90000, avoid using memory above 0x9a000. | |
527 | ||
528 | For boot protocol 2.02 or higher, the command line does not have to be | |
529 | located in the same 64K segment as the real-mode setup code; it is | |
530 | thus permitted to give the stack/heap the full 64K segment and locate | |
531 | the command line above it. | |
532 | ||
533 | The kernel command line should not be located below the real-mode | |
534 | code, nor should it be located in high memory. | |
535 | ||
536 | ||
1da177e4 LT |
537 | **** SAMPLE BOOT CONFIGURATION |
538 | ||
539 | As a sample configuration, assume the following layout of the real | |
de372ecd PA |
540 | mode segment: |
541 | ||
542 | When loading below 0x90000, use the entire segment: | |
543 | ||
544 | 0x0000-0x7fff Real mode kernel | |
545 | 0x8000-0xdfff Stack and heap | |
546 | 0xe000-0xffff Kernel command line | |
1da177e4 | 547 | |
de372ecd PA |
548 | When loading at 0x90000 OR the protocol version is 2.01 or earlier: |
549 | ||
550 | 0x0000-0x7fff Real mode kernel | |
551 | 0x8000-0x97ff Stack and heap | |
552 | 0x9800-0x9fff Kernel command line | |
1da177e4 LT |
553 | |
554 | Such a boot loader should enter the following fields in the header: | |
555 | ||
556 | unsigned long base_ptr; /* base address for real-mode segment */ | |
557 | ||
558 | if ( setup_sects == 0 ) { | |
559 | setup_sects = 4; | |
560 | } | |
561 | ||
562 | if ( protocol >= 0x0200 ) { | |
563 | type_of_loader = <type code>; | |
564 | if ( loading_initrd ) { | |
565 | ramdisk_image = <initrd_address>; | |
566 | ramdisk_size = <initrd_size>; | |
567 | } | |
de372ecd PA |
568 | |
569 | if ( protocol >= 0x0202 && loadflags & 0x01 ) | |
570 | heap_end = 0xe000; | |
571 | else | |
572 | heap_end = 0x9800; | |
573 | ||
1da177e4 | 574 | if ( protocol >= 0x0201 ) { |
de372ecd | 575 | heap_end_ptr = heap_end - 0x200; |
1da177e4 LT |
576 | loadflags |= 0x80; /* CAN_USE_HEAP */ |
577 | } | |
de372ecd | 578 | |
1da177e4 | 579 | if ( protocol >= 0x0202 ) { |
de372ecd PA |
580 | cmd_line_ptr = base_ptr + heap_end; |
581 | strcpy(cmd_line_ptr, cmdline); | |
1da177e4 LT |
582 | } else { |
583 | cmd_line_magic = 0xA33F; | |
de372ecd PA |
584 | cmd_line_offset = heap_end; |
585 | setup_move_size = heap_end + strlen(cmdline)+1; | |
586 | strcpy(base_ptr+cmd_line_offset, cmdline); | |
1da177e4 LT |
587 | } |
588 | } else { | |
589 | /* Very old kernel */ | |
590 | ||
de372ecd PA |
591 | heap_end = 0x9800; |
592 | ||
1da177e4 | 593 | cmd_line_magic = 0xA33F; |
de372ecd | 594 | cmd_line_offset = heap_end; |
1da177e4 LT |
595 | |
596 | /* A very old kernel MUST have its real-mode code | |
597 | loaded at 0x90000 */ | |
598 | ||
599 | if ( base_ptr != 0x90000 ) { | |
600 | /* Copy the real-mode kernel */ | |
601 | memcpy(0x90000, base_ptr, (setup_sects+1)*512); | |
1da177e4 LT |
602 | base_ptr = 0x90000; /* Relocated */ |
603 | } | |
604 | ||
de372ecd PA |
605 | strcpy(0x90000+cmd_line_offset, cmdline); |
606 | ||
1da177e4 LT |
607 | /* It is recommended to clear memory up to the 32K mark */ |
608 | memset(0x90000 + (setup_sects+1)*512, 0, | |
609 | (64-(setup_sects+1))*512); | |
610 | } | |
611 | ||
612 | ||
613 | **** LOADING THE REST OF THE KERNEL | |
614 | ||
f8eeaaf4 PA |
615 | The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 |
616 | in the kernel file (again, if setup_sects == 0 the real value is 4.) | |
617 | It should be loaded at address 0x10000 for Image/zImage kernels and | |
1da177e4 LT |
618 | 0x100000 for bzImage kernels. |
619 | ||
620 | The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 | |
621 | bit (LOAD_HIGH) in the loadflags field is set: | |
622 | ||
623 | is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01); | |
624 | load_address = is_bzImage ? 0x100000 : 0x10000; | |
625 | ||
626 | Note that Image/zImage kernels can be up to 512K in size, and thus use | |
627 | the entire 0x10000-0x90000 range of memory. This means it is pretty | |
628 | much a requirement for these kernels to load the real-mode part at | |
629 | 0x90000. bzImage kernels allow much more flexibility. | |
630 | ||
631 | ||
632 | **** SPECIAL COMMAND LINE OPTIONS | |
633 | ||
634 | If the command line provided by the boot loader is entered by the | |
635 | user, the user may expect the following command line options to work. | |
636 | They should normally not be deleted from the kernel command line even | |
637 | though not all of them are actually meaningful to the kernel. Boot | |
638 | loader authors who need additional command line options for the boot | |
639 | loader itself should get them registered in | |
640 | Documentation/kernel-parameters.txt to make sure they will not | |
641 | conflict with actual kernel options now or in the future. | |
642 | ||
643 | vga=<mode> | |
644 | <mode> here is either an integer (in C notation, either | |
645 | decimal, octal, or hexadecimal) or one of the strings | |
646 | "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask" | |
647 | (meaning 0xFFFD). This value should be entered into the | |
648 | vid_mode field, as it is used by the kernel before the command | |
649 | line is parsed. | |
650 | ||
651 | mem=<size> | |
de372ecd PA |
652 | <size> is an integer in C notation optionally followed by |
653 | (case insensitive) K, M, G, T, P or E (meaning << 10, << 20, | |
654 | << 30, << 40, << 50 or << 60). This specifies the end of | |
655 | memory to the kernel. This affects the possible placement of | |
656 | an initrd, since an initrd should be placed near end of | |
1da177e4 LT |
657 | memory. Note that this is an option to *both* the kernel and |
658 | the bootloader! | |
659 | ||
660 | initrd=<file> | |
661 | An initrd should be loaded. The meaning of <file> is | |
662 | obviously bootloader-dependent, and some boot loaders | |
663 | (e.g. LILO) do not have such a command. | |
664 | ||
665 | In addition, some boot loaders add the following options to the | |
666 | user-specified command line: | |
667 | ||
668 | BOOT_IMAGE=<file> | |
669 | The boot image which was loaded. Again, the meaning of <file> | |
670 | is obviously bootloader-dependent. | |
671 | ||
672 | auto | |
673 | The kernel was booted without explicit user intervention. | |
674 | ||
675 | If these options are added by the boot loader, it is highly | |
676 | recommended that they are located *first*, before the user-specified | |
677 | or configuration-specified command line. Otherwise, "init=/bin/sh" | |
678 | gets confused by the "auto" option. | |
679 | ||
680 | ||
681 | **** RUNNING THE KERNEL | |
682 | ||
683 | The kernel is started by jumping to the kernel entry point, which is | |
684 | located at *segment* offset 0x20 from the start of the real mode | |
685 | kernel. This means that if you loaded your real-mode kernel code at | |
686 | 0x90000, the kernel entry point is 9020:0000. | |
687 | ||
688 | At entry, ds = es = ss should point to the start of the real-mode | |
689 | kernel code (0x9000 if the code is loaded at 0x90000), sp should be | |
690 | set up properly, normally pointing to the top of the heap, and | |
691 | interrupts should be disabled. Furthermore, to guard against bugs in | |
692 | the kernel, it is recommended that the boot loader sets fs = gs = ds = | |
693 | es = ss. | |
694 | ||
695 | In our example from above, we would do: | |
696 | ||
697 | /* Note: in the case of the "old" kernel protocol, base_ptr must | |
698 | be == 0x90000 at this point; see the previous sample code */ | |
699 | ||
700 | seg = base_ptr >> 4; | |
701 | ||
702 | cli(); /* Enter with interrupts disabled! */ | |
703 | ||
704 | /* Set up the real-mode kernel stack */ | |
705 | _SS = seg; | |
de372ecd | 706 | _SP = heap_end; |
1da177e4 LT |
707 | |
708 | _DS = _ES = _FS = _GS = seg; | |
709 | jmp_far(seg+0x20, 0); /* Run the kernel */ | |
710 | ||
711 | If your boot sector accesses a floppy drive, it is recommended to | |
712 | switch off the floppy motor before running the kernel, since the | |
713 | kernel boot leaves interrupts off and thus the motor will not be | |
714 | switched off, especially if the loaded kernel has the floppy driver as | |
715 | a demand-loaded module! | |
716 | ||
717 | ||
718 | **** ADVANCED BOOT TIME HOOKS | |
719 | ||
720 | If the boot loader runs in a particularly hostile environment (such as | |
721 | LOADLIN, which runs under DOS) it may be impossible to follow the | |
722 | standard memory location requirements. Such a boot loader may use the | |
723 | following hooks that, if set, are invoked by the kernel at the | |
724 | appropriate time. The use of these hooks should probably be | |
725 | considered an absolutely last resort! | |
726 | ||
727 | IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and | |
728 | %edi across invocation. | |
729 | ||
730 | realmode_swtch: | |
731 | A 16-bit real mode far subroutine invoked immediately before | |
732 | entering protected mode. The default routine disables NMI, so | |
733 | your routine should probably do so, too. | |
734 | ||
735 | code32_start: | |
736 | A 32-bit flat-mode routine *jumped* to immediately after the | |
737 | transition to protected mode, but before the kernel is | |
de372ecd PA |
738 | uncompressed. No segments, except CS, are guaranteed to be |
739 | set up (current kernels do, but older ones do not); you should | |
740 | set them up to BOOT_DS (0x18) yourself. | |
1da177e4 LT |
741 | |
742 | After completing your hook, you should jump to the address | |
743 | that was in this field before your boot loader overwrote it. |