diff --git a/ChangeLog b/ChangeLog index a0b62214c..d39560249 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +1999-10-22 OKUJI Yoshinori + + * docs/user-ref.texi: New file. + * docs/Makefile.am (UNFINISHED_MANUALS): Added user-red.texi. + 1999-10-21 OKUJI Yoshinori Add BIOS drive remapping support for chain-loading some foolish diff --git a/docs/Makefile.am b/docs/Makefile.am index 0b47e3c10..ff59a5713 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -7,7 +7,7 @@ SRC2TEXI = src2texi noinst_SCRIPTS = $(HELP2MAN) $(SRC2TEXI) # The unfinished manuals. -UNFINISHED_MANUALS = new-grub.texi tutorial.texi +UNFINISHED_MANUALS = new-grub.texi tutorial.texi user-ref.texi EXTRA_DIST = menu.lst $(man_MANS) $(noinst_SCRIPTS) \ $(EXAMPLES) $(multiboot_TEXINFOS) $(UNFINISHED_MANUALS) diff --git a/docs/Makefile.in b/docs/Makefile.in index da07a640e..7d13f0c67 100644 --- a/docs/Makefile.in +++ b/docs/Makefile.in @@ -91,7 +91,7 @@ SRC2TEXI = src2texi noinst_SCRIPTS = $(HELP2MAN) $(SRC2TEXI) # The unfinished manuals. -UNFINISHED_MANUALS = new-grub.texi tutorial.texi +UNFINISHED_MANUALS = new-grub.texi tutorial.texi user-ref.texi EXTRA_DIST = menu.lst $(man_MANS) $(noinst_SCRIPTS) \ $(EXAMPLES) $(multiboot_TEXINFOS) $(UNFINISHED_MANUALS) diff --git a/docs/tutorial.texi b/docs/tutorial.texi index 557996957..6bf1184a3 100644 --- a/docs/tutorial.texi +++ b/docs/tutorial.texi @@ -149,7 +149,7 @@ desirable. However, if you don't want to reboot your computer, run the program @file{/sbin/grub}. In both, GRUB will show the command-line interface. First, set the -GRUB's @dfn{root partition}@footnote{Note that GRUB's root partition is +GRUB's @dfn{root device}@footnote{Note that GRUB's root device is not your OS's root partition; if you need to specify a root partition for your OS, add the argument into the command @command{kernel}.} to the partition which has your GRUB images, like this: @@ -168,7 +168,7 @@ grub> find /boot/grub/stage1 This will search for the filename @file{/boot/grub/stage1} and show the device which contains the images. -If you set the root partition correctly, run the command +If you set the root device correctly, run the command @command{setup}: @example @@ -217,7 +217,7 @@ steps: @enumerate @item -Set GRUB's root partition to the drive where the OS images is stored by +Set GRUB's root device to the drive where the OS images is stored by the command @command{root}. @item @@ -239,7 +239,7 @@ Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is nothing special. But do not forget that you specify a root partition to the kernel. -First, set GRUB's root partition to the same drive as +First, set GRUB's root device to the same drive as GNU/Hurd's. Probably @code{find /boot/gnumach} or such will help you. @@ -259,7 +259,7 @@ And, finally, run the command @command{boot}. It is relatively easy to boot GNU/Linux from GRUB, because booting GNU/Linux somewhat resembles booting a Multiboot-compliant OS. -First, set GRUB's root partition to the same drive as +First, set GRUB's root device to the same drive as GNU/Linux's. Probably @code{find /vmlinuz} or such will help you. @@ -316,7 +316,7 @@ chain-load the boot loader for the operating system. Normally, the boot loader is embedded in the @dfn{boot sector} of the partition on which the operating system is installed. -First, set GRUB's root partition to the partition by the command +First, set GRUB's root device to the partition by the command @command{rootnoverify}: @example diff --git a/docs/user-ref.texi b/docs/user-ref.texi new file mode 100644 index 000000000..5228b1d12 --- /dev/null +++ b/docs/user-ref.texi @@ -0,0 +1,1187 @@ +@node Introduction +@chapter Introduction + +This chapter documents the history and the features of GRUB. + +@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 Specification, Motivation, multiboot, The Multiboot +Specification}), 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 soon 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. @xref{Obtaining and Building GRUB}, for +more information. + + +@node Features +@section GRUB features + +The primary requirement for GRUB is that it be compliant with the +@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot +Specification, Motivation, multiboot, The Multiboot Specification}. + +The other goals, listed in approximate order of importance, are: + +@itemize @bullet{} +@item +Basic functions must be straightforward for end-users. + +@item +Rich functionality to support kernel experts and designers. + +@item +Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and +Linux. Proprietary kernels (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. Only kernels 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 Specification doesn't require all the features +that GRUB supports): + +@table @asis +@item Multiple Executable Formats +Supports many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol +tables are also loaded. + +@item Supports Non-Multiboot Kernels +Supports many of the various free 32-bit kernels that lack Multiboot +compliance (primarily FreeBSD, NetBSD, OpenBSD, and +Linux). Chain-loading of other bootloaders is also supported. + +@item Loads Multiples Modules +GRUB fully supports the Multiboot feature of loading multiple modules. + +@item Configuration File +Supports a human-readable text configuration file with preset boot +commands. The list of commands (@pxref{Command}) are a superset of +those supported on the command line. An example command file is provided +in @ref{Configuration}. + +@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 +entries, and the current implementation has 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 write a new boot command +set from scratch. If no command file is present, GRUB drops to +the command line. + +The list of commands (@pxref{Command}) are a subset of those supported +for command files. Editing commands closely resemble the Bash command +line (@pxref{Command Line Editing, Bash, Command Line Editing, features, +Bash Features}), with @key{TAB}-completion of commands, devices, +partitions, and files in a directory depending on context. + +@item Multiple Filesystem Types +Supports multiple filesystem types transparently, plus a useful explicit +blocklist notation. The currently supported filesystem types are +@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, and +@dfn{Linux ext2fs}. @xref{Filesystems}, for more information. + +@item Decompression Support +Can decompress files which were compressed by @command{gzip}. This +function is both automatic and transparent to the user (i.e. all +functions operate upon the uncompressed contents of the specified +files). This greatly reduces file size and loading time, a particularly +major benefit for floppies.@footnote{There are a few pathological cases +where loading a very badly organized ELF kernel might take longer, but +in practice this never happens.} + +It is conceivable that some kernel modules should be loaded in a +compressed state, so a different module-loading command can be specified +to avoid uncompressing the modules. + +@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 of the root device. + +@item Independent of Drive Geometry Translation +Unlike many other bootloaders, GRUB makes the particular drive +translation irrelevant. A drive installed and running with one +translation may be converted to another translation without any adverse +effects or changes in GRUB's configuration. + +@item Detects All Installed @sc{ram} +GRUB can generally find all the installed @sc{ram} on a PC-compatible +machine. It uses an advanced BIOS query technique for finding all +memory regions (@pxref{Memory detection}). As described on the Multiboot +Specification (@pxref{Top, Multiboot Specification, Motivation, +multiboot, The Multiboot Specification}), not all kernels make use of +this information, but GRUB provides it for those who do. + +@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 +standard interface used in all machines. However, some newer machines +have the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB +automatically detects if LBA mode is available and uses it if +available. In LBA mode, GRUB can access the entire disk. +@end table + +Future directions might include an internal programming language for +supporting richer sets of boot options with control statements (which +would make GRUB its own kind of kernel). Support for non-PC hardware +architectures is also planned.@footnote{There is already a port to the +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{boot loader} 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 boot loader +around@dots{} GRUB! +@end quotation + +We, the GRUB maintainers, do not (usually) encourage Gordon's level of +fanaticism, but it helps to remember that boot loaders deserve +recognition. We hope that you enjoy using GNU GRUB as much as we did +writing it. + + +@node Filesystem +@chapter Filesystem syntax and semantics + +GRUB uses a special syntax for specifying disk drives which can be +accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish +between IDE, ESDI, SCSI, or others. You must know yourself which BIOS +device is equivalent to which OS device. Normally, that will be clear if +you see the files in a device or use the command @command{find}. + +@menu +* Device syntax:: How to specify devices +* Filename syntax:: How to specify files +* Blocklist syntax:: How to specify blocklists +@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 the following 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 +disklabel subpartition, such as @samp{a} or @samp{e}. + +A shortcut for specifying BSD subpartitions is +@code{(@var{bios-device},@var{bsd-subpart-letter})}, in this case, GRUB +searches for the first PC partition containing a BSD disklabel, then +finds the subpartition @var{bsd-subpart-letter}. Here is an example: + +@example +(hd0,a) +@end example + +The syntax like @samp{(hd0)} represents using the entire disk (or the +MBR when installing GRUB), while the syntax like @samp{(hd0,0)} +represents using the partition of the disk (or the boot sector of the +partition when installing GRUB). + + +@node Filename syntax +@section How to specify files + +There are two ways to specify files, by @dfn{absolute filename} and by +@dfn{blocklist}. + +An absolute filename resembles a Unix absolute filename, using @samp{/} +for the directory separator (not @samp{\} as in DOS). One example of an +absolute filename is @samp{(hd0,0)/boot/grub/menu.lst}. This means the +file @file{/boot/grub/menu.lst} in the first partition of the first hard +disk. If you omit the device name in an absolute filename, GRUB uses +GRUB's @dfn{root device} implicitly. So if you set the root device to, +say, @samp{(hd1,0)} by the command @command{root}, then +@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}. + + +@node Blocklist syntax +@section How to specify blocklists + +A blocklist is used for specifying a file that doesn't appear in the +filesystem, like a chainloader. The syntax is +@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}. +Here is an example: + +@example +@code{0+100,200+1,300+300} +@end example + +This represents that GRUB should read blocks 0 through 99, block 200, +and blocks 300 through 600. If you omit an offset, then GRUB assumes +the offset is zero. + +Like the filename syntax (@pxref{Filename syntax}), if a blocklist does +not contain a device name, then GRUB uses GRUB's @dfn{root device}. So +@code{(hd0,1)+1} is the same as @code{+1} when the root device is +@samp{(hd0,1)}. + + +@node Interface +@chapter GRUB's user interface + +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 @dfn{command line} menu +option, or if the configuration file was not found, then GRUB drops to +the command line interface. + +@menu +* Command line:: The flexible command line interface. +* Menu:: The simple menu interface. +* Menu entry editor:: Editing a menu entry. +@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 a user-invisible +way.}. The commands are a subset of those available in the configuration +file, used with exactly the same syntax. + +Cursor movement and editing of the text on the line can be done via a +subset of the functions available in the Bash shell: + +@table @key +@item C-f +@itemx PC left key +Move forward one character. + +@item C-b +@itemx PC right key +Move back one character. + +@item C-a +@itemx HOME +Move to the start of the line. + +@item C-e +@itemx END +Move the the end of the line. + +@item C-d +@itemx DEL +Delete the character underneath the cursor. + +@item C-h +@itemx BS +Delete the character to the left of the cursor. + +@item C-k +Kill the text from the current cursor position to the end of the line. + +@item C-u +Kill backward from the cursor to the beginning of the line. + +@item C-y +Yank the killed text back into the buffer at the cursor. + +@item C-p +@itemx PC up key +Move up through the history list. + +@item C-n +@itemx PC down key +Move down through the history list. +@end table + +When typing commands interactively, if the cursor is within or before +the first word in the command-line, pressing the @key{TAB} key (or +@key{C-i}) will display a listing of the available commands, and if the +cursor is after the first word, the @key{TAB} will provide a completion +listing of disks, partitions, and filenames depending on the context. + + +@node Menu +@section The simple menu interface + +The menu interface is quite easy to use. Its commands are both +reasonably intuitive and described on screen. + +Basically, the menu interface provides a list of @dfn{boot entries} 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 by pressing @key{c} +(which operates exactly like the non-config-file version of GRUB, but +allows one to return to the menu if desired by pressing @key{ESC}) or to +edit any of the @dfn{boot entries} by pressing @key{e}. + + +@node Menu entry editor +@section Editing a menu entry + +The menu entry editor looks much like the main menu interface, but the +lines in the menu are individual commands in the selected entry instead +of entry names. + +If an @key{ESC} is pressed in the editor, it aborts all the changes made +to the configuration entry and returns to the main menu interface. + +When a particular line is selected, the editor places the user at a +special version of the GRUB command line to edit that line. When the +user hits @key{RET}, GRUB replaces the line in question in the boot +entry with the changes (unless it was aborted via @key{ESC}, +in which case the changes are thrown away). + +If you want to add a new line to the menu entry, press @key{o} if adding +a line after the current line or press @key{O} if before the current +line. + +To delete a line, hit the key @key{d}. Although GRUB does not support +@dfn{undo} unfortunately, you can do almost the same thing by just +returning to the main menu. + + +@node Command +@chapter The list of available commands + +In this chapter, we list the available commands, both in the +configuration file and in the command line. + +@menu +* Menu-specific commands:: +* General commads:: +* Command-line-specific commands:: +@end menu + + +@node Menu-specific commands +@section The list of commands for the menu only + +The semantics are as follows: + +@itemize @bullet +@item +The menu-specific commands have to be used before any others. + +@item +The files @emph{must} be in plain-text format. + +@item +@samp{#} at the beginning of a line in a configuration file means it is +only a comment. + +@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 or text at the end of the line is ignored unless otherwise +specified. + +@item +Bad commands are added to the current entry, except before entries +start, where they are ignored. +@end itemize + +Commands usable in the menu only. + +@table @code +@item default @var{num} +Set the default entry to the entry number @var{num} (if not specified, +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 won't help if the machine was rebooted by a +kernel that GRUB loaded. + +@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 timeout @var{sec} +Set a timeout, in @var{sec} seconds, before automatically booting the +default entry (normally the first entry defined). + +@item title @var{name}@dots{} +Start a new boot entry, and set its name to the contents of the rest of +the line, starting with the first non-space character. +@end table + +@node General commads +@section The list of general commands + +Commands usable both in the menu and in the command line. + +@table @code +@item color @var{normal} [@var{highlight}] +Change the menu colors. The color @var{normal} is used for most +lines in the menu, and the color @var{highlight} is used to highlight the +line where the cursor points. If you omit @var{highlight}, then the +inverted color of @var{normal} is used for the highlighted line. +The format of a color is +@code{@var{foreground}/@var{background}}. @var{foreground} and +@var{background} are symbolic color names. A symbolic color name must be +one of these: + +@itemize @bullet +@item +black + +@item +blue + +@item +green + +@item +cyan + +@item +red + +@item +magenta + +@item +brown + +@item +light-gray + +@strong{These below can be specified only for the foreground.} + +@item +dark-gray + +@item +light-blue + +@item +light-green + +@item +light-cyan + +@item +light-red + +@item +light-magenta + +@item +yellow + +@item +white +@end itemize + +But only the first eight names can be used for @var{background}. You can +prefix @code{blink-} to @var{foreground} if you want a blinking +foreground color. + +This command can be used in the configuration file and on the command +line, so you may write something like this in your configuration file: + +@example +# Set default colors. +color light-gray/blue black/light-gray + +# Change the colors. +title OS-BS like +color magenta/blue black/magenta +@end example + +@item device @var{drive} @var{file} +In the grub shell, specify the file @var{file} as the actual drive for a +@sc{bios} drive @var{drive}. You can use this command to create a disk +image and to fix the drives guessed by GRUB when GRUB fails to determine +them correctly, like this: + +@example +grub> device (fd0) /floppy-image +grub> device (hd0) /dev/sd0 +@end example + +This command is just ignored in Stage 2. + +@item hide @var{partition} +Hide @var{partition} by setting the @dfn{hidden} bit in its partition +type code. This is useful only for DOS or Windows when multiple primary +partitions exist in one disk. + +@item unhide @var{partition} +Unhide @var{partition} by clearing the @dfn{hidden} bit in its partition +type code. This is useful only for DOS or Windows when multiple primary +partitions exist in one disk. +@end table + + +@node Command-line-specific commands +@section The list of commands in the command line + +These commands are usable only in the command line and in menu entries. +If you forget some command, run the command @command{help}. + +@table @code +@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). + +@item cat @var{file} +Display the contents of the file @var{file}. This command may be useful +to remind you of your OS's root partition: + +@example +grub> cat /etc/fstab +@end example + +@item chainloader @var{file} +Load @var{file} as a chain-loader. Like any other file loaded by the +filesystem code, it can use the blocklist notation to grab the first +sector of the current partition with @samp{+1}. + +@item configfile @var{file} +Load @var{file} as the configuration file. + +@item embed @var{stage1_5} @var{device} +Embed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if +@var{device} is a drive, or in the @dfn{bootloader} area if @var{device} +is a FFS partition.@footnote{The latter feature has not been implemented +yet.} Print the number of sectors which @var{stage1_5} occupies if +successful. + +@item displaymem +Display what GRUB thinks the system address space map of the machine is, +including all regions of physical @sc{ram} installed. GRUB's +@dfn{upper/lower memory} display 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 find @var{filename} +Search for the filename @var{filename} in all of partitions and print +the list of the devices which contain the file. @var{filename} should be +an absolute filename like @code{/boot/grub/stage1}. + +@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{partition-offset-sector}, +@var{byte-offset}, @var{byte-length}>} for high-level reads inside a +partition, and @samp{[@var{disk-offset-sector}]} for low-level sector +requests from the disk. + +Filesystem test mode is turned off by any use of the @command{install} +or @command{testload} commands. + +@item geometry @var{drive} [@var{cylinder} @var{head} @var{sector} [@var{total_sector}]] +Print the information for the drive @var{drive}. In the grub shell, you +can set the geometry of the drive arbitrarily. The number of the +cylinders, the one of the heads, the one of the sectors and the one of +the total sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR, +respectively. If you omit TOTAL_SECTOR, then it will be calculated +based on the C/H/S values automatically. + +@item help [@var{pattern} @dots{}] +Display helpful information about builtin commands. If you do not +specify @var{pattern}, this command lists the short documents of all +available commands, and, if you specify one or more @var{pattern}s, it +displays long documents of the commands which match @var{pattern}. + +@item impsprobe +Probe the Intel Multiprocessor Specification 1.1 or 1.4 configuration +table and boot the various CPUs which are found into a tight loop. + +@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-device} @var{file} [@var{addr}] [p] [@var{config-file}] +This command is fairly complex, and you should not use this command +unless you are familiar with GRUB. In short, it will perform a full +install presuming the Stage 2 or Stage 1.5@footnote{They're loaded the +same way, so we will refer to the Stage 1.5 as a Stage 2 from now on.} +is in its final install location. + +In slightly more detail, it will load @var{stage1-file}, validate that +it is a GRUB Stage 1 of the right version number, install a blocklist for +loading @var{file} as a Stage 2. If the option @samp{d} is present, the +Stage 1 will always look for the actual disk @var{file} was installed on, +rather than using the booting drive. The Stage 2 will be loaded at +address @var{addr}, which must be @samp{0x8000} for a true Stage 2, and +@samp{0x2000} for a Stage 1.5. If @var{addr} is not present, GRUB will +determine the address automatically. It then writes the completed Stage 1 +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. This command preserves the DOS BPB (and for hard disks, the +partition table) of the sector the Stage 1 is to be installed into. + +@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, NetBSD a.out, etc.) from +@var{file}. The rest of the line is passed verbatim as the @dfn{kernel +command line}. Any modules must be reloaded after using this command. + +@item makeactive +Set the active partition on the root disk to GRUB's root device. +This command is limited to @emph{primary} PC partitions on a hard disk. + +@item map @var{to_drive} @var{from_drive} +Map the drive @var{from_drive} to the drive @var{to_drive}. This is +necessary when you chain-load some operating systems, such as DOS, if +such an OS resides at a non-first drive. Here is an example: + +@example +grub> map (hd0) (hd1) +grub> map (hd1) (hd0) +@end example + +The example exchanges the order between the first hard disk and the +second hard disk. + +@item module @var{file} @dots{} +Load a boot module @var{file} for a Multiboot format boot image (no +interpretation of the file contents are made, so that user of this +command must know what the kernel in question expects). The rest of the +line is passed as the @dfn{module command line}, like the +@command{kernel} command. You must load a Multiboot kernel image before +loading any module. + +@item modulenounzip @var{file} @dots{} +The same as @command{module}, except that automatic decompression is +disabled. + +@item pause @var{message}@dots{} +Print the @var{message}, then wait until a key is pressed. Note that +placing @key{^G} (ASCII code 7) in the message will cause the speaker to +emit the standard beep sound, which is useful when prompting the user to +change floppies. + +@item quit +Exit from the GRUB shell @command{grub} (@pxref{Invoking The grub +shell}). This command is ignored in the native Stage 2. + +@item read @var{addr} +Read a 32-bit value from memory at address @var{addr} and display it in +hex format. + +@item root @var{device} [@var{hdbias}] +Set the current @dfn{root device} 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 correctly determine the PC partition where a BSD sub-partition is +located. The optional @var{hdbias} parameter is a number to tell a BSD +kernel how many BIOS drive numbers are on controllers before the current +one. For example, if there is an IDE disk and a SCSI disk, and your +FreeBSD root partition is on the SCSI disk, 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 device is still +desired. Note that the items mentioned in @command{root} above which +derived from attempting the mount will @emph{not} work correctly. + +@item setup @var{install_device} [@var{image_device}] +Set up the installation of GRUB automatically. This command uses the +more flexible command @command{install} in the backend and installs GRUB +into the device @var{install_device}. If @var{image_device} is +specified, then find the GRUB images in the device @var{image_device}, +otherwise use the current @dfn{root device}, which can be set by the +command @command{root}. If @var{install_dvice} is a hard disk, then +embed a Stage 1.5 in the disk if possible. + +@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 , but if no errors are reported and the final @samp{i=@var{X}, +filepos=@var{Y}} reading has @var{X} and @var{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. + +@item uppermem @var{kbytes} +Force GRUB to assume that only @var{kbytes} kilobytes of upper memory +are installed. Any system address range maps 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. +@end table + + +@node Troubleshooting +@chapter Error messages reported by GRUB + +This chapter describes error messages reported by GRUB when you +encounter trouble. @xref{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 +@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 +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. + +@item 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. + +@item Read Error +A disk read error happened while trying to read the stage2 or stage1.5. + +@item 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). +@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 : Bad filename (must be absolute filename or blocklist) +This error is returned if a filename is requested which doesn't fit the +syntax/rules listed in the @ref{Filesystem}. + +@item 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. + +@item 3 : 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 4 : Bad or incompatible header on compressed file +This error is returned if the file header for a supposedly compressed +file is bad. + +@item 5 : 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 6 : 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. + +@item 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. + +@item 8 : 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 9 : Unknown boot failure +This error is returned if the boot attempt did not succeed for reasons +which are unknown. + +@item 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 likely unable to +provide. + +@item 11 : 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 12 : Invalid device requested +This error is returned if a device string is recognizable but does not +fall under the other device errors. + +@item 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). + +@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 : 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 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. + +@item 17 : Cannot mount selected partition +This error is returned if the partition requested exists, but the +filesystem type cannot be recognized by GRUB. + +@item 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). + +@item 19 : 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 20 : 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 21 : Selected disk does not 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 22 : 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 23 : Error while parsing number +This error is returned if GRUB was expecting to read a number and +encountered bad data. + +@item 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). + +@item 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. + +@item 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. + +@item 27 : 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 28 : 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 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. +@end table + + +@node Invoking the grub shell +@chapter Invoking the grub shell + +This chapter documents the grub shell @command{grub}. + +@menu +* Basic usage:: How to use the grub shell +* Installation under UNIX:: How to install GRUB via @command{grub} +* Device map:: The map between BIOS drives and OS devices +@end menu + + +@node Basic usage +@section Introduction into the grub shell + +You can use the command @command{grub} for installing GRUB under your +operating systems and for a testbed when you add a new feature into GRUB +or when fix a bug. @command{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 in @command{grub}. It is emulated by replacing BIOS +calls with UNIX system calls and libc functions. + +The command @command{grub} accepts the following options: + +@table @code +@item --help +Print a summary of the command line options and exit. + +@item --version +Print the version number of GRUB and exit. + +@item --verbose +Print some verbose messages for debugging purpose. + +@item --device-map=@var{file} +Read the device map file instead of @file{/boot/grub/device.map}. The +format is described in @ref{Device map}. + +@item --no-floppy +Do not probe any floppy drive. This option has no effect if there is the +device map file (@pxref{Device map}). + +@item --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 there +is the device map file (@pxref{Device map}), the grub shell just ignores +this option. + +@item --config-file=@var{file} +Read the configuration file @var{file} instead of +@file{/boot/grub/menu.lst}. The format is the same as the normal GRUB +syntax. See @ref{Filesystems}, for more information. + +@item --boot-drive=@var{drive} +Set the stage2 @var{boot_drive} to @var{drive}. This argument should be +an integer (decimal, octal or hexadecimal). + +@item --install-partition=@var{par} +Set the stage2 @var{install_partition} to @var{par}. This argument +should be an integer (decimal, octal or hexadecimal). + +@item --no-config-file +Do not use the configuration file even if it can be read. + +@item --no-curses +Do not use the curses interface even if it is available. + +@item --batch +This option has the same meaning as @samp{--no-config-file --no-curses}. + +@item --read-only +Disable writing to any disk. + +@item --hold +Wait until a debugger will attach. This option is useful when you want +to debug the startup code. +@end table + + +@node Installation under UNIX +@section How to install GRUB via @command{grub} + +The installation procedure is the same as under the @dfn{native} Stage +2. @xref{Installation}, for more information. The command +@command{grub}-specific information is described here. + +What you should be careful about is @dfn{buffer cache}. @command{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: + +@itemize @bullet +@item +If you can unmount drives to which GRUB may write any amount of data, +unmount them before running @command{grub}. + +@item +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. + +@item +If a drive must be mounted with the read-write flag, make sure that any +activity is not being done on it during running the command +@command{grub}. + +@item +Reboot your operating system as soon as possible. Probably that is not +required if you follow these rules above, but reboot is the most secure +way. +@end itemize + +In addition, enter the command @command{quit} when you finish the +installation. That is @emph{very important} because @command{quit} makes +the buffer cache consistent. Do not push @key{C-c}. + +If you want to install GRUB non-interactively, specify @samp{--batch} +option in the command line. This is a simple example: + +@example +#!/bin/sh + +/sbin/grub --batch </dev/null 2>/dev/null +root (hd0,0) +setup (hd0) +quit +EOT +@end example + + +@node Device map +@section The map between BIOS drives and OS devices + +The grub shell creates the @dfn{device map file} automatically unless it +already exists. The default location is +@file{/boot/grub/device.map}. @xref{Basic usage}, if you want to change +the filename. + +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: + +@example +@var{device} @var{file} +@end example + +@var{device} is a drive, which syntax is the same as the one in GRUB +(@pxref{Device syntax}), and @var{file} is a OS's 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 in some +environments. For example, if you exchange the boot sequence between IDE +and SCSI in your BIOS, it mistakes the order. + +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 @samp{#}. + + +@node Invoking mbchk +@chapter Invoking mbchk + +The program @command{mbchk} checks for the format of a Multiboot +kernel. We recommend using this program before booting your own kernel +by GRUB. + +@command{mbchk} accepts the following options: + +@table @code +@item --help +Print a summary of the command line options and exit. + +@item --version +Print the version number of GRUB and exit. + +@item --quiet +Supress all normal output. +@end table diff --git a/stage1/stage1.S b/stage1/stage1.S index 402c02c6c..79a0c7e87 100644 --- a/stage1/stage1.S +++ b/stage1/stage1.S @@ -373,7 +373,7 @@ general_error: /* go here when you need to stop the machine hard after an error condition */ stop: jmp stop -notification_string: .string "stage1" +notification_string: .string "stage1 " geometry_error_string: .string "Geom" hd_probe_error_string: .string "Hard Disk" read_error_string: .string "Read" diff --git a/stage2/start.S b/stage2/start.S index c63156ac2..8fb021cf5 100644 --- a/stage2/start.S +++ b/stage2/start.S @@ -340,9 +340,9 @@ general_error: stop: jmp stop #ifdef STAGE1_5 -notification_string: .string " stage1.5" +notification_string: .string "stage1.5 " #else -notification_string: .string " stage2" +notification_string: .string "stage2 " #endif geometry_error_string: .string "Geom"