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