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