Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | THE LINUX/I386 BOOT PROTOCOL |
2 | ---------------------------- | |
3 | ||
4 | H. Peter Anvin <hpa@zytor.com> | |
f8eeaaf4 | 5 | Last update 2005-09-02 |
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 | ||
14 | Currently, four versions of the Linux/i386 boot protocol exist. | |
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. |
be274eea VG |
38 | Protocol 2.05: (Kernel 2.6.20) Make protected mode kernel relocatable. |
39 | Introduce relocatable_kernel and kernel_alignment fields. | |
f8eeaaf4 | 40 | |
1da177e4 LT |
41 | |
42 | **** MEMORY LAYOUT | |
43 | ||
44 | The traditional memory map for the kernel loader, used for Image or | |
45 | zImage kernels, typically looks like: | |
46 | ||
47 | | | | |
48 | 0A0000 +------------------------+ | |
49 | | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. | |
50 | 09A000 +------------------------+ | |
51 | | Stack/heap/cmdline | For use by the kernel real-mode code. | |
52 | 098000 +------------------------+ | |
53 | | Kernel setup | The kernel real-mode code. | |
54 | 090200 +------------------------+ | |
55 | | Kernel boot sector | The kernel legacy boot sector. | |
56 | 090000 +------------------------+ | |
57 | | Protected-mode kernel | The bulk of the kernel image. | |
58 | 010000 +------------------------+ | |
59 | | Boot loader | <- Boot sector entry point 0000:7C00 | |
60 | 001000 +------------------------+ | |
61 | | Reserved for MBR/BIOS | | |
62 | 000800 +------------------------+ | |
63 | | Typically used by MBR | | |
64 | 000600 +------------------------+ | |
65 | | BIOS use only | | |
66 | 000000 +------------------------+ | |
67 | ||
68 | ||
69 | When using bzImage, the protected-mode kernel was relocated to | |
70 | 0x100000 ("high memory"), and the kernel real-mode block (boot sector, | |
71 | setup, and stack/heap) was made relocatable to any address between | |
72 | 0x10000 and end of low memory. Unfortunately, in protocols 2.00 and | |
73 | 2.01 the command line is still required to live in the 0x9XXXX memory | |
74 | range, and that memory range is still overwritten by the early kernel. | |
75 | The 2.02 protocol resolves that problem. | |
76 | ||
77 | It is desirable to keep the "memory ceiling" -- the highest point in | |
78 | low memory touched by the boot loader -- as low as possible, since | |
79 | some newer BIOSes have begun to allocate some rather large amounts of | |
80 | memory, called the Extended BIOS Data Area, near the top of low | |
81 | memory. The boot loader should use the "INT 12h" BIOS call to verify | |
82 | how much low memory is available. | |
83 | ||
84 | Unfortunately, if INT 12h reports that the amount of memory is too | |
85 | low, there is usually nothing the boot loader can do but to report an | |
86 | error to the user. The boot loader should therefore be designed to | |
87 | take up as little space in low memory as it reasonably can. For | |
88 | zImage or old bzImage kernels, which need data written into the | |
89 | 0x90000 segment, the boot loader should make sure not to use memory | |
90 | above the 0x9A000 point; too many BIOSes will break above that point. | |
91 | ||
92 | ||
93 | **** THE REAL-MODE KERNEL HEADER | |
94 | ||
95 | In the following text, and anywhere in the kernel boot sequence, "a | |
96 | sector" refers to 512 bytes. It is independent of the actual sector | |
97 | size of the underlying medium. | |
98 | ||
99 | The first step in loading a Linux kernel should be to load the | |
100 | real-mode code (boot sector and setup code) and then examine the | |
101 | following header at offset 0x01f1. The real-mode code can total up to | |
102 | 32K, although the boot loader may choose to load only the first two | |
103 | sectors (1K) and then examine the bootup sector size. | |
104 | ||
105 | The header looks like: | |
106 | ||
107 | Offset Proto Name Meaning | |
108 | /Size | |
109 | ||
f8eeaaf4 | 110 | 01F1/1 ALL(1 setup_sects The size of the setup in sectors |
1da177e4 | 111 | 01F2/2 ALL root_flags If set, the root is mounted readonly |
f8eeaaf4 | 112 | 01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras |
1da177e4 LT |
113 | 01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only |
114 | 01FA/2 ALL vid_mode Video mode control | |
115 | 01FC/2 ALL root_dev Default root device number | |
116 | 01FE/2 ALL boot_flag 0xAA55 magic number | |
117 | 0200/2 2.00+ jump Jump instruction | |
118 | 0202/4 2.00+ header Magic signature "HdrS" | |
119 | 0206/2 2.00+ version Boot protocol version supported | |
120 | 0208/4 2.00+ realmode_swtch Boot loader hook (see below) | |
121 | 020C/2 2.00+ start_sys The load-low segment (0x1000) (obsolete) | |
122 | 020E/2 2.00+ kernel_version Pointer to kernel version string | |
123 | 0210/1 2.00+ type_of_loader Boot loader identifier | |
124 | 0211/1 2.00+ loadflags Boot protocol option flags | |
125 | 0212/2 2.00+ setup_move_size Move to high memory size (used with hooks) | |
126 | 0214/4 2.00+ code32_start Boot loader hook (see below) | |
127 | 0218/4 2.00+ ramdisk_image initrd load address (set by boot loader) | |
128 | 021C/4 2.00+ ramdisk_size initrd size (set by boot loader) | |
129 | 0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only | |
130 | 0224/2 2.01+ heap_end_ptr Free memory after setup end | |
131 | 0226/2 N/A pad1 Unused | |
132 | 0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line | |
133 | 022C/4 2.03+ initrd_addr_max Highest legal initrd address | |
be274eea VG |
134 | 0230/4 2.04+ kernel_alignment Physical addr alignment required for kernel |
135 | 0234/1 2.04+ relocatable_kernel Whether kernel is relocatable or not | |
1da177e4 | 136 | |
f8eeaaf4 PA |
137 | (1) For backwards compatibility, if the setup_sects field contains 0, the |
138 | real value is 4. | |
139 | ||
140 | (2) For boot protocol prior to 2.04, the upper two bytes of the syssize | |
141 | field are unusable, which means the size of a bzImage kernel | |
142 | cannot be determined. | |
1da177e4 LT |
143 | |
144 | If the "HdrS" (0x53726448) magic number is not found at offset 0x202, | |
145 | the boot protocol version is "old". Loading an old kernel, the | |
146 | following parameters should be assumed: | |
147 | ||
148 | Image type = zImage | |
149 | initrd not supported | |
150 | Real-mode kernel must be located at 0x90000. | |
151 | ||
152 | Otherwise, the "version" field contains the protocol version, | |
153 | e.g. protocol version 2.01 will contain 0x0201 in this field. When | |
154 | setting fields in the header, you must make sure only to set fields | |
155 | supported by the protocol version in use. | |
156 | ||
157 | The "kernel_version" field, if set to a nonzero value, contains a | |
158 | pointer to a null-terminated human-readable kernel version number | |
159 | string, less 0x200. This can be used to display the kernel version to | |
160 | the user. This value should be less than (0x200*setup_sects). For | |
161 | example, if this value is set to 0x1c00, the kernel version number | |
162 | string can be found at offset 0x1e00 in the kernel file. This is a | |
163 | valid value if and only if the "setup_sects" field contains the value | |
164 | 14 or higher. | |
165 | ||
166 | Most boot loaders will simply load the kernel at its target address | |
167 | directly. Such boot loaders do not need to worry about filling in | |
168 | most of the fields in the header. The following fields should be | |
169 | filled out, however: | |
170 | ||
171 | vid_mode: | |
172 | Please see the section on SPECIAL COMMAND LINE OPTIONS. | |
173 | ||
174 | type_of_loader: | |
175 | If your boot loader has an assigned id (see table below), enter | |
176 | 0xTV here, where T is an identifier for the boot loader and V is | |
177 | a version number. Otherwise, enter 0xFF here. | |
178 | ||
179 | Assigned boot loader ids: | |
180 | 0 LILO | |
181 | 1 Loadlin | |
182 | 2 bootsect-loader | |
183 | 3 SYSLINUX | |
184 | 4 EtherBoot | |
185 | 5 ELILO | |
186 | 7 GRuB | |
187 | 8 U-BOOT | |
354332ee | 188 | 9 Xen |
1da177e4 LT |
189 | |
190 | Please contact <hpa@zytor.com> if you need a bootloader ID | |
191 | value assigned. | |
192 | ||
193 | loadflags, heap_end_ptr: | |
194 | If the protocol version is 2.01 or higher, enter the | |
195 | offset limit of the setup heap into heap_end_ptr and set the | |
196 | 0x80 bit (CAN_USE_HEAP) of loadflags. heap_end_ptr appears to | |
197 | be relative to the start of setup (offset 0x0200). | |
198 | ||
199 | setup_move_size: | |
200 | When using protocol 2.00 or 2.01, if the real mode | |
201 | kernel is not loaded at 0x90000, it gets moved there later in | |
202 | the loading sequence. Fill in this field if you want | |
203 | additional data (such as the kernel command line) moved in | |
204 | addition to the real-mode kernel itself. | |
205 | ||
206 | ramdisk_image, ramdisk_size: | |
207 | If your boot loader has loaded an initial ramdisk (initrd), | |
208 | set ramdisk_image to the 32-bit pointer to the ramdisk data | |
209 | and the ramdisk_size to the size of the ramdisk data. | |
210 | ||
211 | The initrd should typically be located as high in memory as | |
212 | possible, as it may otherwise get overwritten by the early | |
213 | kernel initialization sequence. However, it must never be | |
214 | located above the address specified in the initrd_addr_max | |
215 | field. The initrd should be at least 4K page aligned. | |
216 | ||
217 | cmd_line_ptr: | |
218 | If the protocol version is 2.02 or higher, this is a 32-bit | |
219 | pointer to the kernel command line. The kernel command line | |
220 | can be located anywhere between the end of setup and 0xA0000. | |
221 | Fill in this field even if your boot loader does not support a | |
222 | command line, in which case you can point this to an empty | |
223 | string (or better yet, to the string "auto".) If this field | |
224 | is left at zero, the kernel will assume that your boot loader | |
225 | does not support the 2.02+ protocol. | |
226 | ||
227 | ramdisk_max: | |
228 | The maximum address that may be occupied by the initrd | |
229 | contents. For boot protocols 2.02 or earlier, this field is | |
230 | not present, and the maximum address is 0x37FFFFFF. (This | |
231 | address is defined as the address of the highest safe byte, so | |
232 | if your ramdisk is exactly 131072 bytes long and this field is | |
233 | 0x37FFFFFF, you can start your ramdisk at 0x37FE0000.) | |
234 | ||
235 | ||
236 | **** THE KERNEL COMMAND LINE | |
237 | ||
238 | The kernel command line has become an important way for the boot | |
239 | loader to communicate with the kernel. Some of its options are also | |
240 | relevant to the boot loader itself, see "special command line options" | |
241 | below. | |
242 | ||
f8eeaaf4 PA |
243 | The kernel command line is a null-terminated string currently up to |
244 | 255 characters long, plus the final null. A string that is too long | |
245 | will be automatically truncated by the kernel, a boot loader may allow | |
246 | a longer command line to be passed to permit future kernels to extend | |
247 | this limit. | |
1da177e4 LT |
248 | |
249 | If the boot protocol version is 2.02 or later, the address of the | |
250 | kernel command line is given by the header field cmd_line_ptr (see | |
f8eeaaf4 PA |
251 | above.) This address can be anywhere between the end of the setup |
252 | heap and 0xA0000. | |
1da177e4 LT |
253 | |
254 | If the protocol version is *not* 2.02 or higher, the kernel | |
255 | command line is entered using the following protocol: | |
256 | ||
257 | At offset 0x0020 (word), "cmd_line_magic", enter the magic | |
258 | number 0xA33F. | |
259 | ||
260 | At offset 0x0022 (word), "cmd_line_offset", enter the offset | |
261 | of the kernel command line (relative to the start of the | |
262 | real-mode kernel). | |
263 | ||
264 | The kernel command line *must* be within the memory region | |
265 | covered by setup_move_size, so you may need to adjust this | |
266 | field. | |
267 | ||
268 | ||
269 | **** SAMPLE BOOT CONFIGURATION | |
270 | ||
271 | As a sample configuration, assume the following layout of the real | |
f8eeaaf4 | 272 | mode segment (this is a typical, and recommended layout): |
1da177e4 LT |
273 | |
274 | 0x0000-0x7FFF Real mode kernel | |
275 | 0x8000-0x8FFF Stack and heap | |
276 | 0x9000-0x90FF Kernel command line | |
277 | ||
278 | Such a boot loader should enter the following fields in the header: | |
279 | ||
280 | unsigned long base_ptr; /* base address for real-mode segment */ | |
281 | ||
282 | if ( setup_sects == 0 ) { | |
283 | setup_sects = 4; | |
284 | } | |
285 | ||
286 | if ( protocol >= 0x0200 ) { | |
287 | type_of_loader = <type code>; | |
288 | if ( loading_initrd ) { | |
289 | ramdisk_image = <initrd_address>; | |
290 | ramdisk_size = <initrd_size>; | |
291 | } | |
292 | if ( protocol >= 0x0201 ) { | |
293 | heap_end_ptr = 0x9000 - 0x200; | |
294 | loadflags |= 0x80; /* CAN_USE_HEAP */ | |
295 | } | |
296 | if ( protocol >= 0x0202 ) { | |
297 | cmd_line_ptr = base_ptr + 0x9000; | |
298 | } else { | |
299 | cmd_line_magic = 0xA33F; | |
300 | cmd_line_offset = 0x9000; | |
301 | setup_move_size = 0x9100; | |
302 | } | |
303 | } else { | |
304 | /* Very old kernel */ | |
305 | ||
306 | cmd_line_magic = 0xA33F; | |
307 | cmd_line_offset = 0x9000; | |
308 | ||
309 | /* A very old kernel MUST have its real-mode code | |
310 | loaded at 0x90000 */ | |
311 | ||
312 | if ( base_ptr != 0x90000 ) { | |
313 | /* Copy the real-mode kernel */ | |
314 | memcpy(0x90000, base_ptr, (setup_sects+1)*512); | |
315 | /* Copy the command line */ | |
316 | memcpy(0x99000, base_ptr+0x9000, 256); | |
317 | ||
318 | base_ptr = 0x90000; /* Relocated */ | |
319 | } | |
320 | ||
321 | /* It is recommended to clear memory up to the 32K mark */ | |
322 | memset(0x90000 + (setup_sects+1)*512, 0, | |
323 | (64-(setup_sects+1))*512); | |
324 | } | |
325 | ||
326 | ||
327 | **** LOADING THE REST OF THE KERNEL | |
328 | ||
f8eeaaf4 PA |
329 | The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 |
330 | in the kernel file (again, if setup_sects == 0 the real value is 4.) | |
331 | It should be loaded at address 0x10000 for Image/zImage kernels and | |
1da177e4 LT |
332 | 0x100000 for bzImage kernels. |
333 | ||
334 | The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 | |
335 | bit (LOAD_HIGH) in the loadflags field is set: | |
336 | ||
337 | is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01); | |
338 | load_address = is_bzImage ? 0x100000 : 0x10000; | |
339 | ||
340 | Note that Image/zImage kernels can be up to 512K in size, and thus use | |
341 | the entire 0x10000-0x90000 range of memory. This means it is pretty | |
342 | much a requirement for these kernels to load the real-mode part at | |
343 | 0x90000. bzImage kernels allow much more flexibility. | |
344 | ||
345 | ||
346 | **** SPECIAL COMMAND LINE OPTIONS | |
347 | ||
348 | If the command line provided by the boot loader is entered by the | |
349 | user, the user may expect the following command line options to work. | |
350 | They should normally not be deleted from the kernel command line even | |
351 | though not all of them are actually meaningful to the kernel. Boot | |
352 | loader authors who need additional command line options for the boot | |
353 | loader itself should get them registered in | |
354 | Documentation/kernel-parameters.txt to make sure they will not | |
355 | conflict with actual kernel options now or in the future. | |
356 | ||
357 | vga=<mode> | |
358 | <mode> here is either an integer (in C notation, either | |
359 | decimal, octal, or hexadecimal) or one of the strings | |
360 | "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask" | |
361 | (meaning 0xFFFD). This value should be entered into the | |
362 | vid_mode field, as it is used by the kernel before the command | |
363 | line is parsed. | |
364 | ||
365 | mem=<size> | |
366 | <size> is an integer in C notation optionally followed by K, M | |
367 | or G (meaning << 10, << 20 or << 30). This specifies the end | |
368 | of memory to the kernel. This affects the possible placement | |
369 | of an initrd, since an initrd should be placed near end of | |
370 | memory. Note that this is an option to *both* the kernel and | |
371 | the bootloader! | |
372 | ||
373 | initrd=<file> | |
374 | An initrd should be loaded. The meaning of <file> is | |
375 | obviously bootloader-dependent, and some boot loaders | |
376 | (e.g. LILO) do not have such a command. | |
377 | ||
378 | In addition, some boot loaders add the following options to the | |
379 | user-specified command line: | |
380 | ||
381 | BOOT_IMAGE=<file> | |
382 | The boot image which was loaded. Again, the meaning of <file> | |
383 | is obviously bootloader-dependent. | |
384 | ||
385 | auto | |
386 | The kernel was booted without explicit user intervention. | |
387 | ||
388 | If these options are added by the boot loader, it is highly | |
389 | recommended that they are located *first*, before the user-specified | |
390 | or configuration-specified command line. Otherwise, "init=/bin/sh" | |
391 | gets confused by the "auto" option. | |
392 | ||
393 | ||
394 | **** RUNNING THE KERNEL | |
395 | ||
396 | The kernel is started by jumping to the kernel entry point, which is | |
397 | located at *segment* offset 0x20 from the start of the real mode | |
398 | kernel. This means that if you loaded your real-mode kernel code at | |
399 | 0x90000, the kernel entry point is 9020:0000. | |
400 | ||
401 | At entry, ds = es = ss should point to the start of the real-mode | |
402 | kernel code (0x9000 if the code is loaded at 0x90000), sp should be | |
403 | set up properly, normally pointing to the top of the heap, and | |
404 | interrupts should be disabled. Furthermore, to guard against bugs in | |
405 | the kernel, it is recommended that the boot loader sets fs = gs = ds = | |
406 | es = ss. | |
407 | ||
408 | In our example from above, we would do: | |
409 | ||
410 | /* Note: in the case of the "old" kernel protocol, base_ptr must | |
411 | be == 0x90000 at this point; see the previous sample code */ | |
412 | ||
413 | seg = base_ptr >> 4; | |
414 | ||
415 | cli(); /* Enter with interrupts disabled! */ | |
416 | ||
417 | /* Set up the real-mode kernel stack */ | |
418 | _SS = seg; | |
419 | _SP = 0x9000; /* Load SP immediately after loading SS! */ | |
420 | ||
421 | _DS = _ES = _FS = _GS = seg; | |
422 | jmp_far(seg+0x20, 0); /* Run the kernel */ | |
423 | ||
424 | If your boot sector accesses a floppy drive, it is recommended to | |
425 | switch off the floppy motor before running the kernel, since the | |
426 | kernel boot leaves interrupts off and thus the motor will not be | |
427 | switched off, especially if the loaded kernel has the floppy driver as | |
428 | a demand-loaded module! | |
429 | ||
430 | ||
431 | **** ADVANCED BOOT TIME HOOKS | |
432 | ||
433 | If the boot loader runs in a particularly hostile environment (such as | |
434 | LOADLIN, which runs under DOS) it may be impossible to follow the | |
435 | standard memory location requirements. Such a boot loader may use the | |
436 | following hooks that, if set, are invoked by the kernel at the | |
437 | appropriate time. The use of these hooks should probably be | |
438 | considered an absolutely last resort! | |
439 | ||
440 | IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and | |
441 | %edi across invocation. | |
442 | ||
443 | realmode_swtch: | |
444 | A 16-bit real mode far subroutine invoked immediately before | |
445 | entering protected mode. The default routine disables NMI, so | |
446 | your routine should probably do so, too. | |
447 | ||
448 | code32_start: | |
449 | A 32-bit flat-mode routine *jumped* to immediately after the | |
450 | transition to protected mode, but before the kernel is | |
451 | uncompressed. No segments, except CS, are set up; you should | |
452 | set them up to KERNEL_DS (0x18) yourself. | |
453 | ||
454 | After completing your hook, you should jump to the address | |
455 | that was in this field before your boot loader overwrote it. |