[PATCH] Improve documentation of BIOS installation

[Colin Watson]

With http://grub.enbug.org/BIOS_Boot_Partition being down at the moment,
I went to look at what corresponding documentation there was in the
manual.  There actually was some, written variously by Vladimir and me,
but I felt that it could use a bit of reorganisation, and being put into
a form where we could give out a single link that discusses all the BIOS
installation issues in one place rather than being scattered around the
manual.

What do you think of this patch?  It consolidates the existing
documentation into a new "BIOS installation" section and adds some
cross-references; I also wrote some new text to try to explain things
more clearly.

2011-03-29  Colin Watson  <address@hidden>

        * docs/grub.texi (BIOS installation): New section, partly based on
        previous text in other sections.
        (Installing GRUB using grub-install): Replace BIOS discussion with a
        cross-reference.
        (Images): Likewise.

=== modified file 'docs/grub.texi'
--- docs/grub.texi      2011-03-09 17:35:16 +0000
+++ docs/grub.texi      2011-03-29 12:22:33 +0000
@@ -550,6 +550,7 @@ the @dfn{boot directory}.
 * Installing GRUB using grub-install::
 * Making a GRUB bootable CD-ROM::
 * Device map::
+* BIOS installation::
 @end menu
 
 
@@ -565,13 +566,8 @@ always. Therefore, GRUB provides you wit
 @dfn{device map}, which you must fix if it is wrong. @xref{Device
 map}, for more details.
 
-On BIOS platforms GRUB has to use a so-called embedding zone. On msdos
-partition tables, this is the space between the MBR and the first partition
-(called the MBR gap or the boot track), while on GPT partition tables it
-uses a BIOS Boot Partition (a partition with GUID
-21686148-6449-6e6f-744e656564454649). If you use GRUB on a BIOS system, make
-sure that the embedding zone is at least 31 KiB (512KiB or more
-recommended).
+For information on where GRUB should be installed on PC BIOS platforms,
address@hidden installation}.
 
 If you still do want to install GRUB under a UNIX-like OS (such
 as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking
@@ -744,6 +740,70 @@ comments in the file if needed, as the G
 just a comment if the first character is @samp{#}.
 
 
address@hidden BIOS installation
address@hidden BIOS installation
+
address@hidden MBR
+
+The partition table format traditionally used on PC BIOS platforms is called
+the Master Boot Record (MBR) format; this is the format that allows up to
+four primary partitions and additional logical partitions.  With this
+partition table format, there are two ways to install GRUB: it can be
+embedded in the area between the MBR and the first partition (called by
+various names, such as the "boot track", "MBR gap", or "embedding area", and
+which is usually at least 31 KiB), or the core image can be installed in a
+file system and a list of the blocks that make it up can be stored in the
+first sector of that partition.
+
+Each of these has different problems.  There is no way to reserve space in
+the embedding area with complete safety, and some proprietary software is
+known to use it to make it difficult for users to work around licensing
+restrictions; and systems are sometimes partitioned without leaving enough
+space before the first partition.  On the other hand, installing to a
+filesystem means that GRUB is vulnerable to its blocks being moved around by
+filesystem features such as tail packing, or even by aggressive fsck
+implementations, so this approach is quite fragile; this approach also has
+reliability problems if the @file{/boot} filesystem is not on the disk the
+BIOS boots from, because GRUB must rely on guessing BIOS drive numbers.
+
+The GRUB development team generally recommends embedding GRUB before the
+first partition, unless you have special requirements.  You must ensure that
+the first partition starts at least 31 KiB (63 sectors) from the start of
+the disk; on modern disks, it is often a performance advantage to align
+partitions on larger boundaries anyway, so the first partition might start 1
+MiB from the start of the disk.
+
address@hidden GPT
+
+Some newer systems use the GUID Partition Table (GPT) format.  This was
+specified as part of the Extensible Firmware Interface (EFI), but it can
+sometimes also be used on BIOS platforms.  With this format, it is possible
+to reserve a whole partition for GRUB, called the BIOS Boot Partition.  GRUB
+can then be embedded into that partition without the risk of being
+overwritten by other software and without being contained in a filesystem
+which might move its blocks around.
+
+When creating a BIOS Boot Partition on a GPT system, you should make sure
+that it is at least 31 KiB in size.  (GPT-formatted disks are not usually
+particularly small, so we recommend that you make it larger than the bare
+minimum, such as 1 MiB, to allow plenty of room for growth.)  You must also
+make sure that it has the proper partition type.  Using GNU Parted, you can
+set this using a command such as the following:
+
address@hidden
+# @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on}
address@hidden example
+
+If you are using gdisk, set the partition type to @samp{0xEF02}.  With
+partitioning programs that require setting the GUID directly, it should be
address@hidden
+
address@hidden:} Be very careful which partition you select!  When GRUB
+finds a BIOS Boot Partition during installation, it will automatically
+overwrite part of it.  Make sure that the partition does not contain any
+other data.
+
+
 @node Booting
 @chapter Booting
 
@@ -2021,28 +2081,8 @@ target operating systems, and so on) fro
 modular design allows the core image to be kept small, since the areas of
 disk where it must be installed are often as small as 32KB.
 
-On PC systems using the traditional MBR partition table format, the core
-image is usually installed in the "MBR gap" between the master boot record
-and the first partition, or sometimes it is installed in a file system and
-read directly from that.  The latter is not recommended because GRUB needs
-to encode the location of all the core image sectors in @file{diskboot.img},
-and if the file system ever moves the core image around (as it is entitled
-to do) then GRUB must be reinstalled; it also means that GRUB will not be
-able to reliably find the core image if it resides on a different disk than
-the one to which @file{boot.img} was installed.
-
-On PC systems using the more recent GUID Partition Table (GPT) format, the
-core image should be installed to a BIOS Boot Partition.  This may be
-created by GNU Parted using a command such as the following:
-
address@hidden
-# @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on}
address@hidden example
-
address@hidden:} Be very careful which partition you select!  When GRUB
-finds a BIOS Boot Partition during installation, it will automatically
-overwrite part of it.  Make sure that the partition does not contain any
-other data.
address@hidden installation}, for details on where the core image can be
+installed on PC systems.
 
 @item *.mod
 Everything else in GRUB resides in dynamically loadable modules.  These are

-- 
Colin Watson                                       address@hidden