docs/grub.texi

\input texinfo  @c -*-texinfo-*-
@setfilename grub.info
@include version.texi

@c Unify all our little indices for now.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@dircategory Kernel
@direntry
* GRUB: (grub).                 The GRand Unified Bootloader.
@end direntry

@ifinfo
Copyright @copyright{} 1996 Erich Boleyn
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

@c @setchapternewpage odd
@settitle GRUB Manual
@titlepage
@finalout
@title The GRUB Manual
@author Gordon Matzigkeit
@author OKUJI Yoshinori
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1996 Erich Boleyn
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

@c The Top node appears only in Info.
@ifinfo

@node Top
@top GRUB

This file documents GNU GRUB, the Grand Unified Bootloader.  This
edition documents version @value{VERSION}.

@menu
* Introduction::                Capturing the spirit of GRUB.
* Installing::                  How to install GRUB on your computer.
* Using::                       Booting your operating systems.
* Filesystems::                 Filesystem syntax and semantics.
* Troubleshooting::             Error messages produced by GRUB.
* Hacking::                     Implementation details.
* Index::                       Index.

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

Introduction

* History::                     From maggot to house fly.
* Features::                    How GRUB is different.
* Role of a bootloader::        Judging a system by its bootloader.

How to install GRUB on your computer

* Boot floppy::                 Creating a GRUB boot floppy.
* Automated install::           Installation via @code{install=}.
* Installation under Unix::     Installation by @file{/sbin/grub}.

Booting your operating systems

* Command-line::                The flexible command-line interface.
* Menu::                        The simple menu interface.
* Menu entry editor::           Editing a menu entry.
* Commands::                    The list of available commands.

Filesystem syntax and semantics

* Device syntax::               How to specify devices.
* Filename syntax::             How to specify files.

Error messages reported by GRUB

* Stage1 errors::               Errors reported by the Stage 1.
* Stage1.5 errors::             Errors reported by the Stage 1.5.
* Stage2 errors::               Errors reported by the Stage 2.

Implementation details

* Memory map::                  The memory map of the various
                                components.
* Embedded data::               Embedded variables in GRUB.
* Memory detection::            How to detect all installed @sc{ram}.
* Low-level disk I/O::          INT 13H disk I/O interrupts.
* MBR::                         The structure of Master Boot Record.
* Partition table::             The format of partition table.

@end detailmenu
@end menu

@end ifinfo


@node Introduction
@chapter Introduction

Briefly, a @dfn{bootloader} is the first software program that runs when
a computer starts.  It is responsible for loading and transferring
control to the operating system @dfn{kernel} software (such as the Linux
or Hurd kernels).  The kernel, in turn, initializes the rest of the
operating system (usually GNU).

@menu
* History::                     From maggot to house fly.
* Features::                    How GRUB is different.
* Role of a bootloader::        Judging a system by its bootloader.
@end menu


@node History
@section History of GRUB

GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
Hurd with the University of Utah's Mach 4 microkernel (now known as GNU
Mach).  Erich and Brian Ford designed the Multiboot Standard
(@pxref{Top, Multiboot Standard, Motivation, multiboot, The Multiboot
Standard}), because they were determined not to add to the large number
of mutually-incompatible PC boot methods.

Erich then began modifying the FreeBSD bootloader so that it would
understand Multiboot.  He quickly realized that it would be a lot easier
to write his own bootloader from scratch than to keep working on the
FreeBSD bootloader, and so GRUB was born.

Erich added many features to GRUB, but other priorities prevented him
from keeping up with the demands of its quickly-expanding user base.  In
1999, Gordon Matzigkeit and OKUJI Yoshinori adopted GRUB as an official
GNU package, and opened its development by making the latest sources
available via anonymous CVS.@footnote{The repository is
@code{:pserver:anoncvs@@anoncvs.gnu.org:/gd/gnu/anoncvsroot}, module
@code{grub}.  Just hit return when prompted for a password.}


@node Features
@section GRUB features

The primary requirement for GRUB is that it be compliant with the
@dfn{Multiboot Standard}, which is described in @ref{Top, Multiboot
Standard, Motivation, multiboot, The Multiboot Standard}.

The other goals, listed in approximate order of importance, are:

@itemize
@item
Basic functions must be easy for an end-user to use.

@item
Rich functionality for OS experts/designers.

@item
Compatibility for booting FreeBSD, NetBSD, OpenBSD, and
Linux. Proprietary OS's such as DOS, Windows NT, and OS/2 are supported
via a chain-loading function.
@end itemize

Except for specific compatibility modes (chain-loading and the Linux
@dfn{piggyback} format), all kernels will be started in much the same
state as in the Multiboot Standard listed above. Only kernels being
loaded at 1 megabyte or above are presently supported. Any attempt to
load below that boundary will simply result in immediate failure and an
error message reporting the problem.

In addition to the requirements above, GRUB has the following features
(note that the Multiboot Standard doesn't explicitly require everything
listed in it, but GRUB will support all options):

@table @asis
@item Multiple Executable Formats
Supports many of the @dfn{a.out} variants plus @dfn{ELF}. Any symbol
table present is also loaded.

@item Supports Non-Multiboot OS's
Supports many of the various free 32-bit OS's prior to any Multiboot
compliance. Chiefly FreeBSD, NetBSD, OpenBSD, and Linux. Chain-loading
is also supported.

@item Loads Multiples Modules
Multiboot feature of loading multiple modules is fully supported.

@item Configuration File
Supports a human-readable text configuration file with preset boot
commands. The list of commands (@pxref{Commands}) are a superset of
those supported on the command-line. An example command-file is provided
under the directory @file{docs/} in the source tree.

@item Menu Interface
A menu-interface listing the preset boot commands, with a programmable
timeout, is available. There is no fixed limit on the number of boot
command-set entries, and should have space for several hundred.

@item Flexible Command-Line Interface
A fairly flexible command-line interface, accessible from the menu, is
available to edit any preset commands, or simply start a new command-set
from scratch. The list of commands (@pxref{Commands}) are a subset of
those supported for command-files. Editing commands closely resemble the
BASH shell command-line (@pxref{Command Line Editing, BASH, Command Line
Editing, features, Bash Features}), with @key{TAB}-completion-listing
(it doesn't perform the completion, just lists the possibilities) of
commands, devices, partitions, and files in a directory depending on
context. If no config file is present, it goes into the command-line.

@item Multiple Filesystem Types
Supports multiple filesystem types transparently, plus an explicitly
usable block-list notation. The currently supported filesystem types are
@dfn{BSD FFS}, @dfn{DOS FAT}, and @dfn{Linux
ext2fs}. @xref{Filesystems}, for more information.

@item Decompression Support
Can decompress files which were compressed with using
@command{gzip}. This function is both automatic and transparent to the
user (i.e. all functions operate normally upon the uncompressed contents
of the files in question). This is a win on 2 fronts, as it both greatly
reduces file size and loading time (there are a few pathological cases
where loading a very badly organized ELF kernel might make it take
longer, but IMO you'll never see this in practice), a particularly major
win for floppies. It is conceivable that some kernel modules should be
loaded in a compressed state, so a variant of the modules loading
command which doesn't uncompress them can be used.

@item Access Data on Any Installed Device
Supports reading data from any or all floppy or hard disk(s) recognized
by the BIOS, independent of the setting for the root partition.

@item Geometry Translation-Independent
Subject to the constraint that it cannot go past the end of the
geometry-translated area of a drive, the particular translation used is
generally irrelevant. This implies a drive installed and running on a
controller with one translation in use may in general be moved to
another controller with a different translation (or the translation
settings on the first controller, if configurable, may be changed) with
no adverse effects and no other changes necessary.

@item Detects All Installed @sc{ram}
GRUB can generally find all the installed @sc{ram} on a PC-compatible
machine. It uses the BIOS query technique (@pxref{Memory detection}). As
described on the Multiboot Standard (@pxref{Top, Multiboot Standard,
Motivation, multiboot, The Multiboot Standard}), OS's which only use the
lower and upper memory values (whose presence is determined by bit 0 of
the flags word passed to the OS) may not be capable of receiving
information on all of installed memory. On most machines, upper memory
is contiguous, so the problem does not arise.

@item Supports Logical Block Address Mode
In traditional disk calls (called @dfn{CHS mode}), there is a geometry
translation problem, that is, the BIOS cannot access over 1024
cylinders, so the accessible space is limited to at least 508 MB and to
at most 8GB. GRUB can't universally solve this problem, as there is no
new interface which is used in all machines. However, some newer
machines have the new interface, Logical Block Address (LBA) mode. So
GRUB will automatically detect if LBA mode is available and use it if
available. In LBA mode, GRUB can access the whole of your disk space.
@end table

Future directions might include an internal programming language for
supporting richer sets of boot options with control statements (it
becomes a boot-script at that point), and possibly support for non-IBM
PC-compatible machines@footnote{There is a port to NEC PC-98xx
series. See
@url{http://www.kuis.kyoto-u.ac.jp/~kmc/proj/linux98/arch/i386/boot/grub98/},
for more information.}.


@node Role of a bootloader
@section The role of a bootloader

The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:

@quotation
Some people like to acknowledge both the operating system and kernel when
they talk about their computers, so they might say they use
``GNU/Linux'' or ``GNU/Hurd''.  Other people seem to think that the
kernel is the most important part of the system, so they like to call
their GNU operating systems ``Linux systems.''

I, personally, believe that this is a grave injustice, because the
@emph{bootloader} is the most important software of all.  I used to
refer to the above systems as either ``LILO''@footnote{The LInux LOader,
a bootloader that everybody uses, but nobody likes.} or ``GRUB''
systems.

Unfortunately, nobody ever understood what I was talking about; now I
just use the word ``GNU'' as a pseudonym for GRUB.

So, if you ever hear people talking about their alleged ``GNU'' systems,
remember that they are actually paying homage to the best bootloader
around@dots{} GRUB!
@end quotation

We, the GRUB maintainers, do not (usually) encourage Gordon's level of
fanaticism, but it helps to remember that bootloaders deserve careful
design.  We hope at least that you enjoy using GNU GRUB as much as we
did writing it.


@node Installing
@chapter How to install GRUB on your computer

Due to the nature of a @dfn{bootloader}, you need to install GRUB on
bootable media, such as a floppy disk. The installation can be performed
by @code{dd} or @code{rawrite} for a boot floppy, or the @code{install=}
command at the GRUB command line (@pxref{Using}).

@menu
* Boot floppy::                 Creating a GRUB boot floppy.
* Automated install::           Installation via @code{install=}.
* Installation under Unix::     Installation by @file{/sbin/grub}.
@end menu


@node Boot floppy
@section Creating a GRUB boot floppy

@quotation
@strong{Caution:} This procedure will destroy any data currently stored
on the floppy.
@end quotation

If you install GRUB using this method, it will only have access to the
command-line interface, since there is no filesystem in which to find a
configuration file (FIXME: ref). If you want to use the menu interface, see
@ref{Automated install}.

Under an UNIX-like operating system, such as GNU, use @code{dd} as
follows, where @file{/dev/fd0} is the floppy device:

@example
dd if=stage1/stage1 of=/dev/fd0 bs=512 count=1
dd if=stage2/stage2 of=/dev/fd0 bs=512 seek=1
@end example

Under DOS-based systems, such as Windows, use @code{copy} and
@code{rawrite}:

@example
copy /b stage1 + stage2 grub.raw
rawrite grub.new a:
@end example

@code{rawrite} is available as a part of the installation tools that
come with many GNU and GNU/Linux distributions.


@node Automated install
@section Installation via the @code{install=} command

@quotation
@strong{Caution:} Installing GRUB's stage1 in this manner will erase the
normal boot-sector used by an OS.  GRUB can boot GNU Mach, Linux,
FreeBSD, NetBSD, and OpenBSD directly, so this may be
desired.  Generally, it is a good idea to back up the first sector of the
partition on which you are installing GRUB's stage1.  This isn't as
important if you are installing GRUB on the first sector of a hard disk,
since it's easy to reinitialize it (by running @code{FDISK /MBR} from DOS).
@end quotation

GRUB has a command called @code{install=} which is described in
@xref{Using}. The purpose of this section is to give examples and
describe how to use the command in different situations.

First, make a GRUB boot floppy (@pxref{Boot floppy}).  This is simply a
way to get the process started easily; any bootable copy of the same
version GRUB will work fine.

Then, make a @file{/boot/grub} directory (@file{\boot\grub} under DOS)
in the @dfn{install partition}.  Place the GRUB @file{stage2} file, any
optional @file{stage1.5} files, and the configuration file
(@file{menu.lst}) in that directory.

Now figure out how to use the @code{install=} command appropriately, and
you're done!

Examples of how to use the @code{install=} command:

@itemize @bullet
@item
@strong{Make a hard disk bootable with GRUB's stage2 on PC partition
number 2:} Make a directory in the partition called @file{/boot/grub},
place the @file{stage2} (and if desired, your configuration file called
@file{menu.lst}), then run the following command at GRUB's command line
(after booting from the GRUB floppy):

@example
install= (fd0)+1 (hd0) (hd0,2)/boot/grub/stage2 0x8000 p
@end example

This tells GRUB to grab the first sector of the floppy and use it as the
stage1, create a block-list using the file @file{/boot/grub/stage2} on
the first hard disk (partition number 2), merge them together, set the
load address correctly for a stage2 (0x8000), save the @dfn{install
partition} in the first sector of the stage2 (the @samp{p} at the end),
then write the result to the first sector of the hard disk.

@item
@strong{Same as above, but place the stage1 on the floppy, then have
it start the stage2 on the hard disk:} The difference here is you're
telling GRUB's stage1 to read from the first hard disk no matter where
the stage1 was loaded from:

@example
install= (fd0)+1 d (fd0) (hd0,2)/boot/grub/stage2 0x8000 p
@end example

The @samp{d} option near the beginning is what sets the @emph{forced}
loading from the disk where the stage2 was installed from.  Also, the
@dfn{destination device} is changed to place the finished stage1 on the
floppy disk.

@item
@strong{Installing from an @emph{install directory} to the second hard
disk:} Here we're loading the stage1 from a file on the first hard disk,
installing stage2 from the first BSD @samp{a} partition on the second
hard disk, and setting the stage2's @dfn{configuration file} to
@file{(hd1,a)/grubdir/configfile}:

@example
install= (hd0,2)/boot/grub/stage1 (hd1) (hd1,a)/boot/grub/stage2 0x8000 p /grubdir/configfile
@end example
@end itemize

You can automate these steps by using a GRUB floppy with a filesystem
and a configuration file which contains entries such as:

@example
# Start of entries
title= GNU/Linux installation

# install command
install= (fd0)+1 (hd0) (hd0,1)/boot/grub/stage2 0x8000 p

# actually boot here
root= (hd0,1)
kernel= /zImage root=/dev/hda2
@end example

@dots{} then have the install script continue from there after boot of
the OS.


@node Installation under Unix
@section Installation by @file{/sbin/grub}

FIXME


@node Using
@chapter Booting your operating system

GRUB has both a simple menu interface for choosing preset entries from a
configuration file, and a highly flexible command-line for performing
any desired combination of boot commands.

GRUB looks for its configuration file as soon as it is loaded.  If one
is found, then the full menu interface is activated using whatever
entries were found in the file.  If you choose the `command line' menu
option, or if the configuration file was not found, then GRUB drops into
the command-line interface.

@menu
* Command-line::                The flexible command-line interface.
* Menu::                        The simple menu interface.
* Menu entry editor::           Editing a menu entry.
* Commands::                    The list of available commands.
@end menu


@node Command-line
@section The flexible command-line interface

The command-line interface provides a prompt and after it an editable
text area much like a command-line in Unix or DOS. Each command is
immediately executed after it is entered @footnote{However, this
behavior will be changed in the future version, in an user-invisible
way.}. The commands are a subset of those available in the configuration
file, used with exactly the same syntax.

@c The list of available keys should be listed in @table, and should be
@c explained exactly. Current explanation is obscure.
Cursor movement and editing of the text on the line can be done via a
subset of the functions available in the BASH (FIXME: ref) shell
(@kbd{C-f} forward, @kbd{C-b} backward, @kbd{C-a} beginning of line,
@kbd{C-e} end of line, @kbd{C-k} delete to end, @kbd{C-u} delete to
beginning; the PC left and right arrow keys, @key{HOME}, @key{DEL}, and
@key{END} work as well).

When typing commands interactively, if the cursor is before the @samp{=}
character in a command being typed, pressing the @key{TAB} key will
display a listing of the available commands, and if the cursor is after
the @samp{=} character, the @key{TAB} will provide a completion listing
of disks, partitions, and filenames depending on the context.
@c But I want to stop this stupid hack and provide more BASH-like
@c interface. I don't think commands ending with @samp{=} are
@c beautiful.


@node Menu
@section The simple menu interface

The menu interface is quite easy to use.  It's commands are both
reasonably intuitive and described on screen.

Basically, the menu interface provides a list of @dfn{boot
configurations} to the user to choose from.  Use the arrow keys to
select the entry of choice, then press @key{RET} to run it.  An optional
timeout is available to boot the default entry (the first one if not
set), which is aborted by pressing any key.

Commands are available to enter a bare command-line (operating exactly
like the non-config-file version of GRUB, but allowing one to return to
the menu if desired) or to edit any of the @dfn{boot configurations},
respectively by pressing @key{c} or @key{e}.


@node Menu entry editor
@section Editing a menu entry

This looks much like the main menu interface, but with the lines in the
menu being individual commands of the selected configuration instead of
configuration names.

If an @key{ESC} is pressed in the editor, it aborts all the changes made
to the configuration entry and goes back to the main menu interface.

When a particular line is selected, then it places the user in a special
version of the command-line for editing that line.  When the user is
finished, GRUB replaces the line in question in the @dfn{boot
configuration} with the changes (unless it was aborted via @key{ESC},
and in that case the changes are thrown away).


@node Commands
@section The list of available commands

In this section, we list the available commands, both in the
configuration file and in the command-line.

The configuration file should follow these rules:

@enumerate
@item
The configuration file specific commands have to be used before any
others.

@item
A multiboot kernel must be loaded before modules can be.

@item
A kernel must be loaded before either the configuration file entry ends,
or any @samp{boot} command is issued in any case.
@end enumerate

The semantics are as follows:

@itemize @bullet
@item
The files @emph{must} be in plain-text format.

@item
@samp{#} at the beginning of a line means it is a comment line in a
configuration file only.

@item
Options are separated by spaces.

@item
All numbers can be either decimal or hexadecimal. A hexadecimal number
must be preceded by @samp{0x}, and is case insensitive.

@item
Extra options/text at the end of the line is ignored unless otherwise
specified.

@item
Bad commands generally get included in the current entry being added to,
except before entries start, where they are ignored.
@end itemize

Commands usable in configuration files only.

@table @code
@item timeout= @var{sec}
Set a timeout, in @var{sec} seconds, before automatically booting the
default entry (normally the first entry defined).

@item default= @var{num}
Set the default entry to entry number @var{num} (otherwise it is 0, the
first entry).

@item fallback= @var{num}
Go into unattended boot mode: if the default boot entry has any errors,
instead of waiting for the user to do anything, it immediately starts
over using the @var{num} entry (same numbering as the @code{default=}
command). This obviously doesn't help if the machine was in the middle
of the boot process (after leaving GRUB's code) and rebooted.

@item password= @var{passwd} @var{new_config_file}
Disable all interactive editing control (menu entry editor and
command-line). If the password @var{passwd} is entered, it loads the
@var{new_config_file} as a new config file and restarts the GRUB Stage
2.

@item title= @dots{}
Start a new menu entry, and set its name to the contents of the rest of
the line, starting with the first non-space character.
@end table

Commands usable in configuration files and interactively.

@table @code
@item pause= @dots{}
Print the entirety to the end of its line, then wait until a key is
pressed. Note that placing a ^G in it will cause the speaker to emit the
standard beep sound, which is useful when asking the user to change
floppies, etc.

@item uppermem= @var{kbytes}
Force GRUB to ignore what it found during the autoprobe of the memory
available to the system, and to use @var{kbytes} as the number of
kilobytes of upper memory installed. Any address range maps of the
system are discarded.

@strong{Caution:} This should be used with great caution, and should
only be necessary on some old machines. GRUB's BIOS probe can pick up
all @sc{ram} on all new machines the author has ever heard of. It can
also be used for debugging purposes to lie to an OS.

@item root= @var{device} [@var{hdbias}]
Set the current @dfn{root partition} to the device @var{device}, then
attempt to mount it to get the partition size (for passing the partition
descriptor in @code{ES:ESI}, used by some chain-loaded bootloaders), the
BSD drive-type (for booting BSD kernels using their native boot format),
and fix up automatic determination of the PC partition where a BSD
sub-partition is located. The optional @var{hdbias} parameter is a
number to tell a kernel which is using one of the BSD boot methodologies
how many BIOS drive numbers are on controllers before the current
one. An example is if there is an IDE disk and a SCSI disk, then set the
root partition normally, except for a kernel using a BSD boot
methodology (FreeBSD or NetBSD), then use a @samp{1} for @var{hdbias}.

@item rootnoverify= @var{device} [@var{hdbias}]
Similar to @command{root=}, but don't attempt to mount the
partition. This is useful for when an OS is outside of the area of the
disk that GRUB can read, but setting the correct root partition is still
desired. Note that the items mentioned in @command{root=} above which
derived from attempting the mount will NOT work correctly.

@item chainloader= @var{file}
Load @var{file} as a chain-loader. Like any other file loaded by the
filesystem code, it can use the block-list notation to grab the first
sector of the current partition with @samp{+1}.

@item kernel= @var{file} @dots{}
Attempt to load the primary boot image (Multiboot a.out or @sc{elf},
Linux zImage or bzImage, FreeBSD-a.out, or NetBSD-a.out) from
@var{file}. This command ignores the rest of the contents of the line,
except that the entire line starting with the kernel filename is passed
verbatim as the @dfn{kernel command-line}. The module state is reset by
this (i.e. reload any modules).

@item module= @var{file} @dots{}
Load a boot module for a Multiboot format boot image (no interpretation
of the file contents are made, so that user of this command/writer of
the configuration file must know what the kernel in question works
with). The rest of the line is passed as the @dfn{module command-line}
much like with the @command{kernel=} command.

@item modulenounzip= @var{file} @dots{}
Exactly like @command{module=}, except that automatic decompress is
disabled.

@item initrd= @var{file} @dots{}
Load an initial ramdisk for a Linux format boot image and set the
appropriate parameters in the Linux setup area in memory.

@item install= @var{stage1_file} [d] @var{dest_dev} @var{file} @var{addr} [p] [@var{config_file}]
This command is fairly complex, and for detailed examples one should
look at @ref{Automated install}. In short, it will perform a full
install presuming the stage1.5 or stage2 (they're loaded the same way,
I'll just refer to it as a stage2 from now on) is in its final install
location (pretty much all other edits are performed by the
@command{install=} command).

In slightly more detail, it will load @var{stage1_file}, validate that
it is a GRUB stage1 of the right version number, install block-list for
loading @var{file} (if the option @samp{d} is present, the stage1 will
always look for the actual disk @var{file} was installed on, rather than
using the booting drive) as a stage2 into memory at address
@var{addr} (for a stage1.5, an address of @samp{0x2000} should be
used, and for a stage2, an address of @samp{0x8000} should be used),
then write the completed stage1 to the first block of the device
@var{dest_dev}. If the options @samp{p} or @var{config_file} are
present, then it reads the first block of stage2, modifies it with the
values of the partition @var{file} was found on (for @samp{p}) or places
the string @var{config_file} into the area telling the stage2 where to
look for a configuration file at boot time. Finally, it preserves the
DOS BPB (and for hard disks, the partition table) of the sector the
stage1 is to be installed into.

@item makeactive
Set the active partition on the root disk to GRUB's root partition (on a
floppy this is a NO-OP). This is limited to working with @emph{primary}
PC partitions.

@item boot
This boots the OS/chain-loader which has been loaded. Only necessary if
running the fully interactive command-line (it is implicit at the end of
a config-file entry).
@end table

Commands usable in configuration files and interactively which are only
available in the debug version of the GRUB Stage 2.

@table @code
@item testload= @var{file}
Read the entire contents of @var{file} in several different ways and
compares them, to test the filesystem code. The output is somewhat
cryptic (see the @samp{T} subcommand of @command{syscmd=} below), but if
no errors are reported and the part right at the end which reads
@samp{i=@var{X}, filepos=@var{Y}} has @var{X} and @var{Y} equal, then it
is definitely consistent, and very likely works correctly subject to a
consistent offset error. A good idea if this works is then to try
loading a kernel with your code.

@item read= @var{addr}
Read a 32-bit unsigned value at address @var{addr} and displays it in
hex format.

@item displaymem
Display what GRUB thinks the system address space map of the machine is,
including all regions of physical @sc{ram} installed. The
@dfn{upper/lower memory} thing GRUB has uses the standard BIOS
interface for the available memory in the first megabyte, or @dfn{lower
memory}, and a synthesized number from various BIOS interfaces of the
memory starting at 1MB and going up to the first chipset hole for
@dfn{upper memory} (the standard PC @dfn{upper memory} interface is
limited to reporting a maximum of 64MB).

@item impsprobe
Probe Intel MPS spec 1.1 or 1.4 configuration table and boot the various
other CPUs which are found into a tight loop.

@item fstest
Toggle filesystem test mode.

Filesystem test mode, when turned on, prints out data corresponding to
all the device reads and what values are being sent to the low-level
routines. The format is @samp{<@var{sector}, @var{byte_offset},
@var{byte_len}>} for high-level reads inside a partition (so
@var{sector} is an offset from the start of the partition), and
@samp{[@var{sector}]} for low-level sector requests from the disk (so
@var{sector} is offset from the start of the disk).

Filesystem test mode is turned off by any uses of the @command{install=}
or @command{testload=} commands.
@end table


@node Filesystems
@chapter Filesystem syntax and semantics

GRUB uses special syntax for specifying disk drives, that can be
accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
IDE, ESDI, SCSI, etc. So you must know which BIOS device is equivalent
to which OS device.

@menu
* Device syntax::               How to specify devices.
* Filename syntax::             How to specify files.
@end menu


@node Device syntax
@section How to specify devices

The device syntax is like this:

@example
@code{(@var{bios_device}[,@var{part_num}][,@var{bsd_subpart_letter}])}
@end example

@samp{[]} means the parameter is optional. @var{bios_device} should be
either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}.
But you can also set @var{bios_device} to a hexadecimal or a decimal,
which is a BIOS drive number, so these are equivalent:

@example
(hd0)
(0x80)
(128)
@end example

@var{part_num} represents the partition number of @var{bios_device},
starting from zero, and @var{bsd_subpart_letter} represents the BSD
sub-partition, like @samp{a} or @samp{e}.

A shortcut for specifying BSD sub-partitions is
@code{(@var{bios_device},@var{bsd_subpart_letter})}, in this case, GRUB
searches for the first PC partition containing BSD sub-partitions, then
finds the sub-partition @var{bsd_subpart_letter}. Here is an example:

@example
(hd0,a)
@end example


@node Filename syntax
@section How to specify files

There are two ways to specify files, @dfn{absolute pathname} and
@dfn{block-list}.

Absolute pathname resembles a Unix absolute pathname. Use @samp{/} for
the directory separator but not @samp{\} like DOS. For example,
@samp{/boot/grub/menu.lst}.

Block-list is used for specifying a file that doesn't appear in the
filesystem, like a chain-loader. The syntax is a bit complex, like this:

@example
@code{1+100,200+1,300+300}
@end example

This represents that GRUB should read 100 blocks from the offset 1, 1
block from the offset 200, and 300 blocks from the offset 300. The
offset is counted from the start of a partition, so the length must be
within the partition size. If you omit a offset, then GRUB assumes the
offset is zero.


@node Troubleshooting
@chapter Error messages reported by GRUB

This chapter describes the meanings of the error messages reported by
GRUB when you encounter some troubles.

@menu
* Stage1 errors::               Errors reported by the Stage 1.
* Stage1.5 errors::             Errors reported by the Stage 1.5.
* Stage2 errors::               Errors reported by the Stage 2.
@end menu


@node Stage1 errors
@section Errors reported by the Stage 1

The general way that the Stage 1 handles errors is to print an error
string and then halt. Pressing @kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will
reboot.

The following is a comprehensive list of error messages for the Stage 1:

@table @asis
@item Hard Disk Error
This error message will occur if the Stage 2 or Stage 1.5 is being read
from a hard disk, and the attempt to determine the size and geometry of
the hard disk fails.

@item Floppy Error
This error message will occur if the Stage 2 or Stage 1.5 is being read
from a floppy disk, and the attempt to determine the size and geometry
of the floppy disk fails. It's listed as a different error since the
probe sequence is different than for hard disks.

@item Read Error
This error message will occur if a disk read error happens while trying
to read the Stage 2 or Stage 1.5.

@item Geom Error
This error message will occur if the location of the Stage 2 or Stage
1.5 is not in the area supported by reading the disk with the BIOS
directly. This could occur because the BIOS translated geometry has been
changed by the user or the disk is moved to another machine or
controller after installation, or GRUB was not installed using itself
(if it was, the Stage 2 version of this error would have been seen
during that process and it would not have completed the install).
@end table


@node Stage1.5 errors
@section Errors reported by the Stage 1.5

The general way that the Stage 1.5 handles errors is to print an error
number in the form @code{Error: @var{num}} and then halt. Pressing
@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will reboot.

The error numbers correspond to the @ref{Stage2 errors} in the listed
sequence.


@node Stage2 errors
@section Errors reported by the Stage 2

The general way that the Stage 2 handles errors is to abort the
operation in question, print an error string, then (if possible) either
continue based on the fact that an error occurred or wait for the user to
deal with the error.

The following is a comprehensive list of error messages for the Stage 2
(error numbers for the Stage 1.5 are listed before the colon in each
description):

@table @asis
@item 1 : Selected item won't fit into memory
This error is returned if a kernel, module, or raw file load command is
either trying to load its data such that it won't fit into memory or it
is simply too big.

@item 2 : Selected disk doesn't exist
This error is returned if the device part of a device- or full filename
refers to a disk or BIOS device that is not present or not recognized by
the BIOS in the system.

@item 3 : Disk read error
This error is returned if there is a disk read error when trying to
probe or read data from a particular disk.

@item 4 : Disk write error
This error is returned if there is a disk write error when trying to
write to a particular disk. This would generally only occur during an
install of set active partition command.

@item 5 : Disk geometry error
This error is returned when a read is attempted at a linear block
address beyond the end of the BIOS translated area. This generally
happens if your disk is larger than the BIOS can handle (512MB for
(E)IDE disks on older machines or larger than 8GB in general).

@item 6 : Attempt to access block outside partition
This error is returned if a linear block address is outside of the disk
partition. This generally happens because of a corrupt filesystem on the
disk or a bug in the code handling it in GRUB (it's a great debugging
tool).

@item 7 : Partition table invalid or corrupt
This error s returned if the sanity checks on the integrity of the
partition table fail. This is a bad sign.

@item 8 : No such partition
This error is returned if a partition is requested in the device part of
a device- or full filename which isn't on the selected disk.

@item 9 : Bad filename (must be absolute pathname or blocklist)
This error is returned if a filename is requested which doesn't fit the
syntax/rules listed in the @ref{Filesystems}.

@item 10 : Bad file or directory type
This error is returned if a file requested is not a regular file, but
something like a symbolic link, directory, or FIFO.

@item 11 : File not found
This error is returned if the specified filename cannot be found, but
everything else (like the disk/partition info) is OK.

@item 12 : Cannot mount selected partition
This error is returned if the partition requested exists, but the
filesystem type cannot be recognized by GRUB.

@item 13 : Inconsistent filesystem structure
This error is returned by the filesystem code to denote an internal
error caused by the sanity checks of the filesystem structure on disk
not matching what it expects. This is usually caused by a corrupt
filesystem or bugs in the code handling it in GRUB.

@item 14 : Filesystem compatibility error, can't read whole file
Some of the filesystem reading code in GRUB has limits on the length of
the files it can read. This error is returned when the user runs into
such a limit.

@item 15 : Error while parsing number
This error is returned if GRUB was expecting to read a number and
encountered bad data.

@item 16 : Device string unrecognizable
This error is returned if a device string was expected, and the string
encountered didn't fit the syntax/rules listed in the @ref{Filesystems}.

@item 17 : Invalid device requested
This error is returned if a device string is recognizable but does not
fall under the other device errors.

@item 18 : Invalid or unsupported executable format
This error is returned if the kernel image being loaded is not
recognized as Multiboot or one of the supported native formats (Linux
zImage or bzImage, FreeBSD, or NetBSD).

@item 19 : Loading below 1MB is not supported
This error is returned if the lowest address in a kernel is below the
1MB boundary. The Linux zImage format is a special case and can be
handled since it has a fixed loading address and maximum size.

@item 20 : Unsupported Multiboot features requested
This error is returned when the Multiboot features word in the Multiboot
header requires a feature that is not recognized. The point of this is
that the kernel requires special handling which GRUB is likely usable to
provide.

@item 21 : Unknown boot failure
This error is returned if the boot attempt did not succeed for reasons
which are unknown.

@item 22 : Must load Multiboot kernel before modules
This error is returned if the module load command is used before loading
a Multiboot kernel. It only makes sense in this case anyway, as GRUB has
no idea how to communicate the presence of location of such modules to a
non-Multiboot-aware kernel.

@item 23 : Must load Linux kernel before initrd
This error is returned if the initrd command is used before loading a
Linux kernel. Similar to the above error, it only makes sense in that
case anyway.

@item 24 : Cannot boot without kernel loaded
This error is returned if GRUB is told to execute the boot sequence
without having a kernel to start.

@item 25 : Unrecognized command
This error is returned if an unrecognized command is entered into the
command-line or in a boot sequence section of a configuration file and
that entry is selected.

@item 26 : Bad or incompatible header on compressed file
This error is returned if the file header for a supposedly compressed
file is bad.

@item 27 : Bad or corrupt data while decompressing file
This error is returned the run-length decompression code gets an
internal error. This is usually from a corrupt file.

@item 28 : Bad or corrupt version of stage1/stage2
This error is returned if the install command is pointed to incompatible
or corrupt versions of the stage1 or stage2. It can't detect corruption
in general, but this is a sanity check on the version numbers, which
should be correct.
@end table


@node Hacking
@chapter Implementation details

This chapter describes the GRUB internals so that developers can
understand the implementation and start to hack GRUB. Of course, the
source code has the complete information, so refer to it when you are
not satisfied with this documentation.

@menu
* Memory map::                  The memory map of the various
                                components.
* Embedded data::               Embedded variables in GRUB.
* Memory detection::            How to detect all installed @sc{ram}.
* Low-level disk I/O::          INT 13H disk I/O interrupts.
* MBR::                         The structure of Master Boot Record.
* Partition table::             The format of partition table.
@end menu


@node Memory map
@section The memory map of various components

GRUB is broken into 2 distinct components, or @dfn{stages}, which are
loaded at different times in the boot process. The Stage 1 has to know
where to find Stage 2, and the Stage 2 has to know where to find its
configuration file (if Stage 2 doesn't have a configuration file, it
drops into the command-line interface and waits for a user command).

Here is the memory map of the various components
@footnote{Currently GRUB does not use the extended memory for itself,
since it is used to load an operating system. But we are planning to use
it for GRUB itself in the future by @dfn{lazy loading}. Ask okuji for
more information.}:

@table @asis
@item 0 to 4K-1
Interrupt & BIOS area

@item down from 8K-1
16-bit stack area

@item 8K to (ebss1.5)
Stage 1.5 (optionally) loaded here by Stage 1

@item 0x7c00 to 0x7dff
Stage 1 loaded here by the BIOS

@item 0x7e00 to 0x7e08
Scratch space used by Stage 1

@item 32K to (ebss2)
Stage 2 loaded here by Stage 1.5 or Stage 1

@item (middle area)
Heap used for random memory allocation

@item down from 416K-1
32-bit stack area

@item 416K to 448K-1
Filesystem info buffer (when reading a filesystem)

@item 448K to 479.5K-1
BIOS track read buffer

@item 479.5K to 480K-1
512 byte fixed SCRATCH area

@item 480K to 511K-1
General storage heap
@end table


@node Embedded data
@section Embedded variables in GRUB

GRUB's stage1 and stage2 have embedded variables whose locations are
well-defined, so that the installation can patch the binary file
directly without recompilation of the modules.

In stage1, these are defined (The number in the parenthesis of each
entry is an offset number):

@table @asis
@item @dfn{major version} (0x1bc)
This is the major version byte (should be 2).

@item @dfn{minor version} (0x1bd)
This is the minor version byte (should be 0).

@item @dfn{stage2 start address} (0x1b8)
This is the data for the @code{ljmp} command to the starting address of
the component loaded by the stage1. The format is two 2-byte words: the
first is the IP, and the second is the CS segment register (remember,
we're in x86 real-mode@dots{} 16-bit instruction pointer and segment
registers shifted left by 4bits).

A @dfn{stage1.5} should be loaded at address 0x2000, and a @dfn{stage2}
should be loaded at address 0x8000. Both use a CS of 0.

@item @dfn{firstlist} (0x1b05)
This is the @emph{ending} address of the block-list data area.

The trick here is that it is actually read backward, and the first
8-byte block-list is not read here, but after the pointer is decremented
8 bytes, then after reading it, it decrements again, reads, decrements,
reads, etc. until it is finished.  The terminating condition is when the
number of sectors to be read in the next block-list is 0.

The format of a block-list can be seen from the example in the code just
before the @code{firstlist} label.  (note that it is always from the
beginning of the disk, and @emph{not} relative to the partition
boundaries)

@item @dfn{loading drive} (0x1b05)
This is the BIOS drive number to load the block-lists from. If the number
is 0xff, then load from the booting drive.
@end table

In stage1.5 and stage2 (these are all defined at the beginning of
@file{shared_src/asm.S}):

@table @asis
@item @dfn{major version} (0x6)
This is the major version byte (should be 2).

@item @dfn{minor version} (0x7)
This is the minor version byte (should be 0).

@item @dfn{install_partition} (0x8)
This is an unsigned long representing the partition on the currently
booted disk which GRUB should expect to find it's data files and treat
as the default root partition.

The format of is exactly the same as the @dfn{partition} part (the
@dfn{disk} part is ignored) of the data passed to an OS by a
Multiboot-compliant bootloader in the @dfn{boot_device} data element,
with one exception.

The exception is that if the first level of disk partitioning is left as
0xFF (decimal 255, which is marked as no partitioning being used), but
the second level does have a partition number, it looks for the first
BSD-style PC partition, and finds the numbered BSD sub-partition in it.
The default @dfn{install_partition} 0xFF00FF, would then find the first
BSD-style PC partition, and use the @samp{a} partition in it, and
0xFF01FF would use the @samp{b} partition, etc.

If an explicit first-level partition is given, then no search is
performed, and it will expect that the BSD-style PC partition is in the
appropriate location, else a @samp{no such partition} error will be
returned.

If a @dfn{stage1.5} is being used, it will pass its own
@dfn{install_partition} to any @dfn{stage2} it loads, therefore
overwriting the one present in the @dfn{stage2}.

@item @dfn{version_string} (0xc)
This is the @dfn{stage1.5} or @dfn{stage2} version string. It isn't
meant to be changed, simply easy to find.

@item @dfn{config_file} (after the terminating zero of @dfn{version_string})
This is the location, using the GRUB filesystem syntax, of the config
file.  It will, by default, look in the @dfn{install_partition} of the
disk GRUB was loaded from, though one can use any valid GRUB filesystem
string, up to and including making it look on other disks.

The bootloader itself doesn't search for the end of
@dfn{version_string}, it simply knows where @dfn{config_file} is, so the
beginning of the string cannot be moved after compile-time.  This should
be OK, since the @dfn{version_string} is meant to be static.

The code of stage2 starts again at offset 0x70,	so @dfn{config_file}
string obviously can't go past there.  Also, remember to terminate the
string with a 0.
@end table


@node Memory detection
@section How to detect all installed @sc{ram}

There are three BIOS calls which return the information of installed
@sc{ram}. GRUB uses these calls to detect all installed @sc{ram} and
which address range should be treated by operating systems.

@menu
* Query System Address Map::    INT 15H, AX=E820h interrupt call.
* Get Large Memory Size::       INT 15H, AX=E801h interrupt call.
* Get Extended Memory Size::    INT 15H, AX=88h interrupt call.
@end menu


@node Query System Address Map
@subsection INT 15H, AX=E820h interrupt call

Real mode only.

This call returns a memory map of all the installed @sc{ram}, and of
physical memory ranges reserved by the BIOS. The address map is returned
by making successive calls to this API, each returning one "run" of
physical address information.  Each run has a type which dictates how
this run of physical address range should be treated by the operating
system.

If the information returned from INT 15h, AX=E820h in some way differs
from INT 15h, AX=E801h (@pxref{Get Large Memory Size}) or INT 15h AH=88h
(@pxref{Get Extended Memory Size}), then the information returned from
E820h supersedes what is returned from these older interfaces. This
allows the BIOS to return whatever information it wishes to for
compatibility reasons.

Input:

@multitable @columnfractions .15 .25 .6
@item @code{EAX} @tab Function Code @tab E820h

@item @code{EBX} @tab Continuation @tab Contains the @dfn{continuation
value} to get the next run of physical memory. This is the value
returned by a previous call to this routine. If this is the first call,
@code{EBX} must contain zero.

@item @code{ES:DI} @tab Buffer Pointer @tab Pointer to an Address Range
Descriptor structure which the BIOS is to fill in.

@item @code{ECX} @tab Buffer Size @tab The length in bytes of the
structure passed to the BIOS. The BIOS will fill in at most @code{ECX}
bytes of the structure or however much of the structure the BIOS
implements. The minimum size which must be supported by both the BIOS
and the caller is 20 bytes. Future implementations may extend this
structure.

@item @code{EDX} @tab Signature @tab @samp{SMAP} - Used by the BIOS to
verify the caller is requesting the system map information to be
returned in @code{ES:DI}.
@end multitable

Output:

@multitable @columnfractions 0.15 0.25 0.6
@item @code{CF} @tab Carry Flag @tab Non-Carry - indicates no error

@item @code{EAX} @tab Signature @tab @samp{SMAP} - Signature to verify
correct BIOS revision.

@item @code{ES:DI} @tab Buffer Pointer @tab Returned Address Range
Descriptor pointer. Same value as on input.

@item @code{ECX} @tab Buffer Size @tab Number of bytes returned by the
BIOS in the address range descriptor. The minimum size structure
returned by the BIOS is 20 bytes.

@item @code{EBX} @tab Continuation @tab Contains the continuation value
to get the next address descriptor. The actual significance of the
continuation value is up to the discretion of the BIOS. The caller must
pass the continuation value unchanged as input to the next iteration of
the E820h call in order to get the next Address Range Descriptor. A
return value of zero means that this is the last descriptor. Note that
the BIOS indicate that the last valid descriptor has been returned by
either returning a zero as the continuation value, or by returning
carry.
@end multitable

The Address Range Descriptor Structure is:

@multitable @columnfractions 0.25 0.3 0.45
@item Offset in Bytes @tab Name @tab Description

@item 0 @tab @dfn{BaseAddrLow} @tab Low 32 Bits of Base Address

@item 4 @tab @dfn{BaseAddrHigh} @tab High 32 Bits of Base Address

@item 8 @tab @dfn{LengthLow} @tab Low 32 Bits of Length in Bytes

@item 12 @tab @dfn{LengthHigh} @tab High 32 Bits of Length in Bytes

@item 16 @tab @dfn{Type} @tab Address type of this range
@end multitable

The @dfn{BaseAddrLow} and @dfn{BaseAddrHigh} together are the 64 bit
@dfn{BaseAddress} of this range. The @dfn{BaseAddress} is the physical
address of the start of the range being specified.

The @dfn{LengthLow} and @dfn{LengthHigh} together are the 64 bit
@dfn{Length} of this range. The @dfn{Length} is the physical contiguous
length in bytes of a range being specified.

The @dfn{Type} field describes the usage of the described address range
as defined in the table below:

@multitable @columnfractions 0.1 0.35 0.55
@item Value @tab Pneumonic @tab Description

@item 1 @tab @dfn{AddressRangeMemory} @tab This run is available
@sc{ram} usable by the operating system.

@item 2 @tab @dfn{AddressRangeReserved} @tab This run of addresses is in
use or reserved by the system, and must not be used by the operating
system.

@item Other @tab @dfn{Undefined} @tab Undefined - Reserved for future
use. Any range of this type must be treated by the OS as if the type
returned was @dfn{AddressRangeReserved}.
@end multitable

The BIOS can use the @dfn{AddressRangeReserved} address range type to
block out various addresses as @emph{not suitable} for use by a
programmable device.

Some of the reasons a BIOS would do this are:

@itemize @bullet
@item
The address range contains system @sc{rom}.

@item
The address range contains @sc{ram} in use by the @sc{rom}.

@item
The address range is in use by a memory mapped system device.

@item
The address range is for whatever reason are unsuitable for a
standard device to use as a device memory space.
@end itemize

Here is the list of assumptions and limitations:

@enumerate
@item
The BIOS will return address ranges describing base board memory and ISA
or PCI memory that is contiguous with that base board memory.

@item
The BIOS @emph{will not} return a range description for the memory
mapping of PCI devices. ISA Option @sc{rom}'s, and ISA plug & play
cards. This is because the OS has mechanisms available to detect them.

@item
The BIOS will return chipset defined address holes that are not being
used by devices as reserved.

@item
Address ranges defined for base board memory mapped I/O devices (for
example APICs) will be returned as reserved.

@item
All occurrences of the system BIOS will be mapped as reserved. This
includes the area below 1 MB, at 16 MB (if present) and at end of the
address space (4 GB).

@item
Standard PC address ranges will not be reported. Example video memory at
A0000 to BFFFF physical will not be described by this function. The
range from E0000 to EFFFF is base board specific and will be reported as
suits the bas board.

@item
All of lower memory is reported as normal memory. It is OS's
responsibility to handle standard @sc{ram} locations reserved for
specific uses, for example: the interrupt vector table (0:0) and the
BIOS data area (40:0).
@end enumerate

Here we explain an example address map. This sample address map
describes a machine which has 128 MB @sc{ram}, 640K of base memory and
127 MB extended.  The base memory has 639K available for the user and 1K
for an extended BIOS data area.  There is a 4 MB Linear Frame Buffer
(LFB) based at 12 MB.  The memory hole created by the chipset is from 8
M to 16 M.  There are memory mapped APIC devices in the system.  The IO
Unit is at FEC00000 and the Local Unit is at FEE00000.  The system BIOS
is remapped to 4G - 64K.

Note that the 639K endpoint of the first memory range is also the base
memory size reported in the BIOS data segment at 40:13.

Key to types: @dfn{ARM} is AddressRangeMemory, @dfn{ARR} is
AddressRangeReserved.

@multitable @columnfractions 0.15 0.1 0.1 0.65
@item Base (Hex) @tab Length @tab Type @tab Description

@item 0000 0000 @tab 639K @tab ARM @tab Available Base memory -
typically the same value as is returned via the INT 12 function.

@item 0009 FC00 @tab 1K @tab ARR @tab Memory reserved for use by the
BIOS(s). This area typically includes the Extended BIOS data area.

@item 000F 0000 @tab 64K @tab ARR @tab System BIOS.

@item 0010 0000 @tab 7M @tab ARM @tab Extended memory, this is not
limited to the 64MB address range.

@item 0080 0000 @tab 8M @tab ARR @tab Chipset memory hole required to
support the LFB mapping at 12 MB.

@item 0100 0000 @tab 120M @tab ARM @tab Base board @sc{ram} relocated
above a chipset memory hole.

@item FE00 0000 @tab 4K @tab ARR @tab IO APIC memory mapped I/O at
FEC00000. Note the range of addresses required for an APIC device may
vary from base OEM to OEM.

@item FEE0 0000 @tab 4K @tab ARR @tab Local APIC memory mapped I/O at
FEE00000.

@item FFFF 0000 @tab 64K @tab ARR @tab Remapped System BIOS at end of
address space.
@end multitable

The following code segment is intended to describe the algorithm needed
when calling the Query System Address Map function. It is an
implementation example and uses non standard mechanisms.

@example
E820Present = FALSE;
Regs.ebx = 0;
do
  @{
    Regs.eax = 0xE820;
    Regs.es = SEGMENT (&Descriptor);
    Regs.di = OFFSET (&Descriptor);
    Regs.ecx = sizeof (Descriptor);
    Regs.edx = 'SMAP';
    
    _int (0x15, Regs);
    
    if ((Regs.eflags & EFLAGS_CARRY) || Regs.eax != 'SMAP')
      @{
        break;
      @}
    
    if (Regs.ecx < 20 || Regs.ecx > sizeof (Descriptor))
      @{
        /* bug in bios - all returned descriptors must be at
           least 20 bytes long, and can not be larger than
           the input buffer.  */
        break;
      @}
    
    E820Present = TRUE;
    .
    .
    .
    Add address range Descriptor.BaseAddress through
    Descriptor.BaseAddress + Descriptor.Length
    as type Descriptor.Type
    .
    .
    .
  @}
while (Regs.ebx != 0);

if (! E820Present)
  @{
    .
    .
    .
    call INT 15H, AX E801h and/or INT 15H, AH=88h to obtain old style
    memory information
    .
    .
    .
  @}
@end example


@node Get Large Memory Size
@subsection INT 15H, AX=E801h interrupt call

Real mode only.

Originally defined for EISA servers, this interface is capable of
reporting up to 4 GB of @sc{ram}.  While not nearly as flexible as
E820h, it is present in many more systems.

Input:

@multitable @columnfractions 0.15 0.25 0.6
@item @code{AX} @tab Function Code @tab E801h
@end multitable

Output:

@multitable @columnfractions 0.15 0.25 0.6
@item @code{CF} @tab Carry Flag @tab Non-Carry - indicates no error.

@item @code{AX} @tab Extended 1 @tab Number of contiguous KB between 1
and 16 MB, maximum 0x3C00 = 15 MB.

@item @code{BX} @tab Extended 2 @tab Number of contiguous 64KB blocks
between 16 MB and 4GB.

@item @code{CX} @tab Configured 1 @tab Number of contiguous KB between 1
and 16 MB, maximum 0x3c00 = 15 MB.

@item @code{DX} @tab Configured 2 @tab Number of contiguous 64KB blocks
between 16 MB and 4 GB.
@end multitable

Not sure what this difference between the @dfn{Extended} and
@dfn{Configured} numbers are, but they appear to be identical, as
reported from the BIOS.

It is possible for a machine using this interface to report a memory
hole just under 16 MB (Count 1 is less than 15 MB, but Count 2 is
non-zero).


@node Get Extended Memory Size
@subsection INT 15H, AX=88h interrupt call

Real mode only.

This interface is quite primitive.  It returns a single value for
contiguous memory above 1 MB.  The biggest limitation is that the value
returned is a 16-bit value, in KB, so it has a maximum saturation of
just under 64 MB even presuming it returns as much as it can.  On some
systems, it won't return anything above the 16 MB boundary.

The one useful point is that it works on every PC available.

Input:

@multitable @columnfractions 0.15 0.25 0.6
@item @code{AH} @tab Function Code @tab 88h
@end multitable

Output:

@multitable @columnfractions 0.15 0.25 0.6
@item @code{CF} @tab Carry Flag @tab Non-Carry - indicates no error.

@item @code{AX} @tab Memory Count @tab Number of contiguous KB above 1
MB.
@end multitable


@node Low-level disk I/O
@section INT 13H disk I/O interrupts

PC_partitioning.txt


@node MBR
@section The structure of Master Boot Record

PC_partitioning.txt


@node Partition table
@section The format of partition table

PC_partitioning.txt


@node Index
@unnumbered Index

@c Currently, we use only the Concept Index.
@printindex cp

@contents
@bye