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