GRUB 2 Guide: significantly enhance EFI section (nearly complete)

1 files changed, 115 insertions, 3 deletions

diff --git a/docs/grub-2-guide.xml b/docs/grub-2-guide.xml
index e8c5b72..44daf5a 100644
--- a/docs/grub-2-guide.xml
+++ b/docs/grub-2-guide.xml
@@ -289,10 +289,122 @@ use it at all.
 </p>
 
 <p>
-TODO: grub image
+Next, you should add (or edit) an entry for the /boot partition into fstab and
+mount it:
+</p>
+
+<pre caption="fstab entry and mounting of /boot">
+# <i>cat /etc/fstab | grep efi-boot</i>
+LABEL=efi-boot   /boot   vfat   defaults   0 2
+# <i>mount /boot</i>
+</pre>
+
+<p>
+Next, you should copy GRUB 2 modules into /boot where they can be found by
+GRUB 2 during system boot:
+</p>
+
+<pre caption="Copying GRUB 2 modules into /boot (must be done everytime GRUB 2 is updated)">
+# <i>mkdir -p /boot/grub2</i>
+# <i>cp /lib/grub2/x86_64-efi/* /boot/grub2/</i>
+</pre>
+
+<p>
+The most crucial step is creating the GRUB 2 image (EFI application). This is
+accomplished using the <c>grub2-mkimage</c> command:
+</p>
+
+<pre caption="Creating GRUB 2 image (must be done everytime GRUB 2 is updated)">
+# <i>grub2-mkimage -p /grub2 -o /boot/grub2/grub.efi -O x86_64-efi part_msdos part_gpt fat</i>
+</pre>
+
+<table>
+<tr>
+<th colspan="2">grub2-mkimage options</th>
+<th>recommended value</th>
+<th>notes</th>
+</tr>
+
+<tr>
+<th>-p</th>
+<ti>where should GRUB 2 look for its modules and config?</ti>
+<ti><c>/grub2</c></ti>
+<ti><b>relative to the root of the
+partition where GRUB 2 EFI application is executed from</b></ti>
+</tr>
+
+<tr>
+<th>-o</th>
+<ti>where to store created image?</ti>
+<ti><c>/boot/grub2/grub.efi</c></ti>
+</tr>
+
+<tr>
+<th>-O</th>
+<ti>platform to create image for</ti>
+<ti><c>x86_64-efi</c></ti>
+<ti>replace with <c>i386-efi</c> on 32bit systems (old Intel Macs)</ti>
+</tr>
+
+<tr>
+<th>&lt;rest&gt;</th>
+<ti>modules from /lib/grub2/[platform] to statically link in</ti>
+<ti><c>part_msdos part_gpt fat</c></ti>
+<ti>you only need to specify modules that are needed to be able to load other
+modules from filesystem. You may drop <c>part_msdos</c> or <c>part_gpt</c> if
+you don't use such partitions. You may add <c>normal</c> for a decent GRUB 2
+shell available even in cases GRUB 2 cannot load other modules</ti>
+</tr>
+</table>
+
+<p>When GRUB 2 image (EFI application) is made, you have to tell your firmware
+to execute it upon boot. There are two ways to achieve this. If there is
+already a default bootloader on your EFI System Partition that you don't want
+to overwrite, you have to use the second. Otherwise you can use the first and
+we encourage you to do so, since it is simpler.
+</p>
+
+<pre caption="Subvariant 1: copying grub.efi into default location for EFI bootloader  (must be done everytime GRUB 2 is updated)">
+# <i>mkdir -p /boot/EFI/BOOT</i>
+# <i>cp /boot/grub2/grub.efi /boot/EFI/BOOT/BOOTX64.EFI</i>
+</pre>
 
-After you have prepared your GAGA, you can easily proceed with generating the
-configuration.
+<note>
+EFI 2 specification says that the default bootloader location is <c>[EFI System
+Partition]\EFI\BOOT\BOOTx64.EFI</c> for x86_64 hardware. (and
+<c>...\BOOTIA32.EFI</c> on 32bit systems) While FAT32 filesystems should be
+case-insesitive, it is recommended to use ALL-CAPS filenames in default
+bootloader path in order to be compatible with all vfat mount options.
+</note>
+
+<pre caption="Subvariant 2: use efibootmgr to tell firmware what to execute on boot">
+# <i>efibootmgr TODO TODO TODO</i>
+</pre>
+
+<warn>
+Executing <c>efibootmgr</c> on Macs is known to brick (destroy) your firmware!
+Various sources report that the <c>bless</c> command should be used instead.
+</warn>
+
+<p>
+Last, you should create a GRUB 2 environment file (where GRUB 2 stores
+persistent variables such number of the last booted item) as it is not created
+automatically:
+</p>
+
+<pre caption="Creating GRUB 2 environment file">
+# <i>grub2-editenv - create</i>
+</pre>
+
+<impo>
+When you update GRUB 2, be sure to execute all commands that are marked as
+such. Failure to do so would result in you using the previously installed GRUB
+version.
+</impo>
+
+<p>
+The last step is actually installing Linux kernel images into /boot, then you
+can easily proceed with generating the configuration.
 </p>
 
 </body>