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
  53**** MEMORY LAYOUT
  54
  55The traditional memory map for the kernel loader, used for Image or
  56zImage kernels, typically looks like:
  57
  58        |                        |
  590A0000  +------------------------+
  60        |  Reserved for BIOS     |      Do not use.  Reserved for BIOS EBDA.
  6109A000  +------------------------+
  62        |  Command line          |
  63        |  Stack/heap            |      For use by the kernel real-mode code.
  64098000  +------------------------+      
  65        |  Kernel setup          |      The kernel real-mode code.
  66090200  +------------------------+
  67        |  Kernel boot sector    |      The kernel legacy boot sector.
  68090000  +------------------------+
  69        |  Protected-mode kernel |      The bulk of the kernel image.
  70010000  +------------------------+
  71        |  Boot loader           |      <- Boot sector entry point 0000:7C00
  72001000  +------------------------+
  73        |  Reserved for MBR/BIOS |
  74000800  +------------------------+
  75        |  Typically used by MBR |
  76000600  +------------------------+ 
  77        |  BIOS use only         |
  78000000  +------------------------+
  79
  80
  81When using bzImage, the protected-mode kernel was relocated to
  820x100000 ("high memory"), and the kernel real-mode block (boot sector,
  83setup, and stack/heap) was made relocatable to any address between
  840x10000 and end of low memory. Unfortunately, in protocols 2.00 and
  852.01 the 0x90000+ memory range is still used internally by the kernel;
  86the 2.02 protocol resolves that problem.
  87
  88It is desirable to keep the "memory ceiling" -- the highest point in
  89low memory touched by the boot loader -- as low as possible, since
  90some newer BIOSes have begun to allocate some rather large amounts of
  91memory, called the Extended BIOS Data Area, near the top of low
  92memory.  The boot loader should use the "INT 12h" BIOS call to verify
  93how much low memory is available.
  94
  95Unfortunately, if INT 12h reports that the amount of memory is too
  96low, there is usually nothing the boot loader can do but to report an
  97error to the user.  The boot loader should therefore be designed to
  98take up as little space in low memory as it reasonably can.  For
  99zImage or old bzImage kernels, which need data written into the
 1000x90000 segment, the boot loader should make sure not to use memory
 101above the 0x9A000 point; too many BIOSes will break above that point.
 102
 103For a modern bzImage kernel with boot protocol version >= 2.02, a
 104memory layout like the following is suggested:
 105
 106        ~                        ~
 107        |  Protected-mode kernel |
 108100000  +------------------------+
 109        |  I/O memory hole       |
 1100A0000  +------------------------+
 111        |  Reserved for BIOS     |      Leave as much as possible unused
 112        ~                        ~
 113        |  Command line          |      (Can also be below the X+10000 mark)
 114X+10000 +------------------------+
 115        |  Stack/heap            |      For use by the kernel real-mode code.
 116X+08000 +------------------------+      
 117        |  Kernel setup          |      The kernel real-mode code.
 118        |  Kernel boot sector    |      The kernel legacy boot sector.
 119X       +------------------------+
 120        |  Boot loader           |      <- Boot sector entry point 0000:7C00
 121001000  +------------------------+
 122        |  Reserved for MBR/BIOS |
 123000800  +------------------------+
 124        |  Typically used by MBR |
 125000600  +------------------------+ 
 126        |  BIOS use only         |
 127000000  +------------------------+
 128
 129... where the address X is as low as the design of the boot loader
 130permits.
 131
 132
 133**** THE REAL-MODE KERNEL HEADER
 134
 135In the following text, and anywhere in the kernel boot sequence, "a
 136sector" refers to 512 bytes.  It is independent of the actual sector
 137size of the underlying medium.
 138
 139The first step in loading a Linux kernel should be to load the
 140real-mode code (boot sector and setup code) and then examine the
 141following header at offset 0x01f1.  The real-mode code can total up to
 14232K, although the boot loader may choose to load only the first two
 143sectors (1K) and then examine the bootup sector size.
 144
 145The header looks like:
 146
 147Offset  Proto   Name            Meaning
 148/Size
 149
 15001F1/1  ALL(1   setup_sects     The size of the setup in sectors
 15101F2/2  ALL     root_flags      If set, the root is mounted readonly
 15201F4/4  2.04+(2 syssize         The size of the 32-bit code in 16-byte paras
 15301F8/2  ALL     ram_size        DO NOT USE - for bootsect.S use only
 15401FA/2  ALL     vid_mode        Video mode control
 15501FC/2  ALL     root_dev        Default root device number
 15601FE/2  ALL     boot_flag       0xAA55 magic number
 1570200/2  2.00+   jump            Jump instruction
 1580202/4  2.00+   header          Magic signature "HdrS"
 1590206/2  2.00+   version         Boot protocol version supported
 1600208/4  2.00+   realmode_swtch  Boot loader hook (see below)
 161020C/2  2.00+   start_sys_seg   The load-low segment (0x1000) (obsolete)
 162020E/2  2.00+   kernel_version  Pointer to kernel version string
 1630210/1  2.00+   type_of_loader  Boot loader identifier
 1640211/1  2.00+   loadflags       Boot protocol option flags
 1650212/2  2.00+   setup_move_size Move to high memory size (used with hooks)
 1660214/4  2.00+   code32_start    Boot loader hook (see below)
 1670218/4  2.00+   ramdisk_image   initrd load address (set by boot loader)
 168021C/4  2.00+   ramdisk_size    initrd size (set by boot loader)
 1690220/4  2.00+   bootsect_kludge DO NOT USE - for bootsect.S use only
 1700224/2  2.01+   heap_end_ptr    Free memory after setup end
 1710226/2  N/A     pad1            Unused
 1720228/4  2.02+   cmd_line_ptr    32-bit pointer to the kernel command line
 173022C/4  2.03+   ramdisk_max     Highest legal initrd address
 1740230/4  2.05+   kernel_alignment Physical addr alignment required for kernel
 1750234/1  2.05+   relocatable_kernel Whether kernel is relocatable or not
 1760235/1  N/A     pad2            Unused
 1770236/2  N/A     pad3            Unused
 1780238/4  2.06+   cmdline_size    Maximum size of the kernel command line
 179023C/4  2.07+   hardware_subarch Hardware subarchitecture
 1800240/8  2.07+   hardware_subarch_data Subarchitecture-specific data
 1810248/4  2.08+   payload_offset  Offset of kernel payload
 182024C/4  2.08+   payload_length  Length of kernel payload
 1830250/8  2.09+   setup_data      64-bit physical pointer to linked list
 184                                of struct setup_data
 185
 186(1) For backwards compatibility, if the setup_sects field contains 0, the
 187    real value is 4.
 188
 189(2) For boot protocol prior to 2.04, the upper two bytes of the syssize
 190    field are unusable, which means the size of a bzImage kernel
 191    cannot be determined.
 192
 193If the "HdrS" (0x53726448) magic number is not found at offset 0x202,
 194the boot protocol version is "old".  Loading an old kernel, the
 195following parameters should be assumed:
 196
 197        Image type = zImage
 198        initrd not supported
 199        Real-mode kernel must be located at 0x90000.
 200
 201Otherwise, the "version" field contains the protocol version,
 202e.g. protocol version 2.01 will contain 0x0201 in this field.  When
 203setting fields in the header, you must make sure only to set fields
 204supported by the protocol version in use.
 205
 206
 207**** DETAILS OF HEADER FIELDS
 208
 209For each field, some are information from the kernel to the bootloader
 210("read"), some are expected to be filled out by the bootloader
 211("write"), and some are expected to be read and modified by the
 212bootloader ("modify").
 213
 214All general purpose boot loaders should write the fields marked
 215(obligatory).  Boot loaders who want to load the kernel at a
 216nonstandard address should fill in the fields marked (reloc); other
 217boot loaders can ignore those fields.
 218
 219The byte order of all fields is littleendian (this is x86, after all.)
 220
 221Field name:     setup_sects
 222Type:           read
 223Offset/size:    0x1f1/1
 224Protocol:       ALL
 225
 226  The size of the setup code in 512-byte sectors.  If this field is
 227  0, the real value is 4.  The real-mode code consists of the boot
 228  sector (always one 512-byte sector) plus the setup code.
 229
 230Field name:      root_flags
 231Type:            modify (optional)
 232Offset/size:     0x1f2/2
 233Protocol:        ALL
 234
 235  If this field is nonzero, the root defaults to readonly.  The use of
 236  this field is deprecated; use the "ro" or "rw" options on the
 237  command line instead.
 238
 239Field name:     syssize
 240Type:           read
 241Offset/size:    0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL)
 242Protocol:       2.04+
 243
 244  The size of the protected-mode code in units of 16-byte paragraphs.
 245  For protocol versions older than 2.04 this field is only two bytes
 246  wide, and therefore cannot be trusted for the size of a kernel if
 247  the LOAD_HIGH flag is set.
 248
 249Field name:     ram_size
 250Type:           kernel internal
 251Offset/size:    0x1f8/2
 252Protocol:       ALL
 253
 254  This field is obsolete.
 255
 256Field name:     vid_mode
 257Type:           modify (obligatory)
 258Offset/size:    0x1fa/2
 259
 260  Please see the section on SPECIAL COMMAND LINE OPTIONS.
 261
 262Field name:     root_dev
 263Type:           modify (optional)
 264Offset/size:    0x1fc/2
 265Protocol:       ALL
 266
 267  The default root device device number.  The use of this field is
 268  deprecated, use the "root=" option on the command line instead.
 269
 270Field name:     boot_flag
 271Type:           read
 272Offset/size:    0x1fe/2
 273Protocol:       ALL
 274
 275  Contains 0xAA55.  This is the closest thing old Linux kernels have
 276  to a magic number.
 277
 278Field name:     jump
 279Type:           read
 280Offset/size:    0x200/2
 281Protocol:       2.00+
 282
 283  Contains an x86 jump instruction, 0xEB followed by a signed offset
 284  relative to byte 0x202.  This can be used to determine the size of
 285  the header.
 286
 287Field name:     header
 288Type:           read
 289Offset/size:    0x202/4
 290Protocol:       2.00+
 291
 292  Contains the magic number "HdrS" (0x53726448).
 293
 294Field name:     version
 295Type:           read
 296Offset/size:    0x206/2
 297Protocol:       2.00+
 298
 299  Contains the boot protocol version, in (major << 8)+minor format,
 300  e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version
 301  10.17.
 302
 303Field name:     realmode_swtch
 304Type:           modify (optional)
 305Offset/size:    0x208/4
 306Protocol:       2.00+
 307
 308  Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
 309
 310Field name:     start_sys_seg
 311Type:           read
 312Offset/size:    0x20c/2
 313Protocol:       2.00+
 314
 315  The load low segment (0x1000).  Obsolete.
 316
 317Field name:     kernel_version
 318Type:           read
 319Offset/size:    0x20e/2
 320Protocol:       2.00+
 321
 322  If set to a nonzero value, contains a pointer to a NUL-terminated
 323  human-readable kernel version number string, less 0x200.  This can
 324  be used to display the kernel version to the user.  This value
 325  should be less than (0x200*setup_sects).
 326
 327  For example, if this value is set to 0x1c00, the kernel version
 328  number string can be found at offset 0x1e00 in the kernel file.
 329  This is a valid value if and only if the "setup_sects" field
 330  contains the value 15 or higher, as:
 331
 332        0x1c00  < 15*0x200 (= 0x1e00) but
 333        0x1c00 >= 14*0x200 (= 0x1c00)
 334
 335        0x1c00 >> 9 = 14, so the minimum value for setup_secs is 15.
 336
 337Field name:     type_of_loader
 338Type:           write (obligatory)
 339Offset/size:    0x210/1
 340Protocol:       2.00+
 341
 342  If your boot loader has an assigned id (see table below), enter
 343  0xTV here, where T is an identifier for the boot loader and V is
 344  a version number.  Otherwise, enter 0xFF here.
 345
 346  Assigned boot loader ids:
 347        0  LILO                 (0x00 reserved for pre-2.00 bootloader)
 348        1  Loadlin
 349        2  bootsect-loader      (0x20, all other values reserved)
 350        3  SYSLINUX
 351        4  EtherBoot
 352        5  ELILO
 353        7  GRUB
 354        8  U-BOOT
 355        9  Xen
 356        A  Gujin
 357        B  Qemu
 358
 359  Please contact <hpa@zytor.com> if you need a bootloader ID
 360  value assigned.
 361
 362Field name:     loadflags
 363Type:           modify (obligatory)
 364Offset/size:    0x211/1
 365Protocol:       2.00+
 366
 367  This field is a bitmask.
 368
 369  Bit 0 (read): LOADED_HIGH
 370        - If 0, the protected-mode code is loaded at 0x10000.
 371        - If 1, the protected-mode code is loaded at 0x100000.
 372
 373  Bit 5 (write): QUIET_FLAG
 374        - If 0, print early messages.
 375        - If 1, suppress early messages.
 376                This requests to the kernel (decompressor and early
 377                kernel) to not write early messages that require
 378                accessing the display hardware directly.
 379
 380  Bit 6 (write): KEEP_SEGMENTS
 381        Protocol: 2.07+
 382        - If 0, reload the segment registers in the 32bit entry point.
 383        - If 1, do not reload the segment registers in the 32bit entry point.
 384                Assume that %cs %ds %ss %es are all set to flat segments with
 385                a base of 0 (or the equivalent for their environment).
 386
 387  Bit 7 (write): CAN_USE_HEAP
 388        Set this bit to 1 to indicate that the value entered in the
 389        heap_end_ptr is valid.  If this field is clear, some setup code
 390        functionality will be disabled.
 391
 392Field name:     setup_move_size
 393Type:           modify (obligatory)
 394Offset/size:    0x212/2
 395Protocol:       2.00-2.01
 396
 397  When using protocol 2.00 or 2.01, if the real mode kernel is not
 398  loaded at 0x90000, it gets moved there later in the loading
 399  sequence.  Fill in this field if you want additional data (such as
 400  the kernel command line) moved in addition to the real-mode kernel
 401  itself.
 402
 403  The unit is bytes starting with the beginning of the boot sector.
 404  
 405  This field is can be ignored when the protocol is 2.02 or higher, or
 406  if the real-mode code is loaded at 0x90000.
 407
 408Field name:     code32_start
 409Type:           modify (optional, reloc)
 410Offset/size:    0x214/4
 411Protocol:       2.00+
 412
 413  The address to jump to in protected mode.  This defaults to the load
 414  address of the kernel, and can be used by the boot loader to
 415  determine the proper load address.
 416
 417  This field can be modified for two purposes:
 418
 419  1. as a boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
 420
 421  2. if a bootloader which does not install a hook loads a
 422     relocatable kernel at a nonstandard address it will have to modify
 423     this field to point to the load address.
 424
 425Field name:     ramdisk_image
 426Type:           write (obligatory)
 427Offset/size:    0x218/4
 428Protocol:       2.00+
 429
 430  The 32-bit linear address of the initial ramdisk or ramfs.  Leave at
 431  zero if there is no initial ramdisk/ramfs.
 432
 433Field name:     ramdisk_size
 434Type:           write (obligatory)
 435Offset/size:    0x21c/4
 436Protocol:       2.00+
 437
 438  Size of the initial ramdisk or ramfs.  Leave at zero if there is no
 439  initial ramdisk/ramfs.
 440
 441Field name:     bootsect_kludge
 442Type:           kernel internal
 443Offset/size:    0x220/4
 444Protocol:       2.00+
 445
 446  This field is obsolete.
 447
 448Field name:     heap_end_ptr
 449Type:           write (obligatory)
 450Offset/size:    0x224/2
 451Protocol:       2.01+
 452
 453  Set this field to the offset (from the beginning of the real-mode
 454  code) of the end of the setup stack/heap, minus 0x0200.
 455
 456Field name:     cmd_line_ptr
 457Type:           write (obligatory)
 458Offset/size:    0x228/4
 459Protocol:       2.02+
 460
 461  Set this field to the linear address of the kernel command line.
 462  The kernel command line can be located anywhere between the end of
 463  the setup heap and 0xA0000; it does not have to be located in the
 464  same 64K segment as the real-mode code itself.
 465
 466  Fill in this field even if your boot loader does not support a
 467  command line, in which case you can point this to an empty string
 468  (or better yet, to the string "auto".)  If this field is left at
 469  zero, the kernel will assume that your boot loader does not support
 470  the 2.02+ protocol.
 471
 472Field name:     ramdisk_max
 473Type:           read
 474Offset/size:    0x22c/4
 475Protocol:       2.03+
 476
 477  The maximum address that may be occupied by the initial
 478  ramdisk/ramfs contents.  For boot protocols 2.02 or earlier, this
 479  field is not present, and the maximum address is 0x37FFFFFF.  (This
 480  address is defined as the address of the highest safe byte, so if
 481  your ramdisk is exactly 131072 bytes long and this field is
 482  0x37FFFFFF, you can start your ramdisk at 0x37FE0000.)
 483
 484Field name:     kernel_alignment
 485Type:           read (reloc)
 486Offset/size:    0x230/4
 487Protocol:       2.05+
 488
 489  Alignment unit required by the kernel (if relocatable_kernel is true.)
 490
 491Field name:     relocatable_kernel
 492Type:           read (reloc)
 493Offset/size:    0x234/1
 494Protocol:       2.05+
 495
 496  If this field is nonzero, the protected-mode part of the kernel can
 497  be loaded at any address that satisfies the kernel_alignment field.
 498  After loading, the boot loader must set the code32_start field to
 499  point to the loaded code, or to a boot loader hook.
 500
 501Field name:     cmdline_size
 502Type:           read
 503Offset/size:    0x238/4
 504Protocol:       2.06+
 505
 506  The maximum size of the command line without the terminating
 507  zero. This means that the command line can contain at most
 508  cmdline_size characters. With protocol version 2.05 and earlier, the
 509  maximum size was 255.
 510
 511Field name:     hardware_subarch
 512Type:           write (optional, defaults to x86/PC)
 513Offset/size:    0x23c/4
 514Protocol:       2.07+
 515
 516  In a paravirtualized environment the hardware low level architectural
 517  pieces such as interrupt handling, page table handling, and
 518  accessing process control registers needs to be done differently.
 519
 520  This field allows the bootloader to inform the kernel we are in one
 521  one of those environments.
 522
 523  0x00000000    The default x86/PC environment
 524  0x00000001    lguest
 525  0x00000002    Xen
 526
 527Field name:     hardware_subarch_data
 528Type:           write (subarch-dependent)
 529Offset/size:    0x240/8
 530Protocol:       2.07+
 531
 532  A pointer to data that is specific to hardware subarch
 533  This field is currently unused for the default x86/PC environment,
 534  do not modify.
 535
 536Field name:     payload_offset
 537Type:           read
 538Offset/size:    0x248/4
 539Protocol:       2.08+
 540
 541  If non-zero then this field contains the offset from the beginning
 542  of the protected-mode code to the payload.
 543
 544  The payload may be compressed. The format of both the compressed and
 545  uncompressed data should be determined using the standard magic
 546  numbers.  The currently supported compression formats are gzip
 547  (magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A) and LZMA
 548  (magic number 5D 00).  The uncompressed payload is currently always ELF
 549  (magic number 7F 45 4C 46).
 550  
 551Field name:     payload_length
 552Type:           read
 553Offset/size:    0x24c/4
 554Protocol:       2.08+
 555
 556  The length of the payload.
 557
 558Field name:     setup_data
 559Type:           write (special)
 560Offset/size:    0x250/8
 561Protocol:       2.09+
 562
 563  The 64-bit physical pointer to NULL terminated single linked list of
 564  struct setup_data. This is used to define a more extensible boot
 565  parameters passing mechanism. The definition of struct setup_data is
 566  as follow:
 567
 568  struct setup_data {
 569          u64 next;
 570          u32 type;
 571          u32 len;
 572          u8  data[0];
 573  };
 574
 575  Where, the next is a 64-bit physical pointer to the next node of
 576  linked list, the next field of the last node is 0; the type is used
 577  to identify the contents of data; the len is the length of data
 578  field; the data holds the real payload.
 579
 580  This list may be modified at a number of points during the bootup
 581  process.  Therefore, when modifying this list one should always make
 582  sure to consider the case where the linked list already contains
 583  entries.
 584
 585
 586**** THE IMAGE CHECKSUM
 587
 588From boot protocol version 2.08 onwards the CRC-32 is calculated over
 589the entire file using the characteristic polynomial 0x04C11DB7 and an
 590initial remainder of 0xffffffff.  The checksum is appended to the
 591file; therefore the CRC of the file up to the limit specified in the
 592syssize field of the header is always 0.
 593
 594
 595**** THE KERNEL COMMAND LINE
 596
 597The kernel command line has become an important way for the boot
 598loader to communicate with the kernel.  Some of its options are also
 599relevant to the boot loader itself, see "special command line options"
 600below.
 601
 602The kernel command line is a null-terminated string. The maximum
 603length can be retrieved from the field cmdline_size.  Before protocol
 604version 2.06, the maximum was 255 characters.  A string that is too
 605long will be automatically truncated by the kernel.
 606
 607If the boot protocol version is 2.02 or later, the address of the
 608kernel command line is given by the header field cmd_line_ptr (see
 609above.)  This address can be anywhere between the end of the setup
 610heap and 0xA0000.
 611
 612If the protocol version is *not* 2.02 or higher, the kernel
 613command line is entered using the following protocol:
 614
 615        At offset 0x0020 (word), "cmd_line_magic", enter the magic
 616        number 0xA33F.
 617
 618        At offset 0x0022 (word), "cmd_line_offset", enter the offset
 619        of the kernel command line (relative to the start of the
 620        real-mode kernel).
 621        
 622        The kernel command line *must* be within the memory region
 623        covered by setup_move_size, so you may need to adjust this
 624        field.
 625
 626
 627**** MEMORY LAYOUT OF THE REAL-MODE CODE
 628
 629The real-mode code requires a stack/heap to be set up, as well as
 630memory allocated for the kernel command line.  This needs to be done
 631in the real-mode accessible memory in bottom megabyte.
 632
 633It should be noted that modern machines often have a sizable Extended
 634BIOS Data Area (EBDA).  As a result, it is advisable to use as little
 635of the low megabyte as possible.
 636
 637Unfortunately, under the following circumstances the 0x90000 memory
 638segment has to be used:
 639
 640        - When loading a zImage kernel ((loadflags & 0x01) == 0).
 641        - When loading a 2.01 or earlier boot protocol kernel.
 642
 643          -> For the 2.00 and 2.01 boot protocols, the real-mode code
 644             can be loaded at another address, but it is internally
 645             relocated to 0x90000.  For the "old" protocol, the
 646             real-mode code must be loaded at 0x90000.
 647
 648When loading at 0x90000, avoid using memory above 0x9a000.
 649
 650For boot protocol 2.02 or higher, the command line does not have to be
 651located in the same 64K segment as the real-mode setup code; it is
 652thus permitted to give the stack/heap the full 64K segment and locate
 653the command line above it.
 654
 655The kernel command line should not be located below the real-mode
 656code, nor should it be located in high memory.
 657
 658
 659**** SAMPLE BOOT CONFIGURATION
 660
 661As a sample configuration, assume the following layout of the real
 662mode segment:
 663
 664    When loading below 0x90000, use the entire segment:
 665
 666        0x0000-0x7fff   Real mode kernel
 667        0x8000-0xdfff   Stack and heap
 668        0xe000-0xffff   Kernel command line
 669
 670    When loading at 0x90000 OR the protocol version is 2.01 or earlier:
 671
 672        0x0000-0x7fff   Real mode kernel
 673        0x8000-0x97ff   Stack and heap
 674        0x9800-0x9fff   Kernel command line
 675
 676Such a boot loader should enter the following fields in the header:
 677
 678        unsigned long base_ptr; /* base address for real-mode segment */
 679
 680        if ( setup_sects == 0 ) {
 681                setup_sects = 4;
 682        }
 683
 684        if ( protocol >= 0x0200 ) {
 685                type_of_loader = <type code>;
 686                if ( loading_initrd ) {
 687                        ramdisk_image = <initrd_address>;
 688                        ramdisk_size = <initrd_size>;
 689                }
 690
 691                if ( protocol >= 0x0202 && loadflags & 0x01 )
 692                        heap_end = 0xe000;
 693                else
 694                        heap_end = 0x9800;
 695
 696                if ( protocol >= 0x0201 ) {
 697                        heap_end_ptr = heap_end - 0x200;
 698                        loadflags |= 0x80; /* CAN_USE_HEAP */
 699                }
 700
 701                if ( protocol >= 0x0202 ) {
 702                        cmd_line_ptr = base_ptr + heap_end;
 703                        strcpy(cmd_line_ptr, cmdline);
 704                } else {
 705                        cmd_line_magic  = 0xA33F;
 706                        cmd_line_offset = heap_end;
 707                        setup_move_size = heap_end + strlen(cmdline)+1;
 708                        strcpy(base_ptr+cmd_line_offset, cmdline);
 709                }
 710        } else {
 711                /* Very old kernel */
 712
 713                heap_end = 0x9800;
 714
 715                cmd_line_magic  = 0xA33F;
 716                cmd_line_offset = heap_end;
 717
 718                /* A very old kernel MUST have its real-mode code
 719                   loaded at 0x90000 */
 720
 721                if ( base_ptr != 0x90000 ) {
 722                        /* Copy the real-mode kernel */
 723                        memcpy(0x90000, base_ptr, (setup_sects+1)*512);
 724                        base_ptr = 0x90000;              /* Relocated */
 725                }
 726
 727                strcpy(0x90000+cmd_line_offset, cmdline);
 728
 729                /* It is recommended to clear memory up to the 32K mark */
 730                memset(0x90000 + (setup_sects+1)*512, 0,
 731                       (64-(setup_sects+1))*512);
 732        }
 733
 734
 735**** LOADING THE REST OF THE KERNEL
 736
 737The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512
 738in the kernel file (again, if setup_sects == 0 the real value is 4.)
 739It should be loaded at address 0x10000 for Image/zImage kernels and
 7400x100000 for bzImage kernels.
 741
 742The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01
 743bit (LOAD_HIGH) in the loadflags field is set:
 744
 745        is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01);
 746        load_address = is_bzImage ? 0x100000 : 0x10000;
 747
 748Note that Image/zImage kernels can be up to 512K in size, and thus use
 749the entire 0x10000-0x90000 range of memory.  This means it is pretty
 750much a requirement for these kernels to load the real-mode part at
 7510x90000.  bzImage kernels allow much more flexibility.
 752
 753
 754**** SPECIAL COMMAND LINE OPTIONS
 755
 756If the command line provided by the boot loader is entered by the
 757user, the user may expect the following command line options to work.
 758They should normally not be deleted from the kernel command line even
 759though not all of them are actually meaningful to the kernel.  Boot
 760loader authors who need additional command line options for the boot
 761loader itself should get them registered in
 762Documentation/kernel-parameters.txt to make sure they will not
 763conflict with actual kernel options now or in the future.
 764
 765  vga=<mode>
 766        <mode> here is either an integer (in C notation, either
 767        decimal, octal, or hexadecimal) or one of the strings
 768        "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask"
 769        (meaning 0xFFFD).  This value should be entered into the
 770        vid_mode field, as it is used by the kernel before the command
 771        line is parsed.
 772
 773  mem=<size>
 774        <size> is an integer in C notation optionally followed by
 775        (case insensitive) K, M, G, T, P or E (meaning << 10, << 20,
 776        << 30, << 40, << 50 or << 60).  This specifies the end of
 777        memory to the kernel. This affects the possible placement of
 778        an initrd, since an initrd should be placed near end of
 779        memory.  Note that this is an option to *both* the kernel and
 780        the bootloader!
 781
 782  initrd=<file>
 783        An initrd should be loaded.  The meaning of <file> is
 784        obviously bootloader-dependent, and some boot loaders
 785        (e.g. LILO) do not have such a command.
 786
 787In addition, some boot loaders add the following options to the
 788user-specified command line:
 789
 790  BOOT_IMAGE=<file>
 791        The boot image which was loaded.  Again, the meaning of <file>
 792        is obviously bootloader-dependent.
 793
 794  auto
 795        The kernel was booted without explicit user intervention.
 796
 797If these options are added by the boot loader, it is highly
 798recommended that they are located *first*, before the user-specified
 799or configuration-specified command line.  Otherwise, "init=/bin/sh"
 800gets confused by the "auto" option.
 801
 802
 803**** RUNNING THE KERNEL
 804
 805The kernel is started by jumping to the kernel entry point, which is
 806located at *segment* offset 0x20 from the start of the real mode
 807kernel.  This means that if you loaded your real-mode kernel code at
 8080x90000, the kernel entry point is 9020:0000.
 809
 810At entry, ds = es = ss should point to the start of the real-mode
 811kernel code (0x9000 if the code is loaded at 0x90000), sp should be
 812set up properly, normally pointing to the top of the heap, and
 813interrupts should be disabled.  Furthermore, to guard against bugs in
 814the kernel, it is recommended that the boot loader sets fs = gs = ds =
 815es = ss.
 816
 817In our example from above, we would do:
 818
 819        /* Note: in the case of the "old" kernel protocol, base_ptr must
 820           be == 0x90000 at this point; see the previous sample code */
 821
 822        seg = base_ptr >> 4;
 823
 824        cli();  /* Enter with interrupts disabled! */
 825
 826        /* Set up the real-mode kernel stack */
 827        _SS = seg;
 828        _SP = heap_end;
 829
 830        _DS = _ES = _FS = _GS = seg;
 831        jmp_far(seg+0x20, 0);   /* Run the kernel */
 832
 833If your boot sector accesses a floppy drive, it is recommended to
 834switch off the floppy motor before running the kernel, since the
 835kernel boot leaves interrupts off and thus the motor will not be
 836switched off, especially if the loaded kernel has the floppy driver as
 837a demand-loaded module!
 838
 839
 840**** ADVANCED BOOT LOADER HOOKS
 841
 842If the boot loader runs in a particularly hostile environment (such as
 843LOADLIN, which runs under DOS) it may be impossible to follow the
 844standard memory location requirements.  Such a boot loader may use the
 845following hooks that, if set, are invoked by the kernel at the
 846appropriate time.  The use of these hooks should probably be
 847considered an absolutely last resort!
 848
 849IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
 850%edi across invocation.
 851
 852  realmode_swtch:
 853        A 16-bit real mode far subroutine invoked immediately before
 854        entering protected mode.  The default routine disables NMI, so
 855        your routine should probably do so, too.
 856
 857  code32_start:
 858        A 32-bit flat-mode routine *jumped* to immediately after the
 859        transition to protected mode, but before the kernel is
 860        uncompressed.  No segments, except CS, are guaranteed to be
 861        set up (current kernels do, but older ones do not); you should
 862        set them up to BOOT_DS (0x18) yourself.
 863
 864        After completing your hook, you should jump to the address
 865        that was in this field before your boot loader overwrote it
 866        (relocated, if appropriate.)
 867
 868
 869**** 32-bit BOOT PROTOCOL
 870
 871For machine with some new BIOS other than legacy BIOS, such as EFI,
 872LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
 873based on legacy BIOS can not be used, so a 32-bit boot protocol needs
 874to be defined.
 875
 876In 32-bit boot protocol, the first step in loading a Linux kernel
 877should be to setup the boot parameters (struct boot_params,
 878traditionally known as "zero page"). The memory for struct boot_params
 879should be allocated and initialized to all zero. Then the setup header
 880from offset 0x01f1 of kernel image on should be loaded into struct
 881boot_params and examined. The end of setup header can be calculated as
 882follow:
 883
 884        0x0202 + byte value at offset 0x0201
 885
 886In addition to read/modify/write the setup header of the struct
 887boot_params as that of 16-bit boot protocol, the boot loader should
 888also fill the additional fields of the struct boot_params as that
 889described in zero-page.txt.
 890
 891After setupping the struct boot_params, the boot loader can load the
 89232/64-bit kernel in the same way as that of 16-bit boot protocol.
 893
 894In 32-bit boot protocol, the kernel is started by jumping to the
 89532-bit kernel entry point, which is the start address of loaded
 89632/64-bit kernel.
 897
 898At entry, the CPU must be in 32-bit protected mode with paging
 899disabled; a GDT must be loaded with the descriptors for selectors
 900__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
 901segment; __BOOS_CS must have execute/read permission, and __BOOT_DS
 902must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
 903must be __BOOT_DS; interrupt must be disabled; %esi must hold the base
 904address of the struct boot_params; %ebp, %edi and %ebx must be zero.
 905
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.