Documentation/i386/boot.txt: update and correct

In the process of rewriting the x86 setup code, I found a number of
inaccuracies and outdated recommendations in the boot protocol
documentation.  Revamp to make it more up to date.

In particular, the common use of the heap actually requires (slightly)
more than 4K of heap plus stack, which is the recommended amount in
the document; currently the code compensates by being smaller than
specified, but we can't assume that will be true forever.  Thus,
recommend that if we have a modern bzImage kernel, that the bootloader
maximizes the available space.

Signed-off-by: H. Peter Anvin <hpa@zytor.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
This commit is contained in:
H. Peter Anvin 2007-05-08 20:37:02 -07:00 committed by Linus Torvalds
parent d5f9f942c6
commit de372ecd80

View file

@ -2,7 +2,7 @@
----------------------------
H. Peter Anvin <hpa@zytor.com>
Last update 2007-03-06
Last update 2007-05-07
On the i386 platform, the Linux kernel uses a rather complicated boot
convention. This has evolved partially due to historical aspects, as
@ -11,7 +11,7 @@ bootable image, the complicated PC memory model and due to changed
expectations in the PC industry caused by the effective demise of
real-mode DOS as a mainstream operating system.
Currently, four versions of the Linux/i386 boot protocol exist.
Currently, the following versions of the Linux/i386 boot protocol exist.
Old kernels: zImage/Image support only. Some very early kernels
may not even support a command line.
@ -183,9 +183,9 @@ filled out, however:
a version number. Otherwise, enter 0xFF here.
Assigned boot loader ids:
0 LILO
0 LILO (0x00 reserved for pre-2.00 bootloader)
1 Loadlin
2 bootsect-loader
2 bootsect-loader (0x20, all other values reserved)
3 SYSLINUX
4 EtherBoot
5 ELILO
@ -210,6 +210,9 @@ filled out, however:
additional data (such as the kernel command line) moved in
addition to the real-mode kernel itself.
The unit is bytes starting with the beginning of the boot
sector.
ramdisk_image, ramdisk_size:
If your boot loader has loaded an initial ramdisk (initrd),
set ramdisk_image to the 32-bit pointer to the ramdisk data
@ -278,14 +281,54 @@ command line is entered using the following protocol:
field.
**** MEMORY LAYOUT OF THE REAL-MODE CODE
The real-mode code requires a stack/heap to be set up, as well as
memory allocated for the kernel command line. This needs to be done
in the real-mode accessible memory in bottom megabyte.
It should be noted that modern machines often have a sizable Extended
BIOS Data Area (EBDA). As a result, it is advisable to use as little
of the low megabyte as possible.
Unfortunately, under the following circumstances the 0x90000 memory
segment has to be used:
- When loading a zImage kernel ((loadflags & 0x01) == 0).
- When loading a 2.01 or earlier boot protocol kernel.
-> For the 2.00 and 2.01 boot protocols, the real-mode code
can be loaded at another address, but it is internally
relocated to 0x90000. For the "old" protocol, the
real-mode code must be loaded at 0x90000.
When loading at 0x90000, avoid using memory above 0x9a000.
For boot protocol 2.02 or higher, the command line does not have to be
located in the same 64K segment as the real-mode setup code; it is
thus permitted to give the stack/heap the full 64K segment and locate
the command line above it.
The kernel command line should not be located below the real-mode
code, nor should it be located in high memory.
**** SAMPLE BOOT CONFIGURATION
As a sample configuration, assume the following layout of the real
mode segment (this is a typical, and recommended layout):
mode segment:
0x0000-0x7FFF Real mode kernel
0x8000-0x8FFF Stack and heap
0x9000-0x90FF Kernel command line
When loading below 0x90000, use the entire segment:
0x0000-0x7fff Real mode kernel
0x8000-0xdfff Stack and heap
0xe000-0xffff Kernel command line
When loading at 0x90000 OR the protocol version is 2.01 or earlier:
0x0000-0x7fff Real mode kernel
0x8000-0x97ff Stack and heap
0x9800-0x9fff Kernel command line
Such a boot loader should enter the following fields in the header:
@ -301,22 +344,33 @@ Such a boot loader should enter the following fields in the header:
ramdisk_image = <initrd_address>;
ramdisk_size = <initrd_size>;
}
if ( protocol >= 0x0202 && loadflags & 0x01 )
heap_end = 0xe000;
else
heap_end = 0x9800;
if ( protocol >= 0x0201 ) {
heap_end_ptr = 0x9000 - 0x200;
heap_end_ptr = heap_end - 0x200;
loadflags |= 0x80; /* CAN_USE_HEAP */
}
if ( protocol >= 0x0202 ) {
cmd_line_ptr = base_ptr + 0x9000;
cmd_line_ptr = base_ptr + heap_end;
strcpy(cmd_line_ptr, cmdline);
} else {
cmd_line_magic = 0xA33F;
cmd_line_offset = 0x9000;
setup_move_size = 0x9100;
cmd_line_offset = heap_end;
setup_move_size = heap_end + strlen(cmdline)+1;
strcpy(base_ptr+cmd_line_offset, cmdline);
}
} else {
/* Very old kernel */
heap_end = 0x9800;
cmd_line_magic = 0xA33F;
cmd_line_offset = 0x9000;
cmd_line_offset = heap_end;
/* A very old kernel MUST have its real-mode code
loaded at 0x90000 */
@ -324,12 +378,11 @@ Such a boot loader should enter the following fields in the header:
if ( base_ptr != 0x90000 ) {
/* Copy the real-mode kernel */
memcpy(0x90000, base_ptr, (setup_sects+1)*512);
/* Copy the command line */
memcpy(0x99000, base_ptr+0x9000, 256);
base_ptr = 0x90000; /* Relocated */
}
strcpy(0x90000+cmd_line_offset, cmdline);
/* It is recommended to clear memory up to the 32K mark */
memset(0x90000 + (setup_sects+1)*512, 0,
(64-(setup_sects+1))*512);
@ -375,10 +428,11 @@ conflict with actual kernel options now or in the future.
line is parsed.
mem=<size>
<size> is an integer in C notation optionally followed by K, M
or G (meaning << 10, << 20 or << 30). This specifies the end
of memory to the kernel. This affects the possible placement
of an initrd, since an initrd should be placed near end of
<size> is an integer in C notation optionally followed by
(case insensitive) K, M, G, T, P or E (meaning << 10, << 20,
<< 30, << 40, << 50 or << 60). This specifies the end of
memory to the kernel. This affects the possible placement of
an initrd, since an initrd should be placed near end of
memory. Note that this is an option to *both* the kernel and
the bootloader!
@ -428,7 +482,7 @@ In our example from above, we would do:
/* Set up the real-mode kernel stack */
_SS = seg;
_SP = 0x9000; /* Load SP immediately after loading SS! */
_SP = heap_end;
_DS = _ES = _FS = _GS = seg;
jmp_far(seg+0x20, 0); /* Run the kernel */
@ -460,8 +514,9 @@ IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
code32_start:
A 32-bit flat-mode routine *jumped* to immediately after the
transition to protected mode, but before the kernel is
uncompressed. No segments, except CS, are set up; you should
set them up to KERNEL_DS (0x18) yourself.
uncompressed. No segments, except CS, are guaranteed to be
set up (current kernels do, but older ones do not); you should
set them up to BOOT_DS (0x18) yourself.
After completing your hook, you should jump to the address
that was in this field before your boot loader overwrote it.