Add the Multiboot Standard manual
This commit is contained in:
okuji
parent
421dbceb11
commit
bef8f221fd
1 changed files with 867 additions and 0 deletions
867
docs/multiboot.texi
Normal file
867
docs/multiboot.texi
Normal file
|
|
@ -0,0 +1,867 @@
|
|||
\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 "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
|
||||
Loading…
Add table
Add a link
Reference in a new issue