docs/multiboot.texi

\input texinfo @c -*-texinfo-*-
@setfilename multiboot.info

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@c
@c This file will be included from grub.texi
@c

@dircategory Kernel
@direntry
* Multiboot Standard: (multiboot).   Multiboot Standard
@end direntry

@ifinfo
Copyright @copyright{} 1999 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@settitle Multiboot Standard
@titlepage
@finalout
@title The Multiboot Standard
@author Kunihiro Ishiguro
@author OKUJI Yoshinori
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage

@ifinfo

@node Top, Motivation, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top Multiboot Standard

This file documents Multiboot Standard, the proposal for the boot
sequence standard.  This edition documents version 0.6.

@menu
* Motivation::                  
* Terminology::                 
* Scope and Requirements::      
* Details::                     
* Authors::                     
* Revision History::            
* Examples::                    
* Index::                       

@detailmenu
 --- The Detailed Node Listing ---

Scope and Requirements

* Architecture::                
* Operating systems::           
* Boot sources::                
* Boot-time configuration::     
* Convenience to the OS::       
* Boot modules::                

Details

* OS Image Format::             
* Machine State::               
* Boot Information Format::     

Examples

* Notes on PCs::                
* Example OS Code::             
* Example Bootloader Code::     

@end detailmenu
@end menu

@end ifinfo


@node Motivation, Terminology, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Motivation

Every OS ever created tends to have its own boot loader.  Installing a
new OS on a machine generally involves installing a whole new set of
boot mechanisms, each with completely different install-time and
boot-time user interfaces.  Getting multiple operating systems to
coexist reliably on one machine through typical @dfn{chaining} mechanisms
can be a nightmare.  There is little or no choice of boot loaders for a
particular operating system - if the one that comes with the OS doesn't
do exactly what you want, or doesn't work on your machine, you're
screwed.

While we may not be able to fix this problem in existing commercial
operating systems, it shouldn't be too difficult for a few people in the
free OS communities to put their heads together and solve this problem
for the popular free operating systems.  That's what this standard aims
for.  Basically, it specifies an interface between a boot loader and a
operating system, such that any complying boot loader should be able to
load any complying operating system.  This standard does @emph{not} specify how
boot loaders should work - only how they must interface with the OS
being loaded.


@node Terminology, Scope and Requirements, Motivation, Top
@comment  node-name,  next,  previous,  up
@chapter Terminology

Throughout this document, the term @dfn{boot loader} means whatever
program or set of programs loads the image of the final operating system
to be run on the machine.  The boot loader may itself consist of several
stages, but that is an implementation detail not relevant to this
standard.  Only the @emph{final} stage of the boot loader - the stage
that eventually transfers control to the OS - needs to follow the rules
specified in this document in order to be @dfn{MultiBoot compliant};
earlier boot loader stages can be designed in whatever way is most
convenient.

The term @dfn{OS image} is used to refer to the initial binary image
that the boot loader loads into memory and transfers control to to start
the OS.  The OS image is typically an executable containing the OS
kernel.

The term @dfn{boot module} refers to other auxiliary files that the boot
loader loads into memory along with the OS image, but does not interpret
in any way other than passing their locations to the OS when it is
invoked.


@node Scope and Requirements, Details, Terminology, Top
@comment  node-name,  next,  previous,  up
@chapter Scope and Requirements

@menu
* Architecture::                
* Operating systems::           
* Boot sources::                
* Boot-time configuration::     
* Convenience to the OS::       
* Boot modules::                
@end menu


@node  Architecture, Operating systems, Scope and Requirements, Scope and Requirements
@comment  node-name,  next,  previous,  up
@section Architecture

This standard is primarily targetted at PC's, since they are the most
common and have the largest variety of OS's and boot loaders.  However,
to the extent that certain other architectures may need a boot standard
and do not have one already, a variation of this standard, stripped of
the x86-specific details, could be adopted for them as well.


@node Operating systems, Boot sources, Architecture, Scope and Requirements
@comment  node-name,  next,  previous,  up
@section Operating systems

This standard is targetted toward free 32-bit operating systems that can
be fairly easily modified to support the standard without going through
lots of bureaucratic rigmarole.  The particular free OS's that this
standard is being primarily designed for are Linux, FreeBSD, NetBSD,
Mach, and VSTa.  It is hoped that other emerging free OS's will adopt it
from the start, and thus immediately be able to take advantage of
existing boot loaders.  It would be nice if commercial operating system
vendors eventually adopted this standard as well, but that's probably a
pipe dream.


@node Boot sources, Boot-time configuration, Operating systems, Scope and Requirements
@comment  node-name,  next,  previous,  up
@section Boot sources

It should be possible to write compliant boot loaders that load the OS
image from a variety of sources, including floppy disk, hard disk, and
across a network.

Disk-based boot loaders may use a variety of techniques to find the
relevant OS image and boot module data on disk, such as by
interpretation of specific file systems (e.g. the BSD/Mach boot loader),
using precalculated @dfn{block lists} (e.g. LILO), loading from a special
@dfn{boot partition} (e.g. OS/2), or even loading from within another
operating system (e.g. the VSTa boot code, which loads from DOS).
Similarly, network-based boot loaders could use a variety of network
hardware and protocols.

It is hoped that boot loaders will be created that support multiple
loading mechanisms, increasing their portability, robustness, and
user-friendliness.


@node Boot-time configuration, Convenience to the OS, Boot sources, Scope and Requirements
@comment  node-name,  next,  previous,  up
@section Boot-time configuration

It is often necessary for one reason or another for the user to be able
to provide some configuration information to the OS dynamically at boot
time.  While this standard should not dictate how this configuration
information is obtained by the boot loader, it should provide a standard
means for the boot loader to pass such information to the OS.


@node Convenience to the OS, Boot modules, Boot-time configuration, Scope and Requirements
@comment  node-name,  next,  previous,  up
@section Convenience to the OS

OS images should be easy to generate.  Ideally, an OS image should
simply be an ordinary 32-bit executable file in whatever file format the
OS normally uses.  It should be possible to @code{nm} or disassemble OS
images just like normal executables.  Specialized tools should not be
needed to create OS images in a @emph{special} file format.  If this
means shifting some work from the OS to the boot loader, that is
probably appropriate, because all the memory consumed by the boot loader
will typically be made available again after the boot process is
created, whereas every bit of code in the OS image typically has to
remain in memory forever.  The OS should not have to worry about getting
into 32-bit mode initially, because mode switching code generally needs
to be in the boot loader anyway in order to load OS data above the 1MB
boundary, and forcing the OS to do this makes creation of OS images much
more difficult.

Unfortunately, there is a horrendous variety of executable file formats
even among free Unix-like PC-based OS's - generally a different format
for each OS.  Most of the relevant free OS's use some variant of a.out
format, but some are moving to ELF.  It is highly desirable for boot
loaders not to have to be able to interpret all the different types of
executable file formats in existence in order to load the OS image -
otherwise the boot loader effectively becomes OS-specific again.

This standard adopts a compromise solution to this problem.  MultiBoot
compliant boot images always either (a) are in ELF format, or (b)
contain a @dfn{magic MultiBoot header}, described below, which allows
the boot loader to load the image without having to understand numerous
a.out variants or other executable formats.  This magic header does not
need to be at the very beginning of the executable file, so kernel
images can still conform to the local a.out format variant in addition
to being MultiBoot compliant.


@node Boot modules,  , Convenience to the OS, Scope and Requirements
@comment  node-name,  next,  previous,  up
@section Boot modules

Many modern operating system kernels, such as those of VSTa and Mach, do
not by themselves contain enough mechanism to get the system fully
operational: they require the presence of additional software modules at
boot time in order to access devices, mount file systems, etc.  While
these additional modules could be embedded in the main OS image along
with the kernel itself, and the resulting image be split apart manually
by the OS when it receives control, it is often more flexible, more
space-efficient, and more convenient to the OS and user if the boot
loader can load these additional modules independently in the first
place.

Thus, this standard should provide a standard method for a boot loader
to indicate to the OS what auxiliary boot modules were loaded, and where
they can be found.  Boot loaders don't have to support multiple boot
modules, but they are strongly encouraged to, because some OS's will be
unable to boot without them.


@node Details, Authors, Scope and Requirements, Top
@comment  node-name,  next,  previous,  up
@chapter Details

There are three main aspects of the boot-loader/OS image interface this
standard must specify:

@enumerate
@item The format of the OS image as seen by the boot loader.
@item The state of the machine when the boot loader starts the OS.
@item The format of the information passed by the boot loader to the OS.
@end enumerate

@menu
* OS Image Format::             
* Machine State::               
* Boot Information Format::     
@end menu


@node OS Image Format, Machine State, Details, Details
@comment  node-name,  next,  previous,  up
@section OS Image Format

An OS image is generally just an ordinary 32-bit executable file in the
standard format for that particular OS, 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.  Initially, only images in a.out
format are supported; ELF support will probably later be specified in
the standard.

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 standard requires that an additional header,
known as a @dfn{multiboot_header}, appear somewhere near the beginning of
the executable file.  In general it should come @emph{as early as possible},
and is typically embedded in the beginning of the text segment after the
@emph{real} executable header.  It @emph{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:

@example
@group
        +-------------------+
0       | magic: 0x1BADB002 |   (required)
4       | flags             |   (required)
8       | checksum          |   (required)
        +-------------------+
8       | header_addr       |   (present if flags[16] is set)
12      | load_addr         |   (present if flags[16] is set)
16      | load_end_addr     |   (present if flags[16] is set)
20      | bss_end_addr      |   (present if flags[16] is set)
24      | entry_addr        |   (present if flags[16] is set)
        +-------------------+
@end group
@end example

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 OS must be aligned on page (4KB) boundaries.  Some OS's 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 @samp{mem_*} fields of the multiboot_info structure defined
below must be included.  If the bootloader is capable of passing a
memory map (the @samp{mmap_*} fields) and one exists, then it must be
included as well.

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 should 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:

@table @code
@item 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 @dfn{synchronize} the
mapping between OS image offsets and physical memory addresses.

@item 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.

@item 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.

@item 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 OS
in that area.

@item entry
The physical address to which the boot loader should jump in order to
start running the OS.
@end table

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.


@node Machine State, Boot Information Format, OS Image Format, Details
@comment  node-name,  next,  previous,  up
@section Machine State

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

@itemize @bullet
@item @code{CS} must be a 32-bit read/execute code segment with an offset of 0
and a limit of 0xffffffff.

@item @code{DS}, @code{ES}, @code{FS}, @code{GS}, and @code{SS} must be a 32-bit read/write data segment with
an offset of 0 and a limit of 0xffffffff.

@item The address 20 line must be usable for standard linear 32-bit
addressing of memory (in standard PC hardware, it is wired to
0 at bootup, forcing addresses in the 1-2 MB range to be mapped to the
0-1 MB range, 3-4 is mapped to 2-3, etc.).

@item Paging must be turned off.

@item The processor interrupt flag must be turned off.

@item @code{EAX} must contain the magic value 0x2BADB002; the presence of this value
indicates to the OS that it was loaded by a MultiBoot-compliant boot
loader (e.g. as opposed to another type of boot loader that the OS can
also be loaded from).

@item @code{EBX} must contain the 32-bit physical address of the multiboot_info
structure provided by the boot loader (see below).
@end itemize

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

@itemize @bullet

@item @code{ESP}: the 32-bit OS must create its own stack as soon as it needs one.

@item @code{GDTR}: Even though the segment registers are set up as described above, the @code{GDTR} may be invalid, so the OS must not load any segment registers (even just reloading the same values!) until it sets up its own @code{GDT}.

@item @code{IDTR}: The OS must leave interrupts disabled until it sets up its own @code{IDT}.
@end itemize

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 OS 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.


@node Boot Information Format,  , Machine State, Details
@comment  node-name,  next,  previous,  up
@section Boot Information Format

Upon entry to the OS, the @code{EBX} register contains the physical
address of a 'multiboot_info' data structure, through which the boot
loader communicates vital information to the OS.  The OS can use or
ignore any parts of the structure as it chooses; all information passed
by the boot loader is advisory only.

The multiboot_info 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 OS's
responsibility to avoid overwriting this memory until it is done using it.

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

@example
@group
        +-------------------+
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)
        +-------------------+
@end group
@end example

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

If bit 0 in the multiboot_info.flags word is set, then the @samp{mem_*} fields
are valid. @samp{mem_lower} and @samp{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 multiboot_info.flags word is set, then the @samp{boot_device}
field is valid, and indicates which BIOS disk device the boot loader loaded
the OS from.  If the OS was not loaded from a BIOS disk, then this field
must not be present (bit 3 must be clear).  The OS may use this field as a
hint for determining its own @dfn{root} device, but is not required to.  The
boot_device field is layed out in four one-byte subfields as follows:

@example
@group
+-------+-------+-------+-------+
| drive | part1 | part2 | part3 |
+-------+-------+-------+-------+
@end group
@end example

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.  @samp{part1}
specifies the @dfn{top-level} partition number, @samp{part2} specifies a
@dfn{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
@samp{part1} contains the DOS partition number, and @samp{part2} and
@samp{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 @dfn{disklabel} strategy, then
@samp{part1} contains the DOS partition number, @samp{part2} contains the BSD
sub-partition within that DOS partition, and @samp{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 @samp{part1} will be 5,
and @samp{part2} and @samp{part3} will both be 0xFF.

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

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

@example
@group
        +-------------------+
0       | mod_start         |
4       | mod_end           |
        +-------------------+
8       | string            |
        +-------------------+
12      | reserved (0)      |
        +-------------------+
@end group
@end example

The first two fields contain the start and end addresses of the boot module
itself.  The @samp{string} field provides an arbitrary string to be associated
with that particular boot module; it is a null-terminated ASCII string,
just like the kernel command line.  The @samp{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 OS treats boot modules as executable programs),
or a pathname (e.g. if the OS treats boot modules as files in a file
system), but its exact use is specific to the OS.  The @samp{reserved} field
must be set to 0 by the boot loader and ignored by the OS.

@strong{Caution:} Bits 4 & 5 are mutually exclusive.

If bit 4 in the multiboot_info.flags word is set, then the following
fields in the multiboot_info structure starting at byte 28 are valid:

@example
@group
        +-------------------+
28      | tabsize           |
32      | strsize           |
36      | addr              |
40      | reserved (0)      |
        +-------------------+
@end group
@end example

These indicate where the symbol table from an a.out kernel image can be
found. @samp{addr} is the physical address of the size (4-byte unsigned
long) of an array of a.out-format @dfn{nlist} structures, followed immediately
by the array itself, then the size (4-byte unsigned long) of a set of
null-terminated ASCII strings (plus sizeof(unsigned long) in this case),
and finally the set of strings itself.  @samp{tabsize} is equal to its size
parameter (found at the beginning of the symbol section), and @samp{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
@samp{tabsize} may be 0, indicating no symbols, even if bit 4 in the flags
word is set.

If bit 5 in the multiboot_info.flags word is set, then the following
fields in the multiboot_info structure starting at byte 28 are valid:

@example
@group
        +-------------------+
28      | num               |
32      | size              |
36      | addr              |
40      | shndx             |
        +-------------------+
@end group
@end example

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 @samp{shdr_*} entries
(@samp{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 @samp{shdr_num} may be 0, indicating no symbols,
even if bit 5 in the flags word is set.

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

@example
@group
        +-------------------+
-4      | size              |
        +-------------------+
0       | BaseAddrLow       |
4       | BaseAddrHigh      |
8       | LengthLow         |
12      | LengthHigh        |
16      | Type              |
        +-------------------+
@end group
@end example

where @dfn{size} is the size of the associated structure in bytes, which
can be greater than the minimum of 20 bytes.  @dfn{BaseAddrLow} is the
lower 32 bits of the starting address, and @dfn{BaseAddrHigh} is the
upper 32 bits, for a total of a 64-bit starting address.
@dfn{LengthLow} is the lower 32 bits of the size of the memory region in
bytes, and @dfn{LengthHigh} is the upper 32 bits, for a total of a
64-bit length.  @dfn{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.


@node Authors, Revision History, Details, Top
@comment  node-name,  next,  previous,  up
@chapter Authors

@example
Bryan Ford
Computer Systems Laboratory
University of Utah
Salt Lake City, UT 84112
(801) 581-4280
baford@@cs.utah.edu
@end example

@example
Erich Stefan Boleyn
924 S.W. 16th Ave, #202
Portland, OR, USA  97205
(503) 226-0741
erich@@uruk.org
@end example

We would also like to thank the many other people have provided comments,
ideas, information, and other forms of support for our work.


@node Revision History, Examples, Authors, Top
@comment  node-name,  next,  previous,  up
@chapter Revision History

@example
Version 0.6   3/29/96  (a few wording changes, header checksum, and
                        clarification of machine state passed to the OS)
Version 0.5   2/23/96  (name change)
Version 0.4   2/1/96   (major changes plus HTMLification)
Version 0.3   12/23/95
Version 0.2   10/22/95
Version 0.1   6/26/95
@end example


@node Examples, Index, Revision History, Top
@comment  node-name,  next,  previous,  up
@chapter Examples

NOTE: The following items are not part of the standards document, but
are included for prospective OS and bootloader writers.

@menu
* Notes on PCs::                
* Example OS Code::             
* Example Bootloader Code::     
@end menu


@node Notes on PCs, Example OS Code, Examples, Examples
@comment  node-name,  next,  previous,  up
@section Notes on PCs

In reference to bit 0 of the multiboot_info.flags parameter,
if the bootloader
in question uses older BIOS interfaces, or the newest ones are not
available (see description about bit 6), then a maximum of either
15 or 63 megabytes of memory may be reported.  It is @emph{highly} recommended
that bootloaders perform a thorough memory probe.

In reference to bit 1 of the multiboot_info.flags parameter, it is
recognized that determination of which BIOS drive maps to which
OS-level device-driver is non-trivial, at best.  Many kludges have
been made to various OSes instead of solving this problem, most of
them breaking under many conditions.  To encourage the use of
general-purpose solutions to this problem, here are 2
@uref{file:bios_mapping}BIOS Device Mapping Techniques.

In reference to bit 6 of the multiboot_info.flags parameter, it is
important to note that the data structure used there (starting with
@samp{BaseAddrLow}) is the data returned by the @uref{file:mem64mb} INT 15h,
AX=E820h - Query System Address Map call.  More information on reserved
memory regions is defined on that web page.  The interface here is meant
to allow a bootloader to work unmodified with any reasonable extensions
of the BIOS interface, passing along any extra data to be interpreted by
the OS as desired.


@node Example OS Code, Example Bootloader Code, Notes on PCs, Examples
@comment  node-name,  next,  previous,  up
@section  Example OS Code

@strong{Caution:} These examples are relevant to the Proposal version 0.5,
which is basically identical except for the multiboot OS header, which was
missing the checksum.  A patch to bring Mach4 UK22 up to version 0.6 is
available in the GRUB FTP area mentioned in the
@ref{Example Bootloader Code} section below.

The Mach 4 distribution, available by anonymous FTP from
@url{ftp://flux.cs.utah.edu:/flux}, contains a C header file that defines the
MultiBoot data structures described above; anyone is welcome to rip it
out and use it for other boot loaders and OS's:

@example
mach4-i386/include/mach/machine/multiboot.h
@end example

This distribution also contains code implementing a @dfn{Linux boot
adaptor}, which collects a MultiBoot-compliant OS image and an optional
set of boot modules, compresses them, and packages them into a single
traditional Linux boot image that can be loaded from LILO or other Linux
boot loaders.  There is also a corresponding @dfn{BSD boot adaptor} which
can be used to wrap a MultiBoot kernel and set of modules and produce an
image that can be loaded from the FreeBSD and NetBSD boot loaders.  All
of this code can be used as-is or as a basis for other boot loaders.
These are the directories of primary relevance:

@example
mach4-i386/boot
mach4-i386/boot/bsd
mach4-i386/boot/linux
@end example

The Mach kernel itself in this distribution contains code that demonstrates
how to create a compliant OS.  The following files are of primary
relevance:

@example
mach4-i386/kernel/i386at/boothdr.S
mach4-i386/kernel/i386at/model_dep.c
@end example

Finally, I have created patches against the Linux 1.2.2 and FreeBSD 2.0
kernels, in order to make them compliant with this proposed standard.
These patches are available in
@url{ftp://kahlua.cs.utah.edu:/private/boot}.


@node Example Bootloader Code,  , Example OS Code, Examples
@comment  node-name,  next,  previous,  up
@section Example Bootloader Code

The GRUB bootloader project @url{http://www.uruk.org/grub/} will be
fully Multiboot-compliant, supporting all required and optional features
present in this standard.

A final release has not been made, but both the GRUB beta release (which
is quite stable) and a patch for Multiboot version 0.6 for Mach4 UK22
are available in the GRUB public release area
@url{ftp://ftp.uruk.org/public/grub/} .


@node Index,  , Examples, Top
@comment  node-name,  next,  previous,  up
@unnumbered Index

@printindex cp

@contents
@bye