A number of items in the i386 boot documentation have been either vague, outdated or hard to read. This text revision adds several more examples, including a memory map for a modern kernel load. It also adds a field-by-field detailed description of the setup header, and a bootloader ID for Qemu.
Unified · Split
| @@ -2,7 +2,7 @@ · 1 unmodified line | ||
| 2 | 2 | ---------------------------- |
| 3 | 3 | |
| 4 | 4 | H. Peter Anvin <hpa@zytor.com> |
| 5 | − Last update 2007-05-07 | |
| 5 | + Last update 2007-05-16 | |
| 6 | 6 | |
| 7 | 7 | On the i386 platform, the Linux kernel uses a rather complicated boot |
| 8 | 8 | convention. This has evolved partially due to historical aspects, as |
| @@ -52,7 +52,8 @@ zImage kernels, typically looks like: · 43 unmodified lines | ||
| 52 | 52 | 0A0000 +------------------------+ |
| 53 | 53 | | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. |
| 54 | 54 | 09A000 +------------------------+ |
| 55 | − | Stack/heap/cmdline | For use by the kernel real-mode code. | |
| 55 | + | Command line | | |
| 56 | + | Stack/heap | For use by the kernel real-mode code. | |
| 56 | 57 | 098000 +------------------------+ |
| 57 | 58 | | Kernel setup | The kernel real-mode code. |
| 58 | 59 | 090200 +------------------------+ |
| @@ -73,10 +74,9 @@ zImage kernels, typically looks like: · 14 unmodified lines | ||
| 73 | 74 | When using bzImage, the protected-mode kernel was relocated to |
| 74 | 75 | 0x100000 ("high memory"), and the kernel real-mode block (boot sector, |
| 75 | 76 | setup, and stack/heap) was made relocatable to any address between |
| 76 | −0x10000 and end of low memory. Unfortunately, in protocols 2.00 and | |
| 77 | −2.01 the command line is still required to live in the 0x9XXXX memory | |
| 78 | −range, and that memory range is still overwritten by the early kernel. | |
| 79 | −The 2.02 protocol resolves that problem. | |
| 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. | |
| 80 | 80 | |
| 81 | 81 | It is desirable to keep the "memory ceiling" -- the highest point in |
| 82 | 82 | low memory touched by the boot loader -- as low as possible, since |
| @@ -93,6 +93,35 @@ zImage or old bzImage kernels, which need data written into the · 10 unmodified lines | ||
| 93 | 93 | 0x90000 segment, the boot loader should make sure not to use memory |
| 94 | 94 | above the 0x9A000 point; too many BIOSes will break above that point. |
| 95 | 95 | |
| 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 | + | |
| 96 | 125 | |
| 97 | 126 | **** THE REAL-MODE KERNEL HEADER |
| 98 | 127 | |
| @@ -160,29 +189,136 @@ e.g. protocol version 2.01 will contain 0x0201 in this field. When · 61 unmodified lines | ||
| 160 | 189 | setting fields in the header, you must make sure only to set fields |
| 161 | 190 | supported by the protocol version in use. |
| 162 | 191 | |
| 163 | −The "kernel_version" field, if set to a nonzero value, contains a | |
| 164 | −pointer to a null-terminated human-readable kernel version number | |
| 165 | −string, less 0x200. This can be used to display the kernel version to | |
| 166 | −the user. This value should be less than (0x200*setup_sects). For | |
| 167 | −example, if this value is set to 0x1c00, the kernel version number | |
| 168 | −string can be found at offset 0x1e00 in the kernel file. This is a | |
| 169 | −valid value if and only if the "setup_sects" field contains the value | |
| 170 | −14 or higher. | |
| 171 | − | |
| 172 | −Most boot loaders will simply load the kernel at its target address | |
| 173 | −directly. Such boot loaders do not need to worry about filling in | |
| 174 | −most of the fields in the header. The following fields should be | |
| 175 | −filled out, however: | |
| 176 | − | |
| 177 | − vid_mode: | |
| 178 | − Please see the section on SPECIAL COMMAND LINE OPTIONS. | |
| 179 | − | |
| 180 | − type_of_loader: | |
| 181 | − If your boot loader has an assigned id (see table below), enter | |
| 182 | − 0xTV here, where T is an identifier for the boot loader and V is | |
| 183 | − a version number. Otherwise, enter 0xFF here. | |
| 184 | − | |
| 185 | − Assigned boot loader ids: | |
| 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: | |
| 186 | 322 | 0 LILO (0x00 reserved for pre-2.00 bootloader) |
| 187 | 323 | 1 Loadlin |
| 188 | 324 | 2 bootsect-loader (0x20, all other values reserved) |
| @@ -193,60 +329,145 @@ filled out, however: · 4 unmodified lines | ||
| 193 | 329 | 8 U-BOOT |
| 194 | 330 | 9 Xen |
| 195 | 331 | A Gujin |
| 332 | + B Qemu | |
| 196 | 333 | |
| 197 | − Please contact <hpa@zytor.com> if you need a bootloader ID | |
| 198 | − value assigned. | |
| 199 | − | |
| 200 | − loadflags, heap_end_ptr: | |
| 201 | − If the protocol version is 2.01 or higher, enter the | |
| 202 | − offset limit of the setup heap into heap_end_ptr and set the | |
| 203 | − 0x80 bit (CAN_USE_HEAP) of loadflags. heap_end_ptr appears to | |
| 204 | − be relative to the start of setup (offset 0x0200). | |
| 205 | − | |
| 206 | − setup_move_size: | |
| 207 | − When using protocol 2.00 or 2.01, if the real mode | |
| 208 | − kernel is not loaded at 0x90000, it gets moved there later in | |
| 209 | − the loading sequence. Fill in this field if you want | |
| 210 | − additional data (such as the kernel command line) moved in | |
| 211 | − addition to the real-mode kernel itself. | |
| 212 | − | |
| 213 | − The unit is bytes starting with the beginning of the boot | |
| 214 | − sector. | |
| 215 | − | |
| 216 | − ramdisk_image, ramdisk_size: | |
| 217 | − If your boot loader has loaded an initial ramdisk (initrd), | |
| 218 | − set ramdisk_image to the 32-bit pointer to the ramdisk data | |
| 219 | − and the ramdisk_size to the size of the ramdisk data. | |
| 220 | − | |
| 221 | − The initrd should typically be located as high in memory as | |
| 222 | − possible, as it may otherwise get overwritten by the early | |
| 223 | − kernel initialization sequence. However, it must never be | |
| 224 | − located above the address specified in the initrd_addr_max | |
| 225 | − field. The initrd should be at least 4K page aligned. | |
| 226 | − | |
| 227 | − cmd_line_ptr: | |
| 228 | − If the protocol version is 2.02 or higher, this is a 32-bit | |
| 229 | − pointer to the kernel command line. The kernel command line | |
| 230 | − can be located anywhere between the end of setup and 0xA0000. | |
| 231 | − Fill in this field even if your boot loader does not support a | |
| 232 | − command line, in which case you can point this to an empty | |
| 233 | − string (or better yet, to the string "auto".) If this field | |
| 234 | − is left at zero, the kernel will assume that your boot loader | |
| 235 | − does not support the 2.02+ protocol. | |
| 236 | − | |
| 237 | − ramdisk_max: | |
| 238 | − The maximum address that may be occupied by the initrd | |
| 239 | − contents. For boot protocols 2.02 or earlier, this field is | |
| 240 | − not present, and the maximum address is 0x37FFFFFF. (This | |
| 241 | − address is defined as the address of the highest safe byte, so | |
| 242 | − if your ramdisk is exactly 131072 bytes long and this field is | |
| 243 | − 0x37FFFFFF, you can start your ramdisk at 0x37FE0000.) | |
| 244 | − | |
| 245 | − cmdline_size: | |
| 246 | − The maximum size of the command line without the terminating | |
| 247 | − zero. This means that the command line can contain at most | |
| 248 | − cmdline_size characters. With protocol version 2.05 and | |
| 249 | − earlier, the maximum size was 255. | |
| 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. | |
| 250 | 471 | |
| 251 | 472 | |
| 252 | 473 | **** THE KERNEL COMMAND LINE |