OpenSolaris_b135/grub/grub-0.97/docs/grub.info-3

This is grub.info, produced by makeinfo version 4.0 from grub.texi.

INFO-DIR-SECTION Kernel
START-INFO-DIR-ENTRY
* GRUB: (grub). The GRand Unified Bootloader
* grub-install: (grub)Invoking grub-install. Install GRUB on your drive
* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password
in MD5 format
* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo
command from a
terminfo name
* grub-set-default: (grub)Invoking grub-set-default. Set a default boot
entry
* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel
END-INFO-DIR-ENTRY

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.

File: grub.info, Node: install, Next: ioprobe, Prev: initrd, Up: Command-line and menu entry commands

install
-------

- Command: install [`--force-lba'] [`--stage2=os_stage2_file']
stage1_file [`d'] dest_dev stage2_file [addr] [`p']
[config_file] [real_config_file]
This command is fairly complex, and you should not use this command
unless you are familiar with GRUB. Use `setup' (*note setup::)
instead.

In short, it will perform a full install presuming the Stage 2 or
Stage 1.5(1) (*note install-Footnote-1::) is in its final install
location.

In slightly more detail, it will load STAGE1_FILE, validate that
it is a GRUB Stage 1 of the right version number, install in it a
blocklist for loading STAGE2_FILE as a Stage 2. If the option `d'
is present, the Stage 1 will always look for the actual disk
STAGE2_FILE was installed on, rather than using the booting drive.
The Stage 2 will be loaded at address ADDR, which must be `0x8000'
for a true Stage 2, and `0x2000' for a Stage 1.5. If ADDR is not
present, GRUB will determine the address automatically. It then
writes the completed Stage 1 to the first block of the device
DEST_DEV. If the options `p' or CONFIG_FILE are present, then it
reads the first block of stage2, modifies it with the values of
the partition STAGE2_FILE was found on (for `p') or places the
string CONFIG_FILE into the area telling the stage2 where to look
for a configuration file at boot time. Likewise, if
REAL_CONFIG_FILE is present and STAGE2_FILE is a Stage 1.5, then
the Stage 2 CONFIG_FILE is patched with the configuration file
name REAL_CONFIG_FILE. This command preserves the DOS BPB (and for
hard disks, the partition table) of the sector the Stage 1 is to
be installed into.

*Caution:* Several buggy BIOSes don't pass a booting drive
properly when booting from a hard disk drive. Therefore, you will
unfortunately have to specify the option `d', whether your Stage2
resides at the booting drive or not, if you have such a BIOS. We
know these are defective in this way:

Fujitsu LifeBook 400 BIOS version 31J0103A

HP Vectra XU 6/200 BIOS version GG.06.11

*Caution2:* A number of BIOSes don't return a correct LBA support
bitmap even if they do have the support. So GRUB provides a
solution to ignore the wrong bitmap, that is, the option
`--force-lba'. Don't use this option if you know that your BIOS
doesn't have LBA support.

*Caution3:* You must specify the option `--stage2' in the grub
shell, if you cannot unmount the filesystem where your stage2 file
resides. The argument should be the file name in your operating
system.

File: grub.info, Node: install-Footnotes, Up: install

(1) They're loaded the same way, so we will refer to the Stage 1.5
as a Stage 2 from now on.

File: grub.info, Node: ioprobe, Next: kernel, Prev: install, Up: Command-line and menu entry commands

ioprobe
-------

- Command: ioprobe drive
Probe I/O ports used for the drive DRIVE. This command will list
the I/O ports on the screen. For technical information, *Note
Internals::.

File: grub.info, Node: kernel, Next: lock, Prev: ioprobe, Up: Command-line and menu entry commands

kernel
------

- Command: kernel [`--type=type'] [`--no-mem-option'] file ...
Attempt to load the primary boot image (Multiboot a.out or ELF,
Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from
FILE. The rest of the line is passed verbatim as the "kernel
command-line". Any modules must be reloaded after using this
command.

This command also accepts the option `--type' so that you can
specify the kernel type of FILE explicitly. The argument TYPE must
be one of these: `netbsd', `freebsd', `openbsd', `linux',
`biglinux', and `multiboot'. However, you need to specify it only
if you want to load a NetBSD ELF kernel, because GRUB can
automatically determine a kernel type in the other cases, quite
safely.

The option `--no-mem-option' is effective only for Linux. If the
option is specified, GRUB doesn't pass the option `mem=' to the
kernel. This option is implied for Linux kernels 2.4.18 and newer.

File: grub.info, Node: lock, Next: makeactive, Prev: kernel, Up: Command-line and menu entry commands

lock
----

- Command: lock
Prevent normal users from executing arbitrary menu entries. You
must use the command `password' if you really want this command to
be useful (*note password::).

This command is used in a menu, as shown in this example:

title This entry is too dangerous to be executed by normal users
lock
root (hd0,a)
kernel /no-security-os

See also *Note rootnoverify::.

File: grub.info, Node: rootnoverify, Next: savedefault, Prev: root, Up: Command-line and menu entry commands

rootnoverify
------------

- Command: rootnoverify device [hdbias]
Similar to `root' (*note 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 device
is still desired. Note that the items mentioned in `root' above
which derived from attempting the mount will _not_ work correctly.

File: grub.info, Node: savedefault, Next: setup, Prev: rootnoverify, Up: Command-line and menu entry commands

savedefault
-----------

- Command: savedefault num
Save the current menu entry or NUM if specified as a default
entry. Here is an example:

default saved
timeout 10

title GNU/Linux
root (hd0,0)
kernel /boot/vmlinuz root=/dev/sda1 vga=ext
initrd /boot/initrd
savedefault

title FreeBSD
root (hd0,a)
kernel /boot/loader
savedefault

With this configuration, GRUB will choose the entry booted
previously as the default entry.

You can specify `fallback' instead of a number. Then, next
fallback entry is saved. Next fallback entry is chosen from
fallback entries. Normally, this will be the first entry in
fallback ones.

See also *Note default:: and *Note Invoking grub-set-default::.

File: grub.info, Node: setup, Next: testload, Prev: savedefault, Up: Command-line and menu entry commands

setup
-----

- Command: setup [`--force-lba'] [`--stage2=os_stage2_file']
[`--prefix=dir'] install_device [image_device]
Set up the installation of GRUB automatically. This command uses
the more flexible command `install' (*note install::) in the
backend and installs GRUB into the device INSTALL_DEVICE. If
IMAGE_DEVICE is specified, then find the GRUB images (*note
Images::) in the device IMAGE_DEVICE, otherwise use the current
"root device", which can be set by the command `root'. If
INSTALL_DEVICE is a hard disk, then embed a Stage 1.5 in the disk
if possible.

The option `--prefix' specifies the directory under which GRUB
images are put. If it is not specified, GRUB automatically
searches them in `/boot/grub' and `/grub'.

The options `--force-lba' and `--stage2' are just passed to
`install' if specified. *Note install::, for more information.

File: grub.info, Node: testload, Next: testvbe, Prev: setup, Up: Command-line and menu entry commands

testload
--------

- Command: testload file
Read the entire contents of FILE in several different ways and
compare them, to test the filesystem code. The output is somewhat
cryptic, but if no errors are reported and the final `i=X,
filepos=Y' reading has X and Y equal, then it is definitely
consistent, and very likely works correctly subject to a
consistent offset error. If this test succeeds, then a good next
step is to try loading a kernel.

File: grub.info, Node: testvbe, Next: uppermem, Prev: testload, Up: Command-line and menu entry commands

testvbe
-------

- Command: testvbe mode
Test the VESA BIOS EXTENSION mode MODE. This command will switch
your video card to the graphics mode, and show an endless
animation. Hit any key to return. See also *Note vbeprobe::.

File: grub.info, Node: uppermem, Next: vbeprobe, Prev: testvbe, Up: Command-line and menu entry commands

uppermem
--------

- Command: uppermem kbytes
Force GRUB to assume that only KBYTES kilobytes of upper memory
are installed. Any system address range maps are discarded.

*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 RAM on all new machines the author has ever heard of. It can
also be used for debugging purposes to lie to an OS.

File: grub.info, Node: vbeprobe, Prev: uppermem, Up: Command-line and menu entry commands

vbeprobe
--------

- Command: vbeprobe [mode]
Probe VESA BIOS EXTENSION information. If the mode MODE is
specified, show only the information about MODE. Otherwise, this
command lists up available VBE modes on the screen. See also *Note
testvbe::.

File: grub.info, Node: Troubleshooting, Next: Invoking the grub shell, Prev: Commands, Up: Top

Error messages reported by GRUB
*******************************

This chapter describes error messages reported by GRUB when you
encounter trouble. *Note Invoking the grub shell::, if your problem is
specific to the grub shell.

* 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

File: grub.info, Node: Stage1 errors, Next: Stage1.5 errors, Up: Troubleshooting

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 `<CTRL>-<ALT>-<DEL>' will reboot.

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

Hard Disk Error
The stage2 or stage1.5 is being read from a hard disk, and the
attempt to determine the size and geometry of the hard disk failed.

Floppy Error
The stage2 or stage1.5 is being read from a floppy disk, and the
attempt to determine the size and geometry of the floppy disk
failed. It's listed as a separate error since the probe sequence
is different than for hard disks.

Read Error
A disk read error happened while trying to read the stage2 or
stage1.5.

Geom Error
The location of the stage2 or stage1.5 is not in the portion of
the disk supported directly by the BIOS read calls. 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).

File: grub.info, Node: Stage1.5 errors, Next: Stage2 errors, Prev: Stage1 errors, Up: Troubleshooting

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 `Error NUM' and then halt. Pressing
`<CTRL>-<ALT>-<DEL>' will reboot.

The error numbers correspond to the errors reported by Stage 2.
*Note Stage2 errors::.

File: grub.info, Node: Stage2 errors, Prev: Stage1.5 errors, Up: Troubleshooting

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

1 : Filename must be either an absolute filename or blocklist
This error is returned if a file name is requested which doesn't
fit the syntax/rules listed in the *Note Filesystem::.

2 : 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.

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

4 : Bad or incompatible header in compressed file
This error is returned if the file header for a supposedly
compressed file is bad.

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

6 : Mismatched or corrupt version of stage1/stage2
This error is returned if the install command points 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.

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

8 : Kernel must be loaded before booting
This error is returned if GRUB is told to execute the boot sequence
without having a kernel to start.

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

10 : 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 probably unable to provide.

11 : Unrecognized device string
This error is returned if a device string was expected, and the
string encountered didn't fit the syntax/rules listed in the *Note
Filesystem::.

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

13 : 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).

14 : Filesystem compatibility error, cannot 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.

15 : File not found
This error is returned if the specified file name cannot be found,
but everything else (like the disk/partition info) is OK.

16 : 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.

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

18 : Selected cylinder exceeds maximum supported by BIOS
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).

19 : Linux kernel must be loaded before initrd
This error is returned if the initrd command is used before
loading a Linux kernel.

20 : Multiboot kernel must be loaded 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
such modules to a non-Multiboot-aware kernel.

21 : Selected disk does not exist
This error is returned if the device part of a device- or full
file name refers to a disk or BIOS device that is not present or
not recognized by the BIOS in the system.

22 : No such partition
This error is returned if a partition is requested in the device
part of a device- or full file name which isn't on the selected
disk.

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

24 : 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).

25 : 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.

26 : Too many symbolic links
This error is returned if the link count is beyond the maximum
(currently 5), possibly the symbolic links are looped.

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

28 : Selected item cannot 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.

29 : 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.

30 : Invalid argument
This error is returned if an argument specified to a command is
invalid.

31 : File is not sector aligned
This error may occur only when you access a ReiserFS partition by
block-lists (e.g. the command `install'). In this case, you should
mount the partition with the `-o notail' option.

32 : Must be authenticated
This error is returned if you try to run a locked entry. You should
enter a correct password before running such an entry.

33 : Serial device not configured
This error is returned if you try to change your terminal to a
serial one before initializing any serial device.

34 : No spare sectors on the disk
This error is returned if a disk doesn't have enough spare space.
This happens when you try to embed Stage 1.5 into the unused
sectors after the MBR, but the first partition starts right after
the MBR or they are used by EZ-BIOS.

File: grub.info, Node: Invoking the grub shell, Next: Invoking grub-install, Prev: Troubleshooting, Up: Top

Invoking the grub shell
***********************

This chapter documents the grub shell `grub'. Note that the grub
shell is an emulator; it doesn't run under the native environment, so it
sometimes does something wrong. Therefore, you shouldn't trust it too
much. If there is anything wrong with it, don't hesitate to try the
native GRUB environment, especially when it guesses a wrong map between
BIOS drives and OS devices.

* Menu:

* Basic usage:: How to use the grub shell
* Installation under UNIX:: How to install GRUB via `grub'
* Device map:: The map between BIOS drives and OS devices

File: grub.info, Node: Basic usage, Next: Installation under UNIX, Up: Invoking the grub shell

Introduction into the grub shell
================================

You can use the command `grub' for installing GRUB under your
operating systems and for a testbed when you add a new feature into GRUB
or when fixing a bug. `grub' is almost the same as the Stage 2, and, in
fact, it shares the source code with the Stage 2 and you can use the
same commands (*note Commands::) in `grub'. It is emulated by replacing
BIOS calls with UNIX system calls and libc functions.

The command `grub' accepts the following options:

`--help'
Print a summary of the command-line options and exit.

`--version'
Print the version number of GRUB and exit.

`--verbose'
Print some verbose messages for debugging purpose.

`--device-map=FILE'
Use the device map file FILE. The format is described in *Note
Device map::.

`--no-floppy'
Do not probe any floppy drive. This option has no effect if the
option `--device-map' is specified (*note Device map::).

`--probe-second-floppy'
Probe the second floppy drive. If this option is not specified,
the grub shell does not probe it, as that sometimes takes a long
time. If you specify the device map file (*note Device map::), the
grub shell just ignores this option.

`--config-file=FILE'
Read the configuration file FILE instead of `/boot/grub/menu.lst'.
The format is the same as the normal GRUB syntax. See *Note
Filesystem::, for more information.

`--boot-drive=DRIVE'
Set the stage2 BOOT_DRIVE to DRIVE. This argument should be an
integer (decimal, octal or hexadecimal).

`--install-partition=PAR'
Set the stage2 INSTALL_PARTITION to PAR. This argument should be
an integer (decimal, octal or hexadecimal).

`--no-config-file'
Do not use the configuration file even if it can be read.

`--no-curses'
Do not use the screen handling interface by the curses even if it
is available.

`--batch'
This option has the same meaning as `--no-config-file --no-curses'.

`--read-only'
Disable writing to any disk.

`--hold'
Wait until a debugger will attach. This option is useful when you
want to debug the startup code.

File: grub.info, Node: Installation under UNIX, Next: Device map, Prev: Basic usage, Up: Invoking the grub shell

How to install GRUB via `grub'
==============================

The installation procedure is the same as under the "native" Stage
2. *Note Installation::, for more information. The command
`grub'-specific information is described here.

What you should be careful about is "buffer cache". `grub' makes use
of raw devices instead of filesystems that your operating systems
serve, so there exists a potential problem that some cache
inconsistency may corrupt your filesystems. What we recommend is:

* If you can unmount drives to which GRUB may write any amount of
data, unmount them before running `grub'.

* If a drive cannot be unmounted but can be mounted with the
read-only flag, mount it in read-only mode. That should be secure.

* If a drive must be mounted with the read-write flag, make sure
that no activity is being done on it while the command `grub' is
running.

* Reboot your operating system as soon as possible. This is probably
not required if you follow the rules above, but reboot is the most
secure way.

In addition, enter the command `quit' when you finish the
installation. That is _very important_ because `quit' makes the buffer
cache consistent. Do not push <C-c>.

If you want to install GRUB non-interactively, specify `--batch'
option in the command-line. This is a simple example:

#!/bin/sh

# Use /usr/sbin/grub if you are on an older system.
/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
root (hd0,0)
setup (hd0)
quit
EOT

File: grub.info, Node: Device map, Prev: Installation under UNIX, Up: Invoking the grub shell

The map between BIOS drives and OS devices
==========================================

When you specify the option `--device-map' (*note Basic usage::),
the grub shell creates the "device map file" automatically unless it
already exists. The file name `/boot/grub/device.map' is preferred.

If the device map file exists, the grub shell reads it to map BIOS
drives to OS devices. This file consists of lines like this:

DEVICE FILE

DEVICE is a drive specified in the GRUB syntax (*note Device
syntax::), and FILE is an OS file, which is normally a device file.

The reason why the grub shell gives you the device map file is that
it cannot guess the map between BIOS drives and OS devices correctly in
some environments. For example, if you exchange the boot sequence
between IDE and SCSI in your BIOS, it gets the order wrong.

Thus, edit the file if the grub shell makes a mistake. You can put
any comments in the file if needed, as the grub shell assumes that a
line is just a comment if the first character is `#'.

File: grub.info, Node: Invoking grub-install, Next: Invoking grub-md5-crypt, Prev: Invoking the grub shell, Up: Top

Invoking grub-install
*********************

The program `grub-install' installs GRUB on your drive using the
grub shell (*note Invoking the grub shell::). You must specify the
device name on which you want to install GRUB, like this:

grub-install INSTALL_DEVICE

The device name INSTALL_DEVICE is an OS device name or a GRUB device
name.

`grub-install' accepts the following options:

`--help'
Print a summary of the command-line options and exit.

`--version'
Print the version number of GRUB and exit.

`--force-lba'
Force GRUB to use LBA mode even for a buggy BIOS. Use this option
only if your BIOS doesn't work properly in LBA mode even though it
supports LBA mode.

`--root-directory=DIR'
Install GRUB images under the directory DIR instead of the root
directory. This option is useful when you want to install GRUB
into a separate partition or a removable disk. Here is an example
in which you have a separate "boot" partition which is mounted on
`/boot':

grub-install --root-directory=/boot hd0

`--grub-shell=FILE'
Use FILE as the grub shell. You can append arbitrary options to
FILE after the file name, like this:

grub-install --grub-shell="grub --read-only" /dev/fd0

`--recheck'
Recheck the device map, even if `/boot/grub/device.map' already
exists. You should use this option whenever you add/remove a disk
into/from your computer.

File: grub.info, Node: Invoking grub-md5-crypt, Next: Invoking grub-terminfo, Prev: Invoking grub-install, Up: Top

Invoking grub-md5-crypt
***********************

The program `grub-md5-crypt' encrypts a password in MD5 format.
This is just a frontend of the grub shell (*note Invoking the grub
shell::). Passwords encrypted by this program can be used with the
command `password' (*note password::).

`grub-md5-crypt' accepts the following options:

`--help'
Print a summary of the command-line options and exit.

`--version'
Print the version information and exit.

`--grub-shell=FILE'
Use FILE as the grub shell.

File: grub.info, Node: Invoking grub-terminfo, Next: Invoking grub-set-default, Prev: Invoking grub-md5-crypt, Up: Top

Invoking grub-terminfo
**********************

The program `grub-terminfo' generates a terminfo command from a
terminfo name (*note terminfo::). The result can be used in the
configuration file, to define escape sequences. Because GRUB assumes
that your terminal is vt100-compatible by default, this would be useful
only if your terminal is uncommon (such as vt52).

`grub-terminfo' accepts the following options:

`--help'
Print a summary of the command-line options and exit.

`--version'
Print the version information and exit.

You must specify one argument to this command. For example:

grub-terminfo vt52

File: grub.info, Node: Invoking grub-set-default, Next: Invoking mbchk, Prev: Invoking grub-terminfo, Up: Top

Invoking grub-set-default
*************************

The program `grub-set-default' sets the default boot entry for GRUB.
This automatically creates a file named `default' under your GRUB
directory (i.e. `/boot/grub'), if it is not present. This file is used
to determine the default boot entry when GRUB boots up your system when
you use `default saved' in your configuration file (*note default::),
and to save next default boot entry when you use `savedefault' in a
boot entry (*note savedefault::).

`grub-set-default' accepts the following options:

`--help'
Print a summary of the command-line options and exit.

`--version'
Print the version information and exit.

`--root-directory=DIR'
Use the directory DIR instead of the root directory (i.e. `/') to
define the location of the default file. This is useful when you
mount a disk which is used for another system.

You must specify a single argument to `grub-set-default'. This
argument is normally the number of a default boot entry. For example,
if you have this configuration file:

default saved
timeout 10

title GNU/Hurd
root (hd0,0)
...

title GNU/Linux
root (hd0,1)
...

and if you want to set the next default boot entry to GNU/Linux, you
may execute this command:

grub-set-default 1

Because the entry for GNU/Linux is `1'. Note that entries are
counted from zero. So, if you want to specify GNU/Hurd here, then you
should specify `0'.

This feature is very useful if you want to test a new kernel or to
make your system quite robust. *Note Making your system robust::, for
more hints about how to set up a robust system.

File: grub.info, Node: Invoking mbchk, Next: Obtaining and Building GRUB, Prev: Invoking grub-set-default, Up: Top

Invoking mbchk
**************

The program `mbchk' checks for the format of a Multiboot kernel. We
recommend using this program before booting your own kernel by GRUB.

`mbchk' accepts the following options:

`--help'
Print a summary of the command-line options and exit.

`--version'
Print the version number of GRUB and exit.

`--quiet'
Suppress all normal output.

File: grub.info, Node: Obtaining and Building GRUB, Next: Reporting bugs, Prev: Invoking mbchk, Up: Top

How to obtain and build GRUB
****************************

*Caution:* GRUB requires binutils-2.9.1.0.23 or later because the
GNU assembler has been changed so that it can produce real 16bits
machine code between 2.9.1 and 2.9.1.0.x. See
`http://sources.redhat.com/binutils/', to obtain information on
how to get the latest version.

GRUB is available from the GNU alpha archive site
`ftp://alpha.gnu.org/gnu/grub' or any of its mirrors. The file will be
named grub-version.tar.gz. The current version is 0.95, so the file you
should grab is:

`ftp://alpha.gnu.org/gnu/grub/grub-0.95.tar.gz'

To unbundle GRUB use the instruction:

zcat grub-0.95.tar.gz | tar xvf -

which will create a directory called `grub-0.95' with all the
sources. You can look at the file `INSTALL' for detailed instructions
on how to build and install GRUB, but you should be able to just do:

cd grub-0.95
./configure
make install

This will install the grub shell `grub' (*note Invoking the grub
shell::), the Multiboot checker `mbchk' (*note Invoking mbchk::), and
the GRUB images. This will also install the GRUB manual.

Also, the latest version is available from the CVS. See
`http://savannah.gnu.org/cvs/?group=grub' for more information.

File: grub.info, Node: Reporting bugs, Next: Future, Prev: Obtaining and Building GRUB, Up: Top

Reporting bugs
**************

These are the guideline for how to report bugs. Take a look at this
list below before you submit bugs:

1. Before getting unsettled, read this manual through and through.
Also, see the GNU GRUB FAQ
(http://www.gnu.org/software/grub/grub-faq.html).

2. Always mention the information on your GRUB. The version number
and the configuration are quite important. If you build it
yourself, write the options specified to the configure script and
your operating system, including the versions of gcc and binutils.

3. If you have trouble with the installation, inform us of how you
installed GRUB. Don't omit error messages, if any. Just `GRUB hangs
up when it boots' is not enough.

The information on your hardware is also essential. These are
especially important: the geometries and the partition tables of
your hard disk drives and your BIOS.

4. If GRUB cannot boot your operating system, write down _everything_
you see on the screen. Don't paraphrase them, like `The foo OS
crashes with GRUB, even though it can boot with the bar boot
loader just fine'. Mention the commands you executed, the messages
printed by them, and information on your operating system
including the version number.

5. Explain what you wanted to do. It is very useful to know your
purpose and your wish, and how GRUB didn't satisfy you.

6. If you can investigate the problem yourself, please do. That will
give you and us much more information on the problem. Attaching a
patch is even better.

When you attach a patch, make the patch in unified diff format, and
write ChangeLog entries. But, even when you make a patch, don't
forget to explain the problem, so that we can understand what your
patch is for.

7. Write down anything that you think might be related. Please
understand that we often need to reproduce the same problem you
encounterred in our environment. So your information should be
sufficient for us to do the same thing--Don't forget that we
cannot see your computer directly. If you are not sure whether to
state a fact or leave it out, state it! Reporting too many things
is much better than omitting something important.

If you follow the guideline above, submit a report to the Bug
Tracking System (http://savannah.gnu.org/bugs/?group=grub).
Alternatively, you can submit a report via electronic mail to
<bug-grub@gnu.org>, but we strongly recommend that you use the Bug
Tracking System, because e-mail can be passed over easily.

Once we get your report, we will try to fix the bugs.

File: grub.info, Node: Future, Next: Internals, Prev: Reporting bugs, Up: Top

Where GRUB will go
******************

We started the next generation of GRUB, GRUB 2. This will include
internationalization, dynamic module loading, real memory management,
multiple architecture support, a scripting language, and many other
nice feature. If you are interested in the development of GRUB 2, take
a look at the homepage (http://www.gnu.org/software/grub/grub.html).

File: grub.info, Node: Internals, Next: Index, Prev: Future, Up: Top

Hacking GRUB
************

This chapter documents the user-invisible aspect of GRUB.

As a general rule of software development, it is impossible to keep
the descriptions of the internals up-to-date, and it is quite hard to
document everything. So refer to the source code, whenever you are not
satisfied with this documentation. Please assume that this gives just
hints to you.

* Menu:

* Memory map:: The memory map of various components
* Embedded data:: Embedded variables in GRUB
* Filesystem interface:: The generic interface for filesystems
* Command interface:: The generic interface for built-ins
* Bootstrap tricks:: The bootstrap mechanism used in GRUB
* I/O ports detection:: How to probe I/O ports used by INT 13H
* Memory detection:: How to detect all installed 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 tables
* Submitting patches:: Where and how you should send patches

File: grub.info, Node: Memory map, Next: Embedded data, Up: Internals

The memory map of various components
====================================

GRUB consists of two distinct components, called "stages", which are
loaded at different times in the boot process. Because they run
mutual-exclusively, sometimes a memory area overlaps with another
memory area. And, even in one stage, a single memory area can be used
for various purposes, because their usages are mutually exclusive.

Here is the memory map of the various components:

0 to 4K-1
BIOS and real mode interrupts

0x07BE to 0x07FF
Partition table passed to another boot loader

down from 8K-1
Real mode stack

0x2000 to ?
The optional Stage 1.5 is loaded here

0x2000 to 0x7FFF
Command-line buffer for Multiboot kernels and modules

0x7C00 to 0x7DFF
Stage 1 is loaded here by BIOS or another boot loader

0x7F00 to 0x7F42
LBA drive parameters

0x8000 to ?
Stage2 is loaded here

The end of Stage 2 to 416K-1
Heap, in particular used for the menu

down from 416K-1
Protected mode stack

416K to 448K-1
Filesystem buffer

448K to 479.5K-1
Raw device buffer

479.5K to 480K-1
512-byte scratch area

480K to 512K-1
Buffers for various functions, such as password, command-line, cut
and paste, and completion.

The last 1K of lower memory
Disk swapping code and data

See the file `stage2/shared.h', for more information.

File: grub.info, Node: Embedded data, Next: Filesystem interface, Prev: Memory map, Up: Internals

Embedded variables in GRUB
==========================

Stage 1 and Stage 2 have embedded variables whose locations are
well-defined, so that the installation can patch the binary file
directly without recompilation of the stages.

In Stage 1, these are defined:

`0x3E'
The version number (not GRUB's, but the installation mechanism's).

`0x40'
The boot drive. If it is 0xFF, use a drive passed by BIOS.

`0x41'
The flag for if forcing LBA.

`0x42'
The starting address of Stage 2.

`0x44'
The first sector of Stage 2.

`0x48'
The starting segment of Stage 2.

`0x1FE'
The signature (`0xAA55').

See the file `stage1/stage1.S', for more information.

In the first sector of Stage 1.5 and Stage 2, the block lists are
recorded between `firstlist' and `lastlist'. The address of `lastlist'
is determined when assembling the file `stage2/start.S'.

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, and so on,
until it is finished. The terminating condition is when the number of
sectors to be read in the next block list is zero.

The format of a block list can be seen from the example in the code
just before the `firstlist' label. Note that it is always from the
beginning of the disk, but _not_ relative to the partition boundaries.

In the second sector of Stage 1.5 and Stage 2, these are defined:

`0x6'
The version number (likewise, the installation mechanism's).

`0x8'
The installed partition.

`0xC'
The saved entry number.

`0x10'
The identifier.

`0x11'
The flag for if forcing LBA.

`0x12'
The version string (GRUB's).

`0x12' + "the length of the version string"
The name of a configuration file.

See the file `stage2/asm.S', for more information.

File: grub.info, Node: Filesystem interface, Next: Command interface, Prev: Embedded data, Up: Internals

The generic interface for filesystems
=====================================

For any particular partition, it is presumed that only one of the
"normal" filesystems such as FAT, FFS, or ext2fs can be used, so there
is a switch table managed by the functions in `disk_io.c'. The notation
is that you can only "mount" one at a time.

The block list filesystem has a special place in the system. In
addition to the "normal" filesystem (or even without one mounted), you
can access disk blocks directly (in the indicated partition) via the
block list notation. Using the block list filesystem doesn't effect any
other filesystem mounts.

The variables which can be read by the filesystem backend are:

`current_drive'
The current BIOS drive number (numbered from 0, if a floppy, and
numbered from 0x80, if a hard disk).

`current_partition'
The current partition number.

`current_slice'
The current partition type.

`saved_drive'
The "drive" part of the root device.

`saved_partition'
The "partition" part of the root device.

`part_start'
The current partition starting address, in sectors.

`part_length'
The current partition length, in sectors.

`print_possibilities'
True when the `dir' function should print the possible completions
of a file, and false when it should try to actually open a file of
that name.

`FSYS_BUF'
Filesystem buffer which is 32K in size, to use in any way which the
filesystem backend desires.

The variables which need to be written by a filesystem backend are:

`filepos'
The current position in the file, in sectors.

*Caution:* the value of FILEPOS can be changed out from under the
filesystem code in the current implementation. Don't depend on it
being the same for later calls into the backend code!

`filemax'
The length of the file.

`disk_read_func'
The value of DISK_READ_HOOK _only_ during reading of data for the
file, not any other fs data, inodes, FAT tables, whatever, then
set to `NULL' at all other times (it will be `NULL' by default).
If this isn't done correctly, then the `testload' and `install'
commands won't work correctly.

The functions expected to be used by the filesystem backend are:

`devread'
Only read sectors from within a partition. Sector 0 is the first
sector in the partition.

`grub_read'
If the backend uses the block list code, then `grub_read' can be
used, after setting BLOCK_FILE to 1.

`print_a_completion'
If PRINT_POSSIBILITIES is true, call `print_a_completion' for each
possible file name. Otherwise, the file name completion won't work.

The functions expected to be defined by the filesystem backend are
described at least moderately in the file `filesys.h'. Their usage is
fairly evident from their use in the functions in `disk_io.c', look for
the use of the FSYS_TABLE array.

*Caution:* The semantics are such that then `mount'ing the
filesystem, presume the filesystem buffer `FSYS_BUF' is corrupted, and
(re-)load all important contents. When opening and reading a file,
presume that the data from the `mount' is available, and doesn't get
corrupted by the open/read (i.e. multiple opens and/or reads will be
done with only one mount if in the same filesystem).

File: grub.info, Node: Command interface, Next: Bootstrap tricks, Prev: Filesystem interface, Up: Internals

The generic interface for built-ins
===================================

GRUB built-in commands are defined in a uniformal interface, whether
they are menu-specific or can be used anywhere. The definition of a
builtin command consists of two parts: the code itself and the table of
the information.

The code must be a function which takes two arguments, a command-line
string and flags, and returns an `int' value. The "flags" argument
specifies how the function is called, using a bit mask. The return
value must be zero if successful, otherwise non-zero. So it is normally
enough to return ERRNUM.

The table of the information is represented by the structure `struct
builtin', which contains the name of the command, a pointer to the
function, flags, a short description of the command and a long
description of the command. Since the descriptions are used only for
help messages interactively, you don't have to define them, if the
command may not be called interactively (such as `title').

The table is finally registered in the table BUILTIN_TABLE, so that
`run_script' and `enter_cmdline' can find the command. See the files
`cmdline.c' and `builtins.c', for more details.