1.. SPDX-License-Identifier: GPL-2.0 2 3=========================== 4The Linux/x86 Boot Protocol 5=========================== 6 7On the x86 platform, the Linux kernel uses a rather complicated boot 8convention. This has evolved partially due to historical aspects, as 9well as the desire in the early days to have the kernel itself be a 10bootable image, the complicated PC memory model and due to changed 11expectations in the PC industry caused by the effective demise of 12real-mode DOS as a mainstream operating system. 13 14Currently, the following versions of the Linux/x86 boot protocol exist. 15 16============= ============================================================ 17Old kernels zImage/Image support only. Some very early kernels 18 may not even support a command line. 19 20Protocol 2.00 (Kernel 1.3.73) Added bzImage and initrd support, as 21 well as a formalized way to communicate between the 22 boot loader and the kernel. setup.S made relocatable, 23 although the traditional setup area still assumed 24 writable. 25 26Protocol 2.01 (Kernel 1.3.76) Added a heap overrun warning. 27 28Protocol 2.02 (Kernel 2.4.0-test3-pre3) New command line protocol. 29 Lower the conventional memory ceiling. No overwrite 30 of the traditional setup area, thus making booting 31 safe for systems which use the EBDA from SMM or 32-bit 32 BIOS entry points. zImage deprecated but still 33 supported. 34 35Protocol 2.03 (Kernel 2.4.18-pre1) Explicitly makes the highest possible 36 initrd address available to the bootloader. 37 38Protocol 2.04 (Kernel 2.6.14) Extend the syssize field to four bytes. 39 40Protocol 2.05 (Kernel 2.6.20) Make protected mode kernel relocatable. 41 Introduce relocatable_kernel and kernel_alignment fields. 42 43Protocol 2.06 (Kernel 2.6.22) Added a field that contains the size of 44 the boot command line. 45 46Protocol 2.07 (Kernel 2.6.24) Added paravirtualised boot protocol. 47 Introduced hardware_subarch and hardware_subarch_data 48 and KEEP_SEGMENTS flag in load_flags. 49 50Protocol 2.08 (Kernel 2.6.26) Added crc32 checksum and ELF format 51 payload. Introduced payload_offset and payload_length 52 fields to aid in locating the payload. 53 54Protocol 2.09 (Kernel 2.6.26) Added a field of 64-bit physical 55 pointer to single linked list of struct setup_data. 56 57Protocol 2.10 (Kernel 2.6.31) Added a protocol for relaxed alignment 58 beyond the kernel_alignment added, new init_size and 59 pref_address fields. Added extended boot loader IDs. 60 61Protocol 2.11 (Kernel 3.6) Added a field for offset of EFI handover 62 protocol entry point. 63 64Protocol 2.12 (Kernel 3.8) Added the xloadflags field and extension fields 65 to struct boot_params for loading bzImage and ramdisk 66 above 4G in 64bit. 67 68Protocol 2.13 (Kernel 3.14) Support 32- and 64-bit flags being set in 69 xloadflags to support booting a 64-bit kernel from 32-bit 70 EFI 71============= ============================================================ 72 73 74Memory Layout 75============= 76 77The traditional memory map for the kernel loader, used for Image or 78zImage kernels, typically looks like:: 79 80 | | 81 0A0000 +------------------------+ 82 | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. 83 09A000 +------------------------+ 84 | Command line | 85 | Stack/heap | For use by the kernel real-mode code. 86 098000 +------------------------+ 87 | Kernel setup | The kernel real-mode code. 88 090200 +------------------------+ 89 | Kernel boot sector | The kernel legacy boot sector. 90 090000 +------------------------+ 91 | Protected-mode kernel | The bulk of the kernel image. 92 010000 +------------------------+ 93 | Boot loader | <- Boot sector entry point 0000:7C00 94 001000 +------------------------+ 95 | Reserved for MBR/BIOS | 96 000800 +------------------------+ 97 | Typically used by MBR | 98 000600 +------------------------+ 99 | BIOS use only | 100 000000 +------------------------+ 101 102When using bzImage, the protected-mode kernel was relocated to 1030x100000 ("high memory"), and the kernel real-mode block (boot sector, 104setup, and stack/heap) was made relocatable to any address between 1050x10000 and end of low memory. Unfortunately, in protocols 2.00 and 1062.01 the 0x90000+ memory range is still used internally by the kernel; 107the 2.02 protocol resolves that problem. 108 109It is desirable to keep the "memory ceiling" -- the highest point in 110low memory touched by the boot loader -- as low as possible, since 111some newer BIOSes have begun to allocate some rather large amounts of 112memory, called the Extended BIOS Data Area, near the top of low 113memory. The boot loader should use the "INT 12h" BIOS call to verify 114how much low memory is available. 115 116Unfortunately, if INT 12h reports that the amount of memory is too 117low, there is usually nothing the boot loader can do but to report an 118error to the user. The boot loader should therefore be designed to 119take up as little space in low memory as it reasonably can. For 120zImage or old bzImage kernels, which need data written into the 1210x90000 segment, the boot loader should make sure not to use memory 122above the 0x9A000 point; too many BIOSes will break above that point. 123 124For a modern bzImage kernel with boot protocol version >= 2.02, a 125memory layout like the following is suggested:: 126 127 ~ ~ 128 | Protected-mode kernel | 129 100000 +------------------------+ 130 | I/O memory hole | 131 0A0000 +------------------------+ 132 | Reserved for BIOS | Leave as much as possible unused 133 ~ ~ 134 | Command line | (Can also be below the X+10000 mark) 135 X+10000 +------------------------+ 136 | Stack/heap | For use by the kernel real-mode code. 137 X+08000 +------------------------+ 138 | Kernel setup | The kernel real-mode code. 139 | Kernel boot sector | The kernel legacy boot sector. 140 X +------------------------+ 141 | Boot loader | <- Boot sector entry point 0000:7C00 142 001000 +------------------------+ 143 | Reserved for MBR/BIOS | 144 000800 +------------------------+ 145 | Typically used by MBR | 146 000600 +------------------------+ 147 | BIOS use only | 148 000000 +------------------------+ 149 150 ... where the address X is as low as the design of the boot loader permits. 151 152 153The Real-Mode Kernel Header 154=========================== 155 156In the following text, and anywhere in the kernel boot sequence, "a 157sector" refers to 512 bytes. It is independent of the actual sector 158size of the underlying medium. 159 160The first step in loading a Linux kernel should be to load the 161real-mode code (boot sector and setup code) and then examine the 162following header at offset 0x01f1. The real-mode code can total up to 16332K, although the boot loader may choose to load only the first two 164sectors (1K) and then examine the bootup sector size. 165 166The header looks like: 167 168=========== ======== ===================== ============================================ 169Offset/Size Proto Name Meaning 170=========== ======== ===================== ============================================ 17101F1/1 ALL(1) setup_sects The size of the setup in sectors 17201F2/2 ALL root_flags If set, the root is mounted readonly 17301F4/4 2.04+(2) syssize The size of the 32-bit code in 16-byte paras 17401F8/2 ALL ram_size DO NOT USE - for bootsect.S use only 17501FA/2 ALL vid_mode Video mode control 17601FC/2 ALL root_dev Default root device number 17701FE/2 ALL boot_flag 0xAA55 magic number 1780200/2 2.00+ jump Jump instruction 1790202/4 2.00+ header Magic signature "HdrS" 1800206/2 2.00+ version Boot protocol version supported 1810208/4 2.00+ realmode_swtch Boot loader hook (see below) 182020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete) 183020E/2 2.00+ kernel_version Pointer to kernel version string 1840210/1 2.00+ type_of_loader Boot loader identifier 1850211/1 2.00+ loadflags Boot protocol option flags 1860212/2 2.00+ setup_move_size Move to high memory size (used with hooks) 1870214/4 2.00+ code32_start Boot loader hook (see below) 1880218/4 2.00+ ramdisk_image initrd load address (set by boot loader) 189021C/4 2.00+ ramdisk_size initrd size (set by boot loader) 1900220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only 1910224/2 2.01+ heap_end_ptr Free memory after setup end 1920226/1 2.02+(3) ext_loader_ver Extended boot loader version 1930227/1 2.02+(3) ext_loader_type Extended boot loader ID 1940228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line 195022C/4 2.03+ initrd_addr_max Highest legal initrd address 1960230/4 2.05+ kernel_alignment Physical addr alignment required for kernel 1970234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not 1980235/1 2.10+ min_alignment Minimum alignment, as a power of two 1990236/2 2.12+ xloadflags Boot protocol option flags 2000238/4 2.06+ cmdline_size Maximum size of the kernel command line 201023C/4 2.07+ hardware_subarch Hardware subarchitecture 2020240/8 2.07+ hardware_subarch_data Subarchitecture-specific data 2030248/4 2.08+ payload_offset Offset of kernel payload 204024C/4 2.08+ payload_length Length of kernel payload 2050250/8 2.09+ setup_data 64-bit physical pointer to linked list 206 of struct setup_data 2070258/8 2.10+ pref_address Preferred loading address 2080260/4 2.10+ init_size Linear memory required during initialization 2090264/4 2.11+ handover_offset Offset of handover entry point 210=========== ======== ===================== ============================================ 211 212.. note:: 213 (1) For backwards compatibility, if the setup_sects field contains 0, the 214 real value is 4. 215 216 (2) For boot protocol prior to 2.04, the upper two bytes of the syssize 217 field are unusable, which means the size of a bzImage kernel 218 cannot be determined. 219 220 (3) Ignored, but safe to set, for boot protocols 2.02-2.09. 221 222If the "HdrS" (0x53726448) magic number is not found at offset 0x202, 223the boot protocol version is "old". Loading an old kernel, the 224following parameters should be assumed:: 225 226 Image type = zImage 227 initrd not supported 228 Real-mode kernel must be located at 0x90000. 229 230Otherwise, the "version" field contains the protocol version, 231e.g. protocol version 2.01 will contain 0x0201 in this field. When 232setting fields in the header, you must make sure only to set fields 233supported by the protocol version in use. 234 235 236Details of Harder Fileds 237======================== 238 239For each field, some are information from the kernel to the bootloader 240("read"), some are expected to be filled out by the bootloader 241("write"), and some are expected to be read and modified by the 242bootloader ("modify"). 243 244All general purpose boot loaders should write the fields marked 245(obligatory). Boot loaders who want to load the kernel at a 246nonstandard address should fill in the fields marked (reloc); other 247boot loaders can ignore those fields. 248 249The byte order of all fields is littleendian (this is x86, after all.) 250 251============ =========== 252Field name: setup_sects 253Type: read 254Offset/size: 0x1f1/1 255Protocol: ALL 256============ =========== 257 258 The size of the setup code in 512-byte sectors. If this field is 259 0, the real value is 4. The real-mode code consists of the boot 260 sector (always one 512-byte sector) plus the setup code. 261 262============ ================= 263Field name: root_flags 264Type: modify (optional) 265Offset/size: 0x1f2/2 266Protocol: ALL 267============ ================= 268 269 If this field is nonzero, the root defaults to readonly. The use of 270 this field is deprecated; use the "ro" or "rw" options on the 271 command line instead. 272 273============ =============================================== 274Field name: syssize 275Type: read 276Offset/size: 0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL) 277Protocol: 2.04+ 278============ =============================================== 279 280 The size of the protected-mode code in units of 16-byte paragraphs. 281 For protocol versions older than 2.04 this field is only two bytes 282 wide, and therefore cannot be trusted for the size of a kernel if 283 the LOAD_HIGH flag is set. 284 285============ =============== 286Field name: ram_size 287Type: kernel internal 288Offset/size: 0x1f8/2 289Protocol: ALL 290============ =============== 291 292 This field is obsolete. 293 294============ =================== 295Field name: vid_mode 296Type: modify (obligatory) 297Offset/size: 0x1fa/2 298============ =================== 299 300 Please see the section on SPECIAL COMMAND LINE OPTIONS. 301 302============ ================= 303Field name: root_dev 304Type: modify (optional) 305Offset/size: 0x1fc/2 306Protocol: ALL 307============ ================= 308 309 The default root device device number. The use of this field is 310 deprecated, use the "root=" option on the command line instead. 311 312============ ========= 313Field name: boot_flag 314Type: read 315Offset/size: 0x1fe/2 316Protocol: ALL 317============ ========= 318 319 Contains 0xAA55. This is the closest thing old Linux kernels have 320 to a magic number. 321 322============ ======= 323Field name: jump 324Type: read 325Offset/size: 0x200/2 326Protocol: 2.00+ 327============ ======= 328 329 Contains an x86 jump instruction, 0xEB followed by a signed offset 330 relative to byte 0x202. This can be used to determine the size of 331 the header. 332 333============ ======= 334Field name: header 335Type: read 336Offset/size: 0x202/4 337Protocol: 2.00+ 338============ ======= 339 340 Contains the magic number "HdrS" (0x53726448). 341 342============ ======= 343Field name: version 344Type: read 345Offset/size: 0x206/2 346Protocol: 2.00+ 347============ ======= 348 349 Contains the boot protocol version, in (major << 8)+minor format, 350 e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version 351 10.17. 352 353============ ================= 354Field name: realmode_swtch 355Type: modify (optional) 356Offset/size: 0x208/4 357Protocol: 2.00+ 358============ ================= 359 360 Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.) 361 362============ ============= 363Field name: start_sys_seg 364Type: read 365Offset/size: 0x20c/2 366Protocol: 2.00+ 367============ ============= 368 369 The load low segment (0x1000). Obsolete. 370 371============ ============== 372Field name: kernel_version 373Type: read 374Offset/size: 0x20e/2 375Protocol: 2.00+ 376============ ============== 377 378 If set to a nonzero value, contains a pointer to a NUL-terminated 379 human-readable kernel version number string, less 0x200. This can 380 be used to display the kernel version to the user. This value 381 should be less than (0x200*setup_sects). 382 383 For example, if this value is set to 0x1c00, the kernel version 384 number string can be found at offset 0x1e00 in the kernel file. 385 This is a valid value if and only if the "setup_sects" field 386 contains the value 15 or higher, as:: 387 388 0x1c00 < 15*0x200 (= 0x1e00) but 389 0x1c00 >= 14*0x200 (= 0x1c00) 390 391 0x1c00 >> 9 = 14, So the minimum value for setup_secs is 15. 392 393============ ================== 394Field name: type_of_loader 395Type: write (obligatory) 396Offset/size: 0x210/1 397Protocol: 2.00+ 398============ ================== 399 400 If your boot loader has an assigned id (see table below), enter 401 0xTV here, where T is an identifier for the boot loader and V is 402 a version number. Otherwise, enter 0xFF here. 403 404 For boot loader IDs above T = 0xD, write T = 0xE to this field and 405 write the extended ID minus 0x10 to the ext_loader_type field. 406 Similarly, the ext_loader_ver field can be used to provide more than 407 four bits for the bootloader version. 408 409 For example, for T = 0x15, V = 0x234, write:: 410 411 type_of_loader <- 0xE4 412 ext_loader_type <- 0x05 413 ext_loader_ver <- 0x23 414 415 Assigned boot loader ids (hexadecimal): 416 417 == ======================================= 418 0 LILO 419 (0x00 reserved for pre-2.00 bootloader) 420 1 Loadlin 421 2 bootsect-loader 422 (0x20, all other values reserved) 423 3 Syslinux 424 4 Etherboot/gPXE/iPXE 425 5 ELILO 426 7 GRUB 427 8 U-Boot 428 9 Xen 429 A Gujin 430 B Qemu 431 C Arcturus Networks uCbootloader 432 D kexec-tools 433 E Extended (see ext_loader_type) 434 F Special (0xFF = undefined) 435 10 Reserved 436 11 Minimal Linux Bootloader 437 <http://sebastian-plotz.blogspot.de> 438 12 OVMF UEFI virtualization stack 439 == ======================================= 440 441 Please contact <hpa@zytor.com> if you need a bootloader ID value assigned. 442 443============ =================== 444Field name: loadflags 445Type: modify (obligatory) 446Offset/size: 0x211/1 447Protocol: 2.00+ 448============ =================== 449 450 This field is a bitmask. 451 452 Bit 0 (read): LOADED_HIGH 453 454 - If 0, the protected-mode code is loaded at 0x10000. 455 - If 1, the protected-mode code is loaded at 0x100000. 456 457 Bit 1 (kernel internal): KASLR_FLAG 458 459 - Used internally by the compressed kernel to communicate 460 KASLR status to kernel proper. 461 462 - If 1, KASLR enabled. 463 - If 0, KASLR disabled. 464 465 Bit 5 (write): QUIET_FLAG 466 467 - If 0, print early messages. 468 - If 1, suppress early messages. 469 470 This requests to the kernel (decompressor and early 471 kernel) to not write early messages that require 472 accessing the display hardware directly. 473 474 Bit 6 (write): KEEP_SEGMENTS 475 476 Protocol: 2.07+ 477 478 - If 0, reload the segment registers in the 32bit entry point. 479 - If 1, do not reload the segment registers in the 32bit entry point. 480 481 Assume that %cs %ds %ss %es are all set to flat segments with 482 a base of 0 (or the equivalent for their environment). 483 484 Bit 7 (write): CAN_USE_HEAP 485 486 Set this bit to 1 to indicate that the value entered in the 487 heap_end_ptr is valid. If this field is clear, some setup code 488 functionality will be disabled. 489 490 491============ =================== 492Field name: setup_move_size 493Type: modify (obligatory) 494Offset/size: 0x212/2 495Protocol: 2.00-2.01 496============ =================== 497 498 When using protocol 2.00 or 2.01, if the real mode kernel is not 499 loaded at 0x90000, it gets moved there later in the loading 500 sequence. Fill in this field if you want additional data (such as 501 the kernel command line) moved in addition to the real-mode kernel 502 itself. 503 504 The unit is bytes starting with the beginning of the boot sector. 505 506 This field is can be ignored when the protocol is 2.02 or higher, or 507 if the real-mode code is loaded at 0x90000. 508 509============ ======================== 510Field name: code32_start 511Type: modify (optional, reloc) 512Offset/size: 0x214/4 513Protocol: 2.00+ 514============ ======================== 515 516 The address to jump to in protected mode. This defaults to the load 517 address of the kernel, and can be used by the boot loader to 518 determine the proper load address. 519 520 This field can be modified for two purposes: 521 522 1. as a boot loader hook (see Advanced Boot Loader Hooks below.) 523 524 2. if a bootloader which does not install a hook loads a 525 relocatable kernel at a nonstandard address it will have to modify 526 this field to point to the load address. 527 528============ ================== 529Field name: ramdisk_image 530Type: write (obligatory) 531Offset/size: 0x218/4 532Protocol: 2.00+ 533============ ================== 534 535 The 32-bit linear address of the initial ramdisk or ramfs. Leave at 536 zero if there is no initial ramdisk/ramfs. 537 538============ ================== 539Field name: ramdisk_size 540Type: write (obligatory) 541Offset/size: 0x21c/4 542Protocol: 2.00+ 543============ ================== 544 545 Size of the initial ramdisk or ramfs. Leave at zero if there is no 546 initial ramdisk/ramfs. 547 548============ =============== 549Field name: bootsect_kludge 550Type: kernel internal 551Offset/size: 0x220/4 552Protocol: 2.00+ 553============ =============== 554 555 This field is obsolete. 556 557============ ================== 558Field name: heap_end_ptr 559Type: write (obligatory) 560Offset/size: 0x224/2 561Protocol: 2.01+ 562============ ================== 563 564 Set this field to the offset (from the beginning of the real-mode 565 code) of the end of the setup stack/heap, minus 0x0200. 566 567============ ================ 568Field name: ext_loader_ver 569Type: write (optional) 570Offset/size: 0x226/1 571Protocol: 2.02+ 572============ ================ 573 574 This field is used as an extension of the version number in the 575 type_of_loader field. The total version number is considered to be 576 (type_of_loader & 0x0f) + (ext_loader_ver << 4). 577 578 The use of this field is boot loader specific. If not written, it 579 is zero. 580 581 Kernels prior to 2.6.31 did not recognize this field, but it is safe 582 to write for protocol version 2.02 or higher. 583 584============ ===================================================== 585Field name: ext_loader_type 586Type: write (obligatory if (type_of_loader & 0xf0) == 0xe0) 587Offset/size: 0x227/1 588Protocol: 2.02+ 589============ ===================================================== 590 591 This field is used as an extension of the type number in 592 type_of_loader field. If the type in type_of_loader is 0xE, then 593 the actual type is (ext_loader_type + 0x10). 594 595 This field is ignored if the type in type_of_loader is not 0xE. 596 597 Kernels prior to 2.6.31 did not recognize this field, but it is safe 598 to write for protocol version 2.02 or higher. 599 600============ ================== 601Field name: cmd_line_ptr 602Type: write (obligatory) 603Offset/size: 0x228/4 604Protocol: 2.02+ 605============ ================== 606 607 Set this field to the linear address of the kernel command line. 608 The kernel command line can be located anywhere between the end of 609 the setup heap and 0xA0000; it does not have to be located in the 610 same 64K segment as the real-mode code itself. 611 612 Fill in this field even if your boot loader does not support a 613 command line, in which case you can point this to an empty string 614 (or better yet, to the string "auto".) If this field is left at 615 zero, the kernel will assume that your boot loader does not support 616 the 2.02+ protocol. 617 618============ =============== 619Field name: initrd_addr_max 620Type: read 621Offset/size: 0x22c/4 622Protocol: 2.03+ 623============ =============== 624 625 The maximum address that may be occupied by the initial 626 ramdisk/ramfs contents. For boot protocols 2.02 or earlier, this 627 field is not present, and the maximum address is 0x37FFFFFF. (This 628 address is defined as the address of the highest safe byte, so if 629 your ramdisk is exactly 131072 bytes long and this field is 630 0x37FFFFFF, you can start your ramdisk at 0x37FE0000.) 631 632============ ============================ 633Field name: kernel_alignment 634Type: read/modify (reloc) 635Offset/size: 0x230/4 636Protocol: 2.05+ (read), 2.10+ (modify) 637============ ============================ 638 639 Alignment unit required by the kernel (if relocatable_kernel is 640 true.) A relocatable kernel that is loaded at an alignment 641 incompatible with the value in this field will be realigned during 642 kernel initialization. 643 644 Starting with protocol version 2.10, this reflects the kernel 645 alignment preferred for optimal performance; it is possible for the 646 loader to modify this field to permit a lesser alignment. See the 647 min_alignment and pref_address field below. 648 649============ ================== 650Field name: relocatable_kernel 651Type: read (reloc) 652Offset/size: 0x234/1 653Protocol: 2.05+ 654============ ================== 655 656 If this field is nonzero, the protected-mode part of the kernel can 657 be loaded at any address that satisfies the kernel_alignment field. 658 After loading, the boot loader must set the code32_start field to 659 point to the loaded code, or to a boot loader hook. 660 661============ ============= 662Field name: min_alignment 663Type: read (reloc) 664Offset/size: 0x235/1 665Protocol: 2.10+ 666============ ============= 667 668 This field, if nonzero, indicates as a power of two the minimum 669 alignment required, as opposed to preferred, by the kernel to boot. 670 If a boot loader makes use of this field, it should update the 671 kernel_alignment field with the alignment unit desired; typically:: 672 673 kernel_alignment = 1 << min_alignment 674 675 There may be a considerable performance cost with an excessively 676 misaligned kernel. Therefore, a loader should typically try each 677 power-of-two alignment from kernel_alignment down to this alignment. 678 679============ ========== 680Field name: xloadflags 681Type: read 682Offset/size: 0x236/2 683Protocol: 2.12+ 684============ ========== 685 686 This field is a bitmask. 687 688 Bit 0 (read): XLF_KERNEL_64 689 690 - If 1, this kernel has the legacy 64-bit entry point at 0x200. 691 692 Bit 1 (read): XLF_CAN_BE_LOADED_ABOVE_4G 693 694 - If 1, kernel/boot_params/cmdline/ramdisk can be above 4G. 695 696 Bit 2 (read): XLF_EFI_HANDOVER_32 697 698 - If 1, the kernel supports the 32-bit EFI handoff entry point 699 given at handover_offset. 700 701 Bit 3 (read): XLF_EFI_HANDOVER_64 702 703 - If 1, the kernel supports the 64-bit EFI handoff entry point 704 given at handover_offset + 0x200. 705 706 Bit 4 (read): XLF_EFI_KEXEC 707 708 - If 1, the kernel supports kexec EFI boot with EFI runtime support. 709 710 711============ ============ 712Field name: cmdline_size 713Type: read 714Offset/size: 0x238/4 715Protocol: 2.06+ 716============ ============ 717 718 The maximum size of the command line without the terminating 719 zero. This means that the command line can contain at most 720 cmdline_size characters. With protocol version 2.05 and earlier, the 721 maximum size was 255. 722 723============ ==================================== 724Field name: hardware_subarch 725Type: write (optional, defaults to x86/PC) 726Offset/size: 0x23c/4 727Protocol: 2.07+ 728============ ==================================== 729 730 In a paravirtualized environment the hardware low level architectural 731 pieces such as interrupt handling, page table handling, and 732 accessing process control registers needs to be done differently. 733 734 This field allows the bootloader to inform the kernel we are in one 735 one of those environments. 736 737 ========== ============================== 738 0x00000000 The default x86/PC environment 739 0x00000001 lguest 740 0x00000002 Xen 741 0x00000003 Moorestown MID 742 0x00000004 CE4100 TV Platform 743 ========== ============================== 744 745============ ========================= 746Field name: hardware_subarch_data 747Type: write (subarch-dependent) 748Offset/size: 0x240/8 749Protocol: 2.07+ 750============ ========================= 751 752 A pointer to data that is specific to hardware subarch 753 This field is currently unused for the default x86/PC environment, 754 do not modify. 755 756============ ============== 757Field name: payload_offset 758Type: read 759Offset/size: 0x248/4 760Protocol: 2.08+ 761============ ============== 762 763 If non-zero then this field contains the offset from the beginning 764 of the protected-mode code to the payload. 765 766 The payload may be compressed. The format of both the compressed and 767 uncompressed data should be determined using the standard magic 768 numbers. The currently supported compression formats are gzip 769 (magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A), LZMA 770 (magic number 5D 00), XZ (magic number FD 37), and LZ4 (magic number 771 02 21). The uncompressed payload is currently always ELF (magic 772 number 7F 45 4C 46). 773 774============ ============== 775Field name: payload_length 776Type: read 777Offset/size: 0x24c/4 778Protocol: 2.08+ 779============ ============== 780 781 The length of the payload. 782 783============ =============== 784Field name: setup_data 785Type: write (special) 786Offset/size: 0x250/8 787Protocol: 2.09+ 788============ =============== 789 790 The 64-bit physical pointer to NULL terminated single linked list of 791 struct setup_data. This is used to define a more extensible boot 792 parameters passing mechanism. The definition of struct setup_data is 793 as follow:: 794 795 struct setup_data { 796 u64 next; 797 u32 type; 798 u32 len; 799 u8 data[0]; 800 }; 801 802 Where, the next is a 64-bit physical pointer to the next node of 803 linked list, the next field of the last node is 0; the type is used 804 to identify the contents of data; the len is the length of data 805 field; the data holds the real payload. 806 807 This list may be modified at a number of points during the bootup 808 process. Therefore, when modifying this list one should always make 809 sure to consider the case where the linked list already contains 810 entries. 811 812============ ============ 813Field name: pref_address 814Type: read (reloc) 815Offset/size: 0x258/8 816Protocol: 2.10+ 817============ ============ 818 819 This field, if nonzero, represents a preferred load address for the 820 kernel. A relocating bootloader should attempt to load at this 821 address if possible. 822 823 A non-relocatable kernel will unconditionally move itself and to run 824 at this address. 825 826============ ======= 827Field name: init_size 828Type: read 829Offset/size: 0x260/4 830============ ======= 831 832 This field indicates the amount of linear contiguous memory starting 833 at the kernel runtime start address that the kernel needs before it 834 is capable of examining its memory map. This is not the same thing 835 as the total amount of memory the kernel needs to boot, but it can 836 be used by a relocating boot loader to help select a safe load 837 address for the kernel. 838 839 The kernel runtime start address is determined by the following algorithm:: 840 841 if (relocatable_kernel) 842 runtime_start = align_up(load_address, kernel_alignment) 843 else 844 runtime_start = pref_address 845 846============ =============== 847Field name: handover_offset 848Type: read 849Offset/size: 0x264/4 850============ =============== 851 852 This field is the offset from the beginning of the kernel image to 853 the EFI handover protocol entry point. Boot loaders using the EFI 854 handover protocol to boot the kernel should jump to this offset. 855 856 See EFI HANDOVER PROTOCOL below for more details. 857 858 859The Image Checksum 860================== 861 862From boot protocol version 2.08 onwards the CRC-32 is calculated over 863the entire file using the characteristic polynomial 0x04C11DB7 and an 864initial remainder of 0xffffffff. The checksum is appended to the 865file; therefore the CRC of the file up to the limit specified in the 866syssize field of the header is always 0. 867 868 869The Kernel Command Line 870======================= 871 872The kernel command line has become an important way for the boot 873loader to communicate with the kernel. Some of its options are also 874relevant to the boot loader itself, see "special command line options" 875below. 876 877The kernel command line is a null-terminated string. The maximum 878length can be retrieved from the field cmdline_size. Before protocol 879version 2.06, the maximum was 255 characters. A string that is too 880long will be automatically truncated by the kernel. 881 882If the boot protocol version is 2.02 or later, the address of the 883kernel command line is given by the header field cmd_line_ptr (see 884above.) This address can be anywhere between the end of the setup 885heap and 0xA0000. 886 887If the protocol version is *not* 2.02 or higher, the kernel 888command line is entered using the following protocol: 889 890 - At offset 0x0020 (word), "cmd_line_magic", enter the magic 891 number 0xA33F. 892 893 - At offset 0x0022 (word), "cmd_line_offset", enter the offset 894 of the kernel command line (relative to the start of the 895 real-mode kernel). 896 897 - The kernel command line *must* be within the memory region 898 covered by setup_move_size, so you may need to adjust this 899 field. 900 901 902Memory Layout of The Real-Mode Code 903=================================== 904 905The real-mode code requires a stack/heap to be set up, as well as 906memory allocated for the kernel command line. This needs to be done 907in the real-mode accessible memory in bottom megabyte. 908 909It should be noted that modern machines often have a sizable Extended 910BIOS Data Area (EBDA). As a result, it is advisable to use as little 911of the low megabyte as possible. 912 913Unfortunately, under the following circumstances the 0x90000 memory 914segment has to be used: 915 916 - When loading a zImage kernel ((loadflags & 0x01) == 0). 917 - When loading a 2.01 or earlier boot protocol kernel. 918 919.. note:: 920 For the 2.00 and 2.01 boot protocols, the real-mode code 921 can be loaded at another address, but it is internally 922 relocated to 0x90000. For the "old" protocol, the 923 real-mode code must be loaded at 0x90000. 924 925When loading at 0x90000, avoid using memory above 0x9a000. 926 927For boot protocol 2.02 or higher, the command line does not have to be 928located in the same 64K segment as the real-mode setup code; it is 929thus permitted to give the stack/heap the full 64K segment and locate 930the command line above it. 931 932The kernel command line should not be located below the real-mode 933code, nor should it be located in high memory. 934 935 936Sample Boot Configuartion 937========================= 938 939As a sample configuration, assume the following layout of the real 940mode segment. 941 942 When loading below 0x90000, use the entire segment: 943 944 ============= =================== 945 0x0000-0x7fff Real mode kernel 946 0x8000-0xdfff Stack and heap 947 0xe000-0xffff Kernel command line 948 ============= =================== 949 950 When loading at 0x90000 OR the protocol version is 2.01 or earlier: 951 952 ============= =================== 953 0x0000-0x7fff Real mode kernel 954 0x8000-0x97ff Stack and heap 955 0x9800-0x9fff Kernel command line 956 ============= =================== 957 958Such a boot loader should enter the following fields in the header:: 959 960 unsigned long base_ptr; /* base address for real-mode segment */ 961 962 if ( setup_sects == 0 ) { 963 setup_sects = 4; 964 } 965 966 if ( protocol >= 0x0200 ) { 967 type_of_loader = <type code>; 968 if ( loading_initrd ) { 969 ramdisk_image = <initrd_address>; 970 ramdisk_size = <initrd_size>; 971 } 972 973 if ( protocol >= 0x0202 && loadflags & 0x01 ) 974 heap_end = 0xe000; 975 else 976 heap_end = 0x9800; 977 978 if ( protocol >= 0x0201 ) { 979 heap_end_ptr = heap_end - 0x200; 980 loadflags |= 0x80; /* CAN_USE_HEAP */ 981 } 982 983 if ( protocol >= 0x0202 ) { 984 cmd_line_ptr = base_ptr + heap_end; 985 strcpy(cmd_line_ptr, cmdline); 986 } else { 987 cmd_line_magic = 0xA33F; 988 cmd_line_offset = heap_end; 989 setup_move_size = heap_end + strlen(cmdline)+1; 990 strcpy(base_ptr+cmd_line_offset, cmdline); 991 } 992 } else { 993 /* Very old kernel */ 994 995 heap_end = 0x9800; 996 997 cmd_line_magic = 0xA33F; 998 cmd_line_offset = heap_end; 999 1000 /* A very old kernel MUST have its real-mode code 1001 loaded at 0x90000 */ 1002 1003 if ( base_ptr != 0x90000 ) { 1004 /* Copy the real-mode kernel */ 1005 memcpy(0x90000, base_ptr, (setup_sects+1)*512); 1006 base_ptr = 0x90000; /* Relocated */ 1007 } 1008 1009 strcpy(0x90000+cmd_line_offset, cmdline); 1010 1011 /* It is recommended to clear memory up to the 32K mark */ 1012 memset(0x90000 + (setup_sects+1)*512, 0, 1013 (64-(setup_sects+1))*512); 1014 } 1015 1016 1017Loading The Rest of The Kernel 1018============================== 1019 1020The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 1021in the kernel file (again, if setup_sects == 0 the real value is 4.) 1022It should be loaded at address 0x10000 for Image/zImage kernels and 10230x100000 for bzImage kernels. 1024 1025The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 1026bit (LOAD_HIGH) in the loadflags field is set:: 1027 1028 is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01); 1029 load_address = is_bzImage ? 0x100000 : 0x10000; 1030 1031Note that Image/zImage kernels can be up to 512K in size, and thus use 1032the entire 0x10000-0x90000 range of memory. This means it is pretty 1033much a requirement for these kernels to load the real-mode part at 10340x90000. bzImage kernels allow much more flexibility. 1035 1036Special Command Line Options 1037============================ 1038 1039If the command line provided by the boot loader is entered by the 1040user, the user may expect the following command line options to work. 1041They should normally not be deleted from the kernel command line even 1042though not all of them are actually meaningful to the kernel. Boot 1043loader authors who need additional command line options for the boot 1044loader itself should get them registered in 1045Documentation/admin-guide/kernel-parameters.rst to make sure they will not 1046conflict with actual kernel options now or in the future. 1047 1048 vga=<mode> 1049 <mode> here is either an integer (in C notation, either 1050 decimal, octal, or hexadecimal) or one of the strings 1051 "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask" 1052 (meaning 0xFFFD). This value should be entered into the 1053 vid_mode field, as it is used by the kernel before the command 1054 line is parsed. 1055 1056 mem=<size> 1057 <size> is an integer in C notation optionally followed by 1058 (case insensitive) K, M, G, T, P or E (meaning << 10, << 20, 1059 << 30, << 40, << 50 or << 60). This specifies the end of 1060 memory to the kernel. This affects the possible placement of 1061 an initrd, since an initrd should be placed near end of 1062 memory. Note that this is an option to *both* the kernel and 1063 the bootloader! 1064 1065 initrd=<file> 1066 An initrd should be loaded. The meaning of <file> is 1067 obviously bootloader-dependent, and some boot loaders 1068 (e.g. LILO) do not have such a command. 1069 1070In addition, some boot loaders add the following options to the 1071user-specified command line: 1072 1073 BOOT_IMAGE=<file> 1074 The boot image which was loaded. Again, the meaning of <file> 1075 is obviously bootloader-dependent. 1076 1077 auto 1078 The kernel was booted without explicit user intervention. 1079 1080If these options are added by the boot loader, it is highly 1081recommended that they are located *first*, before the user-specified 1082or configuration-specified command line. Otherwise, "init=/bin/sh" 1083gets confused by the "auto" option. 1084 1085 1086Running the Kernel 1087================== 1088 1089The kernel is started by jumping to the kernel entry point, which is 1090located at *segment* offset 0x20 from the start of the real mode 1091kernel. This means that if you loaded your real-mode kernel code at 10920x90000, the kernel entry point is 9020:0000. 1093 1094At entry, ds = es = ss should point to the start of the real-mode 1095kernel code (0x9000 if the code is loaded at 0x90000), sp should be 1096set up properly, normally pointing to the top of the heap, and 1097interrupts should be disabled. Furthermore, to guard against bugs in 1098the kernel, it is recommended that the boot loader sets fs = gs = ds = 1099es = ss. 1100 1101In our example from above, we would do:: 1102 1103 /* Note: in the case of the "old" kernel protocol, base_ptr must 1104 be == 0x90000 at this point; see the previous sample code */ 1105 1106 seg = base_ptr >> 4; 1107 1108 cli(); /* Enter with interrupts disabled! */ 1109 1110 /* Set up the real-mode kernel stack */ 1111 _SS = seg; 1112 _SP = heap_end; 1113 1114 _DS = _ES = _FS = _GS = seg; 1115 jmp_far(seg+0x20, 0); /* Run the kernel */ 1116 1117If your boot sector accesses a floppy drive, it is recommended to 1118switch off the floppy motor before running the kernel, since the 1119kernel boot leaves interrupts off and thus the motor will not be 1120switched off, especially if the loaded kernel has the floppy driver as 1121a demand-loaded module! 1122 1123 1124Advanced Boot Loader Hooks 1125========================== 1126 1127If the boot loader runs in a particularly hostile environment (such as 1128LOADLIN, which runs under DOS) it may be impossible to follow the 1129standard memory location requirements. Such a boot loader may use the 1130following hooks that, if set, are invoked by the kernel at the 1131appropriate time. The use of these hooks should probably be 1132considered an absolutely last resort! 1133 1134IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and 1135%edi across invocation. 1136 1137 realmode_swtch: 1138 A 16-bit real mode far subroutine invoked immediately before 1139 entering protected mode. The default routine disables NMI, so 1140 your routine should probably do so, too. 1141 1142 code32_start: 1143 A 32-bit flat-mode routine *jumped* to immediately after the 1144 transition to protected mode, but before the kernel is 1145 uncompressed. No segments, except CS, are guaranteed to be 1146 set up (current kernels do, but older ones do not); you should 1147 set them up to BOOT_DS (0x18) yourself. 1148 1149 After completing your hook, you should jump to the address 1150 that was in this field before your boot loader overwrote it 1151 (relocated, if appropriate.) 1152 1153 115432-bit Boot Protocol 1155==================== 1156 1157For machine with some new BIOS other than legacy BIOS, such as EFI, 1158LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel 1159based on legacy BIOS can not be used, so a 32-bit boot protocol needs 1160to be defined. 1161 1162In 32-bit boot protocol, the first step in loading a Linux kernel 1163should be to setup the boot parameters (struct boot_params, 1164traditionally known as "zero page"). The memory for struct boot_params 1165should be allocated and initialized to all zero. Then the setup header 1166from offset 0x01f1 of kernel image on should be loaded into struct 1167boot_params and examined. The end of setup header can be calculated as 1168follow:: 1169 1170 0x0202 + byte value at offset 0x0201 1171 1172In addition to read/modify/write the setup header of the struct 1173boot_params as that of 16-bit boot protocol, the boot loader should 1174also fill the additional fields of the struct boot_params as that 1175described in zero-page.txt. 1176 1177After setting up the struct boot_params, the boot loader can load the 117832/64-bit kernel in the same way as that of 16-bit boot protocol. 1179 1180In 32-bit boot protocol, the kernel is started by jumping to the 118132-bit kernel entry point, which is the start address of loaded 118232/64-bit kernel. 1183 1184At entry, the CPU must be in 32-bit protected mode with paging 1185disabled; a GDT must be loaded with the descriptors for selectors 1186__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat 1187segment; __BOOT_CS must have execute/read permission, and __BOOT_DS 1188must have read/write permission; CS must be __BOOT_CS and DS, ES, SS 1189must be __BOOT_DS; interrupt must be disabled; %esi must hold the base 1190address of the struct boot_params; %ebp, %edi and %ebx must be zero. 1191 119264-bit Boot Protocol 1193==================== 1194 1195For machine with 64bit cpus and 64bit kernel, we could use 64bit bootloader 1196and we need a 64-bit boot protocol. 1197 1198In 64-bit boot protocol, the first step in loading a Linux kernel 1199should be to setup the boot parameters (struct boot_params, 1200traditionally known as "zero page"). The memory for struct boot_params 1201could be allocated anywhere (even above 4G) and initialized to all zero. 1202Then, the setup header at offset 0x01f1 of kernel image on should be 1203loaded into struct boot_params and examined. The end of setup header 1204can be calculated as follows:: 1205 1206 0x0202 + byte value at offset 0x0201 1207 1208In addition to read/modify/write the setup header of the struct 1209boot_params as that of 16-bit boot protocol, the boot loader should 1210also fill the additional fields of the struct boot_params as described 1211in zero-page.txt. 1212 1213After setting up the struct boot_params, the boot loader can load 121464-bit kernel in the same way as that of 16-bit boot protocol, but 1215kernel could be loaded above 4G. 1216 1217In 64-bit boot protocol, the kernel is started by jumping to the 121864-bit kernel entry point, which is the start address of loaded 121964-bit kernel plus 0x200. 1220 1221At entry, the CPU must be in 64-bit mode with paging enabled. 1222The range with setup_header.init_size from start address of loaded 1223kernel and zero page and command line buffer get ident mapping; 1224a GDT must be loaded with the descriptors for selectors 1225__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat 1226segment; __BOOT_CS must have execute/read permission, and __BOOT_DS 1227must have read/write permission; CS must be __BOOT_CS and DS, ES, SS 1228must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base 1229address of the struct boot_params. 1230 1231EFI Handover Protocol 1232===================== 1233 1234This protocol allows boot loaders to defer initialisation to the EFI 1235boot stub. The boot loader is required to load the kernel/initrd(s) 1236from the boot media and jump to the EFI handover protocol entry point 1237which is hdr->handover_offset bytes from the beginning of 1238startup_{32,64}. 1239 1240The function prototype for the handover entry point looks like this:: 1241 1242 efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp) 1243 1244'handle' is the EFI image handle passed to the boot loader by the EFI 1245firmware, 'table' is the EFI system table - these are the first two 1246arguments of the "handoff state" as described in section 2.3 of the 1247UEFI specification. 'bp' is the boot loader-allocated boot params. 1248 1249The boot loader *must* fill out the following fields in bp:: 1250 1251 - hdr.code32_start 1252 - hdr.cmd_line_ptr 1253 - hdr.ramdisk_image (if applicable) 1254 - hdr.ramdisk_size (if applicable) 1255 1256All other fields should be zero. 1257
