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