[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Details

There are three main aspects of the boot loader/OS image interface:

  1. The format of the OS image as seen by the boot loader.

  2. The state of the machine when the boot loader starts the operating system.

  3. The format of the information passed by the boot loader to the operating system.

4.1 OS image format  
4.2 Machine state  
4.3 Boot information format  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 OS image format

An OS image is generally just an ordinary 32-bit executable file in the standard format for that particular operating system, except that it may be linked at a non-default load address to avoid loading on top of the PC's I/O region or other reserved areas, and of course it can't use shared libraries or other fancy features.

Unfortunately, the exact meaning of the text, data, bss, and entry fields of a.out headers tends to vary widely between different executable flavors, and it is sometimes very difficult to distinguish one flavor from another (e.g. Linux ZMAGIC executables and Mach ZMAGIC executables). Furthermore, there is no simple, reliable way of determining at what address in memory the text segment is supposed to start. Therefore, this specification requires that an additional header, known as a Multiboot header, appear somewhere near the beginning of the executable file. In general it should come as early as possible, and is typically embedded in the beginning of the text segment after the real executable header. It must be contained completely within the first 8192 bytes of the executable file, and must be longword (32-bit) aligned. These rules allow the boot loader to find and synchronize with the text segment in the a.out file without knowing beforehand the details of the a.out variant. The layout of the header is as follows:

 
        +-------------------+
0       | magic: 0x1BADB002 |   (required)
4       | flags             |   (required)
8       | checksum          |   (required)
        +-------------------+
12      | header_addr       |   (present if flags[16] is set)
16      | load_addr         |   (present if flags[16] is set)
20      | load_end_addr     |   (present if flags[16] is set)
24      | bss_end_addr      |   (present if flags[16] is set)
28      | entry_addr        |   (present if flags[16] is set)
        +-------------------+
32      | mode_type         |   (present if flags[2] is set)
36      | width             |   (present if flags[2] is set)
40      | height            |   (present if flags[2] is set)
44      | depth             |   (present if flags[2] is set)
        +-------------------+

All fields are in little-endian byte order, of course. The first field is the magic number identifying the header, which must be the hex value 0x1BADB002.

The `flags' field specifies features that the OS image requests or requires of the boot loader. Bits 0-15 indicate requirements; if the boot loader sees any of these bits set but doesn't understand the flag or can't fulfill the requirements it indicates for some reason, it must notify the user and fail to load the OS image. Bits 16-31 indicate optional features; if any bits in this range are set but the boot loader doesn't understand them, it can simply ignore them and proceed as usual. Naturally, all as-yet-undefined bits in the `flags' word must be set to zero in OS images. This way, the `flags' fields serves for version control as well as simple feature selection.

If bit 0 in the `flags' word is set, then all boot modules loaded along with the operating system must be aligned on page (4KB) boundaries. Some operating systems expect to be able to map the pages containing boot modules directly into a paged address space during startup, and thus need the boot modules to be page-aligned.

If bit 1 in the `flags' word is set, then information on available memory via at least the `mem_*' fields of the Multiboot information structure (see section 4.3 Boot information format) must be included. If the bootloader is capable of passing a memory map (the `mmap_*' fields) and one exists, then it must be included as well.

If bit 2 in the `flags' word is set, information about the video mode table, defined later, must be available to the kernel.

Also, information about a preferred default mode can be specified in the `mode_type', `width', `height' and `depth' fields. This is only a recommended mode by the kernel. If the mode exists, the boot loader should set it if the user hasn't specified a mode. If not, it should fall back to a similar mode, if available.

Valid numbers for `mode_type' is 0 for linear graphics mode and 1 for EGA-standard text mode. Everything else is reserved for future expansion. Please note that even if you set this field to indicate that you want a graphics mode, you might get a text mode.

`width' and `height' is specified in pixels, if graphics mode, or characters in EGA text mode. `depth' is given in bits per pixel for graphics, or zero for EGA text modes.

Any, some or all of those three fields may be set to zero, indicating to the boot loader that no preference is given. This makes it possible for a kernel to just say it wants a 32-bit resolution, for example.

If bit 16 in the `flags' word is set, then the fields at offsets 8-24 in the Multiboot header are valid, and the boot loader should use them instead of the fields in the actual executable header to calculate where to load the OS image. This information does not need to be provided if the kernel image is in ELF format, but it must be provided if the images is in a.out format or in some other format. Compliant boot loaders must be able to load images that either are in ELF format or contain the load address information embedded in the Multiboot header; they may also directly support other executable formats, such as particular a.out variants, but are not required to.

All of the address fields enabled by flag bit 16 are physical addresses. The meaning of each is as follows:

header_addr
Contains the address corresponding to the beginning of the Multiboot header -- the physical memory location at which the magic value is supposed to be loaded. This field serves to synchronize the mapping between OS image offsets and physical memory addresses.

load_addr
Contains the physical address of the beginning of the text segment. The offset in the OS image file at which to start loading is defined by the offset at which the header was found, minus (header_addr - load_addr). load_addr must be less than or equal to header_addr.

load_end_addr
Contains the physical address of the end of the data segment. (load_end_addr - load_addr) specifies how much data to load. This implies that the text and data segments must be consecutive in the OS image; this is true for existing a.out executable formats.

bss_end_addr
Contains the physical address of the end of the bss segment. The boot loader initializes this area to zero, and reserves the memory it occupies to avoid placing boot modules and other data relevant to the operating system in that area.

entry_addr
The physical address to which the boot loader should jump in order to start running the operating system.

The checksum is a 32-bit unsigned value which, when added to the other required fields, must have a 32-bit unsigned sum of zero.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Machine state

When the boot loader invokes the 32-bit operating system, the machine must have the following state:

All other processor registers and flag bits are undefined. This includes, in particular:

However, other machine state should be left by the boot loader in normal working order, i.e. as initialized by the BIOS (or DOS, if that's what the boot loader runs from). In other words, the operating system should be able to make BIOS calls and such after being loaded, as long as it does not overwrite the BIOS data structures before doing so. Also, the boot loader must leave the PIC programmed with the normal BIOS/DOS values, even if it changed them during the switch to 32-bit mode.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Boot information format

Upon entry to the operating system, the EBX register contains the physical address of a Multiboot information data structure, through which the boot loader communicates vital information to the operating system. The operating system can use or ignore any parts of the structure as it chooses; all information passed by the boot loader is advisory only.

The Multiboot information structure and its related substructures may be placed anywhere in memory by the boot loader (with the exception of the memory reserved for the kernel and boot modules, of course). It is the operating system's responsibility to avoid overwriting this memory until it is done using it.

The format of the Multiboot information structure (as defined so far) follows:

 
        +-------------------+
0       | flags             |    (required)
        +-------------------+
4       | mem_lower         |    (present if flags[0] is set)
8       | mem_upper         |    (present if flags[0] is set)
        +-------------------+
12      | boot_device       |    (present if flags[1] is set)
        +-------------------+
16      | cmdline           |    (present if flags[2] is set)
        +-------------------+
20      | mods_count        |    (present if flags[3] is set)
24      | mods_addr         |    (present if flags[3] is set)
        +-------------------+
28 - 40 | syms              |    (present if flags[4] or
        |                   |                flags[5] is set)
        +-------------------+
44      | mmap_length       |    (present if flags[6] is set)
48      | mmap_addr         |    (present if flags[6] is set)
        +-------------------+
52      | drives_count      |    (present if flags[7] is set)
56      | drives_addr       |    (present if flags[7] is set)
        +-------------------+
60      | config_table      |    (present if flags[8] is set)
        +-------------------+
64      | boot_loader_name  |    (present if flags[9] is set)
        +-------------------+
68 - ?? | apm_table         |    (present if flags[10] is set)
        +-------------------+
?? - ?? | graphics_table    |    (present if flags[11] is set)
        +-------------------+

The first longword indicates the presence and validity of other fields in the Multiboot information structure. All as-yet-undefined bits must be set to zero by the boot loader. Any set bits that the operating system does not understand should be ignored. Thus, the `flags' field also functions as a version indicator, allowing the Multiboot information structure to be expanded in the future without breaking anything.

If bit 0 in the `flags' word is set, then the `mem_*' fields are valid. `mem_lower' and `mem_upper' indicate the amount of lower and upper memory, respectively, in kilobytes. Lower memory starts at address 0, and upper memory starts at address 1 megabyte. The maximum possible value for lower memory is 640 kilobytes. The value returned for upper memory is maximally the address of the first upper memory hole minus 1 megabyte. It is not guaranteed to be this value.

If bit 1 in the `flags' word is set, then the `boot_device' field is valid, and indicates which BIOS disk device the boot loader loaded the OS image from. If the OS image was not loaded from a BIOS disk, then this field must not be present (bit 3 must be clear). The operating system may use this field as a hint for determining its own root device, but is not required to. The `boot_device' field is laid out in four one-byte subfields as follows:

 
+-------+-------+-------+-------+
| drive | part1 | part2 | part3 |
+-------+-------+-------+-------+

The first byte contains the BIOS drive number as understood by the BIOS INT 0x13 low-level disk interface: e.g. 0x00 for the first floppy disk or 0x80 for the first hard disk.

The three remaining bytes specify the boot partition. `part1' specifies the top-level partition number, `part2' specifies a sub-partition in the top-level partition, etc. Partition numbers always start from zero. Unused partition bytes must be set to 0xFF. For example, if the disk is partitioned using a simple one-level DOS partitioning scheme, then `part1' contains the DOS partition number, and `part2' and `part3' are both 0xFF. As another example, if a disk is partitioned first into DOS partitions, and then one of those DOS partitions is subdivided into several BSD partitions using BSD's disklabel strategy, then `part1' contains the DOS partition number, `part2' contains the BSD sub-partition within that DOS partition, and `part3' is 0xFF.

DOS extended partitions are indicated as partition numbers starting from 4 and increasing, rather than as nested sub-partitions, even though the underlying disk layout of extended partitions is hierarchical in nature. For example, if the boot loader boots from the second extended partition on a disk partitioned in conventional DOS style, then `part1' will be 5, and `part2' and `part3' will both be 0xFF.

If bit 2 of the `flags' longword is set, the `cmdline' field is valid, and contains the physical address of the command line to be passed to the kernel. The command line is a normal C-style zero-terminated string.

If bit 3 of the `flags' is set, then the `mods' fields indicate to the kernel what boot modules were loaded along with the kernel image, and where they can be found. `mods_count' contains the number of modules loaded; `mods_addr' contains the physical address of the first module structure. `mods_count' may be zero, indicating no boot modules were loaded, even if bit 1 of `flags' is set. Each module structure is formatted as follows:

 
        +-------------------+
0       | mod_start         |
4       | mod_end           |
        +-------------------+
8       | string            |
        +-------------------+
12      | reserved (0)      |
        +-------------------+

The first two fields contain the start and end addresses of the boot module itself. The `string' field provides an arbitrary string to be associated with that particular boot module; it is a zero-terminated ASCII string, just like the kernel command line. The `string' field may be 0 if there is no string associated with the module. Typically the string might be a command line (e.g. if the operating system treats boot modules as executable programs), or a pathname (e.g. if the operating system treats boot modules as files in a file system), but its exact use is specific to the operating system. The `reserved' field must be set to 0 by the boot loader and ignored by the operating system.

Caution: Bits 4 & 5 are mutually exclusive.

If bit 4 in the `flags' word is set, then the following fields in the Multiboot information structure starting at byte 28 are valid:

 
        +-------------------+
28      | tabsize           |
32      | strsize           |
36      | addr              |
40      | reserved (0)      |
        +-------------------+

These indicate where the symbol table from an a.out kernel image can be found. `addr' is the physical address of the size (4-byte unsigned long) of an array of a.out format nlist structures, followed immediately by the array itself, then the size (4-byte unsigned long) of a set of zero-terminated ASCII strings (plus sizeof(unsigned long) in this case), and finally the set of strings itself. `tabsize' is equal to its size parameter (found at the beginning of the symbol section), and `strsize' is equal to its size parameter (found at the beginning of the string section) of the following string table to which the symbol table refers. Note that `tabsize' may be 0, indicating no symbols, even if bit 4 in the `flags' word is set.

If bit 5 in the `flags' word is set, then the following fields in the Multiboot information structure starting at byte 28 are valid:

 
        +-------------------+
28      | num               |
32      | size              |
36      | addr              |
40      | shndx             |
        +-------------------+

These indicate where the section header table from an ELF kernel is, the size of each entry, number of entries, and the string table used as the index of names. They correspond to the `shdr_*' entries (`shdr_num', etc.) in the Executable and Linkable Format (ELF) specification in the program header. All sections are loaded, and the physical address fields of the ELF section header then refer to where the sections are in memory (refer to the i386 ELF documentation for details as to how to read the section header(s)). Note that `shdr_num' may be 0, indicating no symbols, even if bit 5 in the `flags' word is set.

If bit 6 in the `flags' word is set, then the `mmap_*' fields are valid, and indicate the address and length of a buffer containing a memory map of the machine provided by the BIOS. `mmap_addr' is the address, and `mmap_length' is the total size of the buffer. The buffer consists of one or more of the following size/structure pairs (`size' is really used for skipping to the next pair):

 
        +-------------------+
-4      | size              |
        +-------------------+
0       | base_addr_low     |
4       | base_addr_high    |
8       | length_low        |
12      | length_high       |
16      | type              |
        +-------------------+

where `size' is the size of the associated structure in bytes, which can be greater than the minimum of 20 bytes. `base_addr_low' is the lower 32 bits of the starting address, and `base_addr_high' is the upper 32 bits, for a total of a 64-bit starting address. `length_low' is the lower 32 bits of the size of the memory region in bytes, and `length_high' is the upper 32 bits, for a total of a 64-bit length. `type' is the variety of address range represented, where a value of 1 indicates available RAM, and all other values currently indicated a reserved area.

The map provided is guaranteed to list all standard RAM that should be available for normal use.

If bit 7 in the `flags' is set, then the `drives_*' fields are valid, and indicate the address of the physical address of the first drive structure and the number of drive structures. `drives_addr' is the address, and `drives_count' is the number. `drives_count' may be zero. Each drive structure is formatted as follows:

 
        +-------------------+
0       | drive_number      |
        +-------------------+
1       | drive_mode        |
        +-------------------+
2       | drive_cylinders   |
4       | drive_heads       |
5       | drive_sectors     |
        +-------------------+
6       | drive_ports       |
        +-------------------+
10      | reserved (0)      |
        +-------------------+

The `drive_number' field contains the BIOS drive number. The `drive_mode' field represents the access mode used by the boot loader. Currently, the following modes are defined:

`0'
CHS mode (traditional cylinder/head/sector addressing mode).

`1'
LBA mode (Logical Block Addressing mode).

The three fields, `drive_cylinders', `drive_heads' and `drive_sectors', indicate the geometry of the drive detected by the BIOS. `drive_cylinders' contains the number of the cylinders. `drive_heads' contains the number of the heads. `drive_sectors' contains the number of the sectors per track.

The `drive_ports' field contains the physical address of the array of the I/O ports used for the drive in the BIOS code. The array consists of zero or more unsigned two-bytes integers, and is terminated with zero. Note that the array may contain any number of I/O ports that are not related to the drive actually (such as DMA controller's ports).

The last field `reserved' is reserved for future use, and must be zero. The size is four bytes.

If bit 8 in the `flags' is set, then the `config_table' field is valid, and indicates the address of the ROM configuration table returned by the GET CONFIGURATION BIOS call. If the BIOS call fails, then the size of the table must be zero.

If bit 9 in the `flags' is set, the `boot_loader_name' field is valid, and contains the physical address of the name of the boot loader booting the kernel. The name is a normal C-style zero-terminated string.

If bit 11 in the `flags' is set, video mode information is available in the mode table. This should only be done if the kernel has indicated in the `Multiboot Header' that it accepts graphics modes.

The mode table looks like this:

 
        +----------------------+
0       | mode_type            |
4       | width                |
8       | height               |
12      | depth                |
16      | frame_buffer_address |
        +----------------------+

Valid numbers for `mode_type' is 0 for linear graphics mode and 1 for EGA-standard text mode. Everything else is reserved for future expansion.

`width' and `height' is specified in pixels, if graphics mode, or characters in EGA text mode. `depth' is given in bits per pixel for graphics, or unused for EGA text mode.

`frame_buffer_address' specifies the physical start address of the linear frame buffer. This is valid for both graphics and text modes.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by root on February, 25 2001 using texi2html