Commit de372ecd authored by H. Peter Anvin's avatar H. Peter Anvin Committed by Linus Torvalds

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: default avatarH. Peter Anvin <hpa@zytor.com>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent d5f9f942
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
---------------------------- ----------------------------
H. Peter Anvin <hpa@zytor.com> 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 On the i386 platform, the Linux kernel uses a rather complicated boot
convention. This has evolved partially due to historical aspects, as 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 ...@@ -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 expectations in the PC industry caused by the effective demise of
real-mode DOS as a mainstream operating system. 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 Old kernels: zImage/Image support only. Some very early kernels
may not even support a command line. may not even support a command line.
...@@ -183,9 +183,9 @@ filled out, however: ...@@ -183,9 +183,9 @@ filled out, however:
a version number. Otherwise, enter 0xFF here. a version number. Otherwise, enter 0xFF here.
Assigned boot loader ids: Assigned boot loader ids:
0 LILO 0 LILO (0x00 reserved for pre-2.00 bootloader)
1 Loadlin 1 Loadlin
2 bootsect-loader 2 bootsect-loader (0x20, all other values reserved)
3 SYSLINUX 3 SYSLINUX
4 EtherBoot 4 EtherBoot
5 ELILO 5 ELILO
...@@ -210,6 +210,9 @@ filled out, however: ...@@ -210,6 +210,9 @@ filled out, however:
additional data (such as the kernel command line) moved in additional data (such as the kernel command line) moved in
addition to the real-mode kernel itself. addition to the real-mode kernel itself.
The unit is bytes starting with the beginning of the boot
sector.
ramdisk_image, ramdisk_size: ramdisk_image, ramdisk_size:
If your boot loader has loaded an initial ramdisk (initrd), If your boot loader has loaded an initial ramdisk (initrd),
set ramdisk_image to the 32-bit pointer to the ramdisk data set ramdisk_image to the 32-bit pointer to the ramdisk data
...@@ -278,14 +281,54 @@ command line is entered using the following protocol: ...@@ -278,14 +281,54 @@ command line is entered using the following protocol:
field. 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 **** SAMPLE BOOT CONFIGURATION
As a sample configuration, assume the following layout of the real As a sample configuration, assume the following layout of the real
mode segment (this is a typical, and recommended layout): mode segment:
When loading below 0x90000, use the entire segment:
0x0000-0x7fff Real mode kernel
0x8000-0xdfff Stack and heap
0xe000-0xffff Kernel command line
0x0000-0x7FFF Real mode kernel When loading at 0x90000 OR the protocol version is 2.01 or earlier:
0x8000-0x8FFF Stack and heap
0x9000-0x90FF Kernel command line 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: 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: ...@@ -301,22 +344,33 @@ Such a boot loader should enter the following fields in the header:
ramdisk_image = <initrd_address>; ramdisk_image = <initrd_address>;
ramdisk_size = <initrd_size>; ramdisk_size = <initrd_size>;
} }
if ( protocol >= 0x0202 && loadflags & 0x01 )
heap_end = 0xe000;
else
heap_end = 0x9800;
if ( protocol >= 0x0201 ) { if ( protocol >= 0x0201 ) {
heap_end_ptr = 0x9000 - 0x200; heap_end_ptr = heap_end - 0x200;
loadflags |= 0x80; /* CAN_USE_HEAP */ loadflags |= 0x80; /* CAN_USE_HEAP */
} }
if ( protocol >= 0x0202 ) { if ( protocol >= 0x0202 ) {
cmd_line_ptr = base_ptr + 0x9000; cmd_line_ptr = base_ptr + heap_end;
strcpy(cmd_line_ptr, cmdline);
} else { } else {
cmd_line_magic = 0xA33F; cmd_line_magic = 0xA33F;
cmd_line_offset = 0x9000; cmd_line_offset = heap_end;
setup_move_size = 0x9100; setup_move_size = heap_end + strlen(cmdline)+1;
strcpy(base_ptr+cmd_line_offset, cmdline);
} }
} else { } else {
/* Very old kernel */ /* Very old kernel */
heap_end = 0x9800;
cmd_line_magic = 0xA33F; cmd_line_magic = 0xA33F;
cmd_line_offset = 0x9000; cmd_line_offset = heap_end;
/* A very old kernel MUST have its real-mode code /* A very old kernel MUST have its real-mode code
loaded at 0x90000 */ loaded at 0x90000 */
...@@ -324,12 +378,11 @@ Such a boot loader should enter the following fields in the header: ...@@ -324,12 +378,11 @@ Such a boot loader should enter the following fields in the header:
if ( base_ptr != 0x90000 ) { if ( base_ptr != 0x90000 ) {
/* Copy the real-mode kernel */ /* Copy the real-mode kernel */
memcpy(0x90000, base_ptr, (setup_sects+1)*512); memcpy(0x90000, base_ptr, (setup_sects+1)*512);
/* Copy the command line */
memcpy(0x99000, base_ptr+0x9000, 256);
base_ptr = 0x90000; /* Relocated */ base_ptr = 0x90000; /* Relocated */
} }
strcpy(0x90000+cmd_line_offset, cmdline);
/* It is recommended to clear memory up to the 32K mark */ /* It is recommended to clear memory up to the 32K mark */
memset(0x90000 + (setup_sects+1)*512, 0, memset(0x90000 + (setup_sects+1)*512, 0,
(64-(setup_sects+1))*512); (64-(setup_sects+1))*512);
...@@ -375,10 +428,11 @@ conflict with actual kernel options now or in the future. ...@@ -375,10 +428,11 @@ conflict with actual kernel options now or in the future.
line is parsed. line is parsed.
mem=<size> mem=<size>
<size> is an integer in C notation optionally followed by K, M <size> is an integer in C notation optionally followed by
or G (meaning << 10, << 20 or << 30). This specifies the end (case insensitive) K, M, G, T, P or E (meaning << 10, << 20,
of memory to the kernel. This affects the possible placement << 30, << 40, << 50 or << 60). This specifies the end of
of an initrd, since an initrd should be placed near 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 memory. Note that this is an option to *both* the kernel and
the bootloader! the bootloader!
...@@ -428,7 +482,7 @@ In our example from above, we would do: ...@@ -428,7 +482,7 @@ In our example from above, we would do:
/* Set up the real-mode kernel stack */ /* Set up the real-mode kernel stack */
_SS = seg; _SS = seg;
_SP = 0x9000; /* Load SP immediately after loading SS! */ _SP = heap_end;
_DS = _ES = _FS = _GS = seg; _DS = _ES = _FS = _GS = seg;
jmp_far(seg+0x20, 0); /* Run the kernel */ jmp_far(seg+0x20, 0); /* Run the kernel */
...@@ -460,8 +514,9 @@ IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and ...@@ -460,8 +514,9 @@ IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
code32_start: code32_start:
A 32-bit flat-mode routine *jumped* to immediately after the A 32-bit flat-mode routine *jumped* to immediately after the
transition to protected mode, but before the kernel is transition to protected mode, but before the kernel is
uncompressed. No segments, except CS, are set up; you should uncompressed. No segments, except CS, are guaranteed to be
set them up to KERNEL_DS (0x18) yourself. 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 After completing your hook, you should jump to the address
that was in this field before your boot loader overwrote it. that was in this field before your boot loader overwrote it.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment