[bug#72457] [PATCH v4 13/15] doc: Update bootloader documentation.

[Lilah Tascheter via Guix-patches <guix-patches@gnu.org>]

* doc/guix.texi
  (Manual Installation)[Proceeding with the Installation]: Offload
  target reference.

  (System Installation)[Building the Installation Image]: Use beaglebone
  as the example, and don't reference deleted variables.

  (System Configuration)[Using the Configuration System]: Update
  example.
  [operating-system Reference]<bootloader>: Can use multiple
  bootloaders.
  [Keyboard Layout]: Update example.
  [Bootloader Configuration]<bootloader>: Update documentation for all
  bootloaders, and add new ones. Document new fields efi-removable?,
  32bit?, and keypair. Update terminal-outputs and terminal-outputs to
  not be GRUB-specific.
  <bootloader-target>: New record.
  <menu-entry>: Remove now-unsupported GRUB specifics in linux. Move
  device documentation and add some for device-mount-point and
  device-subvol. Fix typo in multiboot-arguments. Document chain-loader
  for arbitrary bootloaders.
  [Invoking guix system]<switch-generation>: Bootloaders are now
  reinstalled.
  <image> Other bootloaders may be used.
  [Invoking guix deploy]: Update template.

  (Creating System Images)[image Reference]<partition Reference>: Add
  target field.
  [Instantiate an Image]: Update examples and update formatting.
  <efi32-disk-image, efi32-raw-image-type>: Delete.
  [image-type Reference]<pinebook-pro-image-type, rock64-image-type>:
  Reword slightly.

Change-Id: I45ac9d5ad3cb491c693e9a4b2f0b44b527478ee7
---
 doc/guix.texi | 458 +++++++++++++++++++++++++++++---------------------
 1 file changed, 262 insertions(+), 196 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 41814042f5..b5f35a9066 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2516,12 +2516,9 @@ Proceeding with the Installation
 Make sure the @code{bootloader-configuration} form refers to the targets
 you want to install GRUB on.  It should mention @code{grub-bootloader}
 if you are installing GRUB in the legacy way, or
-@code{grub-efi-bootloader} for newer UEFI systems.  For legacy systems,
-the @code{targets} field contain the names of the devices, like
-@code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
-EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
-are currently mounted and a @code{file-system} entry is specified in
-your configuration.
+@code{grub-efi-bootloader} for newer UEFI systems.
+@xref{Bootloader Configuration} for information on how to format the
+@code{targets} field.
 
 @item
 Be sure that your file system labels match the value of their respective
@@ -2653,11 +2650,13 @@ Building the Installation Image
 includes the bootloader, specifically:
 
 @example
-guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
+guix system image --system=armhf-linux -e '(@ (gnu system install) beaglebone-black-installation-os)'
 @end example
 
-@code{A20-OLinuXino-Lime2} is the name of the board.  If you specify an invalid
-board, a list of possible boards will be printed.
+@code{beaglebone-black} is the name of the board.  Similar
+@code{installation-os} variables exist for most other supported boards.
+Otherwise, you can use @code{embedded-installation-os}, passing it a u-boot
+bootloader and the desired console tty.
 
 
 @c *********************************************************************
@@ -17229,7 +17228,9 @@ Using the Configuration System
 @lisp
 (bootloader-configuration
   (bootloader grub-efi-bootloader)
-  (targets '("/boot/efi")))
+  (targets (list (bootloader-target
+                   (type 'esp)
+                   (path "/boot/efi")))))
 @end lisp
 
 @xref{Bootloader Configuration}, for more information on the available
@@ -17535,8 +17536,10 @@ operating-system Reference
 List of strings or gexps representing additional arguments to pass on
 the command-line of the kernel---e.g., @code{("console=ttyS0")}.
 
-@item @code{bootloader}
-The system bootloader configuration object.  @xref{Bootloader Configuration}.
+@item @code{bootloader} (default: '())
+The system bootloader configuration object.  Can either be a single
+@code{bootloader-configuration} or a list of them, to install multiple or no
+bootloaders.  @xref{Bootloader Configuration}.
 
 @item @code{label}
 This is the label (a string) as it appears in the bootloader's menu entry.
@@ -18731,7 +18734,9 @@ Keyboard Layout
   (keyboard-layout (keyboard-layout "tr"))  ;for the console
   (bootloader (bootloader-configuration
                 (bootloader grub-efi-bootloader)
-                (targets '("/boot/efi"))
+                (targets (list (bootloader-target
+                                 (type 'esp)
+                                 (path "/boot/efi"))))
                 (keyboard-layout keyboard-layout))) ;for GRUB
   (services (cons (set-xorg-configuration
                     (xorg-configuration             ;for Xorg
@@ -42119,132 +42124,124 @@ Bootloader Configuration
 @cindex EFI, bootloader
 @cindex UEFI, bootloader
 @cindex BIOS, bootloader
-The bootloader to use, as a @code{bootloader} object.  For now
-@code{grub-bootloader}, @code{grub-efi-bootloader},
-@code{grub-efi-removable-bootloader}, @code{grub-efi-netboot-bootloader},
-@code{grub-efi-netboot-removable-bootloader}, @code{extlinux-bootloader}
-and @code{u-boot-bootloader} are supported.
+The bootloader to use, as a @code{bootloader} object.  Available bootloaders, in
+addition to what target types they require, are as follows:
 
-@cindex ARM, bootloaders
-@cindex AArch64, bootloaders
-Available bootloaders are described in @code{(gnu bootloader @dots{})}
-modules.  In particular, @code{(gnu bootloader u-boot)} contains definitions
-of bootloaders for a wide range of ARM and AArch64 systems, using the
-@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
+@itemize
+@vindex depthcharge-veyron-speedy-bootloader
+@item @code{depthcharge-veyron-speedy-bootloader}
+For the Asus C201.  Requires a @code{'part} target, denoting the partition to
+install the kernel blob as a @code{device}, @code{label}, or @code{uuid}.
 
 @vindex grub-bootloader
-@code{grub-bootloader} allows you to boot in particular Intel-based machines
-in ``legacy'' BIOS mode.
+@item @code{grub-bootloader}
+GRUB2 for BIOS systems.  Requires a @code{'disk} target providing either a
+@code{device}, @code{label}, or @code{uuid}.  If root is mounted over NFS, it
+will load its files and the Guix System over
+@acronym{PXE, Preboot eXecution Environment}.
+
+@vindex grub-minimal-bootloader
+@item @code{grub-minimal-bootloader}
+As above, but using a minimal build of GRUB.
 
 @vindex grub-efi-bootloader
-@code{grub-efi-bootloader} allows to boot on modern systems using the
-@dfn{Unified Extensible Firmware Interface} (UEFI).  This is what you should
-use if the installation image contains a @file{/sys/firmware/efi} directory
-when you boot it on your system.
-
-@vindex grub-efi-removable-bootloader
-@code{grub-efi-removable-bootloader} allows you to boot your system from
-removable media by writing the GRUB file to the UEFI-specification location of
-@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}.
-This is also useful for some UEFI firmwares that ``forget'' their configuration
-from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only
-be used if the @file{/sys/firmware/efi} directory is available.
+@item @code{grub-efi-bootloader}
+GRUB2 for "modern" systems using the @dfn{Unified Extensible Firmware Interface}
+(UEFI).  Requires an @code{'esp} target providing a @code{path} to the mount
+point of the EFI System Partition.  If root is mounted over NFS, it will load
+its files and the Guix System over a
+@acronym{TFTP, Trivial File Transfer Protocol} server as configured over
+@acronym{DHCP, Dynamic Host Configuration Protocol} as per PXE.
+
+@vindex extlinux-bootloader
+@item @code{extlinux-bootloader}
+Extlinux for "legacy" BIOS systems.  Requires a @code{'disk} target providing
+either a @code{device}, @code{label}, or @code{uuid}.
+
+@vindex extlinux-gpt-bootloader
+@item @code{extlinux-gpt-bootloader}
+As above, but for systems using the GPT instead of MBR partition table.
+
+@cindex Secure Boot, UEFI
+@vindex uki-efi-bootloader
+@item @code{uki-efi-bootloader}
+Makes and installs UKI images for UEFI systems.  Requires an @code{'esp} target
+providing a @code{path} to the mount point of the EFI System Partition.  Not all
+system generations may be available with this option, as UKI images contain the
+entire kernel and initramfs, and ESPs tend to be small.
+
+Full disk encryption with @code{uki-efi-bootloader} only requires a single
+password entry with fast decryption, in contrast to GRUB2 requiring a second
+password entry with slow, LUKS1-only decryption.
+
+This is the only bootloader to currently support UEFI secure boot, when
+configured as below.
 
-@quotation Note
-This @emph{will} overwrite the GRUB file from any other operating systems that
-also place their GRUB file in the UEFI-specification location; making them
-unbootable.
-@end quotation
+@cindex ARM, bootloaders
+@cindex AArch64, bootloaders
+@vindex u-boot-a20-olinuxino-lime-bootloader
+@vindex u-boot-a20-olinuxino-lime2-bootloader
+@vindex u-boot-a20-olinuxino-micro-bootloader
+@vindex u-boot-bananapi-m2-ultra-bootloader
+@vindex u-boot-beaglebone-black-bootloader
+@vindex u-boot-cubietruck-bootloader
+@vindex u-boot-firefly-rk3399-bootloader
+@vindex u-boot-mx6cuboxi-bootloader
+@vindex u-boot-nintendo-nes-classic-edition-bootloader
+@vindex u-boot-novena-bootloader
+@vindex u-boot-orangepi-r1-plus-lts-rk3328-bootloader
+@vindex u-boot-pine64-plus-bootloader
+@vindex u-boot-pine64-lts-bootloader
+@vindex u-boot-pinebook-bootloader
+@vindex u-boot-pinebook-pro-rk3399-bootloader
+@vindex u-boot-puma-rk3399-bootloader
+@vindex u-boot-rock64-rk3328-bootloader
+@vindex u-boot-rockpro64-rk3399-bootloader
+@vindex u-boot-sifive-unmatched-bootloader
+@vindex u-boot-qemu-riscv64-bootloader
+@vindex u-boot-starfive-visionfive2-bootloader
+@vindex u-boot-ts7970-q-2g-1000mhz-c-bootloader
+@vindex u-boot-wandboard-bootloader
+@vindex u-boot-rpi-2-bootloader
+@vindex u-boot-rpi-3-bootloader
+@vindex u-boot-rpi-4-bootloader
+@vindex u-boot-rpi-bootloader
+@item U-Boot
+U-Boot has individual bootloaders @code{u-boot-board-bootloader} for each
+of the following @code{board}s: @code{a20-olinuxino-lime},
+@code{a20-olinuxino-lime2}, @code{a20-olinuxino-micro},
+@code{bananapi-m2-ultra}, @code{beaglebone-black}, @code{cubietruck},
+@code{firefly-rk3399}, @code{mx6cuboxi}, @code{nintendo-nes-classic-edition},
+@code{novena}, @code{orangepi-r1-plus-lts-rk3328}, @code{pine64-plus},
+@code{pine64-lts}, @code{pinebook}, @code{pinebook-pro-rk3399},
+@code{puma-rk3399}, @code{rock64-rk3328}, @code{rockpro64-rk3399},
+@code{rpi-2}, @code{rpi-3}, @code{rpi-4}, @code{rpi}, @code{sifive-unmatched},
+@code{ts7970-q-2g-1000mhz-c}, @code{qemu-riscv64}, and @code{wandboard}.
+
+Each of these requires a @code{'disk} target providing either a @code{device},
+@code{label}, or @code{uuid}, except for @code{ts7970-q-2g-1000mhz-c} and
+@code{qemu-riscv64}, in which the bootloader just copies U-Boot to
+@file{/boot/u-boot.imx} or @file{/boot/u-boot.bin}, respectively.  You should
+then manually flash it to the SPI flash at the U-Boot prompt.
+
+By default Guix configures U-Boot to boot using a generated extlinux config, but
+U-Boot does support loading UEFI bootloaders, if you want to combine it with
+another.
+@end itemize
 
-@vindex grub-efi-netboot-bootloader
-@code{grub-efi-netboot-bootloader} allows you to boot your system over network
-through TFTP@.  In combination with an NFS root file system this allows you to
-build a diskless Guix system.
-
-The installation of the @code{grub-efi-netboot-bootloader} generates the
-content of the TFTP root directory at @code{targets} (@pxref{Bootloader
-Configuration, @code{targets}}) below the sub-directory @file{efi/Guix}, to be
-served by a TFTP server.  You may want to mount your TFTP server directories
-onto the @code{targets} to move the required files to the TFTP server
-automatically during installation.
-
-If you plan to use an NFS root file system as well (actually if you mount the
-store from an NFS share), then the TFTP server needs to serve the file
-@file{/boot/grub/grub.cfg} and other files from the store (like GRUBs background
-image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the
-initrd (@pxref{operating-system Reference, @code{initrd}})), too.  All these
-files from the store will be accessed by GRUB through TFTP with their normal
-store path, for example as
-@file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
-
-Two symlinks are created to make this possible.  For each target in the
-@code{targets} field, the first symlink is
-@samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
-@file{../../../boot/grub/grub.cfg}, where @samp{target} may be
-@file{/boot}.  In this case the link is not leaving the served TFTP root
-directory, but otherwise it does.  The second link is
-@samp{target}@file{/gnu/store} and points to @file{../gnu/store}.  This
-link is leaving the served TFTP root directory.
-
-The assumption behind all this is that you have an NFS server exporting
-the root file system for your Guix system, and additionally a TFTP
-server exporting your @code{targets} directories—usually a single
-@file{/boot}—from that same root file system for your Guix system.  In
-this constellation the symlinks will work.
-
-For other constellations you will have to program your own bootloader
-installer, which then takes care to make necessary files from the store
-accessible through TFTP, for example by copying them into the TFTP root
-directory for your @code{targets}.
-
-It is important to note that symlinks pointing outside the TFTP root directory
-may need to be allowed in the configuration of your TFTP server.  Further the
-store link exposes the whole store through TFTP@.  Both points need to be
-considered carefully for security aspects.  It is advised to disable any TFTP
-write access!
-
-Please note, that this bootloader will not modify the ‘UEFI Boot Manager’ of
-the system.
-
-Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
-NFS servers, you also need a properly configured DHCP server to make the booting
-over netboot possible.  For all this we can currently only recommend you to look
-for instructions about @acronym{PXE, Preboot eXecution Environment}.
-
-If a local EFI System Partition (ESP) or a similar partition with a FAT
-file system is mounted in @code{targets}, then symlinks cannot be
-created.  In this case everything will be prepared for booting from
-local storage, matching the behavior of @code{grub-efi-bootloader}, with
-the difference that all GRUB binaries are copied to @code{targets},
-necessary for booting over the network.
-
-@vindex grub-efi-netboot-removable-bootloader
-@code{grub-efi-netboot-removable-bootloader} is identical to
-@code{grub-efi-netboot-bootloader} with the exception that the
-sub-directory @file{efi/boot} will be used instead of @file{efi/Guix} to
-comply with the UEFI specification for removable media.
+@item @code{targets}
+This is a list of @code{bootloader-target} (see below) structures denoting
+where the bootloader should install itself.  Interpretation of specific target
+types and target requirements depend on the specific @code{bootloader} used.
 
 @quotation Note
-This @emph{will} overwrite the GRUB file from any other operating systems that
-also place their GRUB file in the UEFI-specification location; making them
-unbootable.
+Bootloaders have a set of default targets, that can interact with user-specified
+targets.  For UEFI bootloaders using the @code{'esp} target, this typically
+includes a @code{'vendir} target.  If you configure multiple UEFI bootloaders,
+you should set different @code{'vendir} target @code{path}s for each, each
+@code{offset} from @code{'esp}.
 @end quotation
 
-@item @code{targets}
-This is a list of strings denoting the targets onto which to install the
-bootloader.
-
-The interpretation of targets depends on the bootloader in question.
-For @code{grub-bootloader}, for example, they should be device names
-understood by the bootloader @command{installer} command, such as
-@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
-GNU GRUB Manual}).  For @code{grub-efi-bootloader} and
-@code{grub-efi-removable-bootloader} they should be mount
-points of the EFI file system, usually @file{/boot/efi}.  For
-@code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
-points corresponding to TFTP root directories served by your TFTP
-server.
-
 @item @code{menu-entries} (default: @code{'()})
 A possibly empty list of @code{menu-entry} objects (see below), denoting
 entries to appear in the bootloader menu, in addition to the current
@@ -42254,6 +42251,29 @@ Bootloader Configuration
 The index of the default boot menu entry.  Index 0 is for the entry of the
 current system.
 
+@item @code{efi-removable?} (default: @var{#f})
+Used by all UEFI bootloaders to determine whether they should be installed to
+the UEFI standard fallback bootloader path (on x86_64,
+@file{/EFI/BOOT/BOOTX64.EFI}).  This allows it to be booted from removable media
+or otherwise in cases where the system has not been booted from UEFI already.
+
+@quotation Warning
+This will override any other bootloaders installed to the same path!
+@end quotation
+
+@item @code{32bit?} (default: @var{#f})
+Some 64-bit systems require their bootloaders to be 32-bit, including some early
+UEFI systems and some Raspberry Pis.  If that is the case, and the bootloader
+supports it, setting this option will force the bootloader to install as if it
+were on a 32-bit system.
+
+@item @code{keypair} (default: @var{#f})
+Designates a keypair to be used by bootloaders that support some kind of
+cryptographic signature, such as UEFI Secure Boot.  This must be a pair
+@code{'(cert . priv)} of paths to the public key (@code{cert}) and private key
+(@code{priv}).  The keys these paths point to should be owned by root with 600
+permissions for security purposes.
+
 @item @code{timeout} (default: @code{5})
 The number of seconds to wait for keyboard input before booting.  Set to
 0 to boot immediately, and to -1 to wait indefinitely.
@@ -42276,19 +42296,20 @@ Bootloader Configuration
 is provided, some bootloaders might use a default theme, that's true
 for GRUB.
 
-@item @code{terminal-outputs} (default: @code{'(gfxterm)})
+@item @code{terminal-outputs} (default: @var{#f})
 The output terminals used for the bootloader boot menu, as a list of
-symbols.  GRUB accepts the values: @code{console}, @code{serial},
-@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
-@code{mda_text}, @code{morse}, and @code{pkmodem}.  This field
-corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple
-configuration,,, grub,GNU GRUB manual}).
-
-@item @code{terminal-inputs} (default: @code{'()})
+symbols.  When @var{#f}, the default is used.  For GRUB this is @code{gfxterm}.
+GRUB accepts the values: @code{console}, @code{serial}, @code{serial_@{0-3@}},
+@code{gfxterm}, @code{vga_text}, @code{mda_text}, @code{morse}, and
+@code{pkmodem}.  This field corresponds to the GRUB variable
+@code{GRUB_TERMINAL_OUTPUT}
+(@pxref{Simple configuration,,, grub,GNU GRUB manual}).
+
+@item @code{terminal-inputs} (default: @var{#f})
 The input terminals used for the bootloader boot menu, as a list of
-symbols.  For GRUB, the default is the native platform terminal as
-determined at run-time.  GRUB accepts the values: @code{console},
-@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
+symbols.  When @var{#f}, the default is used. For GRUB, this is the native
+platform terminal as determined at run-time.  GRUB accepts the values:
+@code{console}, @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
 @code{usb_keyboard}.  This field corresponds to the GRUB variable
 @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
 manual}).
@@ -42364,6 +42385,53 @@ Bootloader Configuration
 
 @end deftp
 
+@vindex bootloader-target
+Configuring bootloader targets uses a specialized record designed for clarity
+and to abstract the varying user-supplied paths bootloaders may need.  Only the
+@code{type} field is required; Guix will attempt to extrapolate as needed from
+what information you provide, though at least one of @code{path}, @code{device},
+@code{label}, or @code{uuid} is required to do so.
+
+@deftp {Data Type} bootloader-target
+The type of a target as used in @code{bootloader-configuration}.
+
+@table @asis
+
+@item @code{type}
+What target this record is describing. Must be a symbol, for example @code{'esp}
+or @code{'disk}.
+
+@item @code{path} (default: @var{#f})
+@code{path} denotes a string path, usually interpreted by the bootloader to
+signify a mount point (such as in the case of @code{'esp}).  This value is
+automatically offset from the target denoted by @code{offset}, even if the path
+given is absolute.  This allows for bootloaders to know what device or partition
+a @code{path} is actually stored on, and how to locate it.
+
+@item @code{offset} (default: @code{'root} when @code{path}, otherwise @var{#f})
+All @code{path} values, even if absolute, are automatically offset from another.
+@code{offset} is a symbol denoting which target type the path should be offset
+from.  This allows for bootloaders to know what device or partition a
+@code{path} is actually stored on, and how to locate it.
+
+For most setups, you don't need to deal with this.
+
+@item @code{device} (default: @var{#f})
+@itemx @code{label} (default: @var{#f})
+@itemx @code{uuid} (default: @var{#f})
+These all work as a way of defining some kind of physical device or partition.
+@code{uuid} (taking a @code{uuid} record) and @code{label} (taking a string) are
+vastly preferred over device (a string denoting a filesystem path to a block
+device), as block device names are inconsistant and unrecognized at boot-time.
+
+@item @code{file-system} (default: @var{#f})
+A string denoting a file system type, as used in @ref{File Systems}.  Unless
+your filesystem isn't being detected properly, or is unmounted at bootloader
+install-time, you shouldn't need to specify this.
+
+@end table
+@end deftp
+
 @cindex dual boot
 @cindex boot menu
 Should you want to list additional boot menu entries @i{via} the
@@ -42375,6 +42443,8 @@ Bootloader Configuration
 @lisp
 (menu-entry
   (label "The Other Distro")
+  (device (file-system-label "boot"))
+  (device-mount-point "/boot")
   (linux "/boot/old/vmlinux-2.6.32")
   (linux-arguments '("root=/dev/sda2"))
   (initrd "/boot/old/initrd"))
@@ -42390,6 +42460,28 @@ Bootloader Configuration
 @item @code{label}
 The label to show in the menu---e.g., @code{"GNU"}.
 
+@item @code{device} (default: @var{#f})
+The device where any files specified below are to be found--eg, for GRUB,
+@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
+
+This may be a file system label (a string), a file system UUID (a
+bytevector, @pxref{File Systems}), or @code{#f}, in which case
+the bootloader will search the device containing the file specified by
+the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}).  It
+must @emph{not} be an OS device name such as @file{/dev/sda1}.
+
+@item @code{device-mount-point} (default: @var{#f})
+This is where @code{device} is mounted onto your file system.  If provided, it
+allows for you to specify full paths for provided files, which will be
+automatically realized into paths local to their device.
+
+This is not necessary if specified files are already referring to files local to
+@code{device}, including if they're on your root filesystem.
+
+@item @code{device-subvol} (default: @var{#f})
+This is a btrfs subvolume name, useful in case you wish to access files from a
+btrfs subvolume on a device.  @xref{Btrfs file system}.
+
 @item @code{linux} (default: @code{#f})
 The Linux kernel image to boot, for example:
 
@@ -42397,17 +42489,6 @@ Bootloader Configuration
 (file-append linux-libre "/bzImage")
 @end lisp
 
-For GRUB, it is also possible to specify a device explicitly in the
-file path using GRUB's device naming convention (@pxref{Naming
-convention,,, grub, GNU GRUB manual}), for example:
-
-@example
-"(hd0,msdos1)/boot/vmlinuz"
-@end example
-
-If the device is specified explicitly as above, then the @code{device}
-field is ignored entirely.
-
 @item @code{linux-arguments} (default: @code{'()})
 The list of extra Linux kernel command-line arguments---e.g.,
 @code{'("console=ttyS0")}.
@@ -42416,16 +42497,6 @@ Bootloader Configuration
 A G-Expression or string denoting the file name of the initial RAM disk
 to use (@pxref{G-Expressions}).
 
-@item @code{device} (default: @code{#f})
-The device where the kernel and initrd are to be found---i.e., for GRUB,
-@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
-
-This may be a file system label (a string), a file system UUID (a
-bytevector, @pxref{File Systems}), or @code{#f}, in which case
-the bootloader will search the device containing the file specified by
-the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}).  It
-must @emph{not} be an OS device name such as @file{/dev/sda1}.
-
 @item @code{multiboot-kernel} (default: @code{#f})
 The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB
 manual}).  When this field is set, a Multiboot menu-entry is generated.
@@ -42448,7 +42519,7 @@ Bootloader Configuration
 To use the new and still experimental
 @uref{https://darnassus.sceen.net/~hurd-web/rump_kernel/, rumpdisk
 user-level disk driver} instead of GNU@tie{}Mach's in-kernel IDE driver,
-set @code{kernel-arguments} to:
+set @code{multiboot-arguments} to:
 
 @lisp
 '("noide")
@@ -42471,10 +42542,11 @@ Bootloader Configuration
 @end lisp
 
 @item @code{chain-loader} (default: @code{#f})
-A string that can be accepted by @code{grub}'s @code{chainloader}
-directive. This has no effect if either @code{linux} or
-@code{multiboot-kernel} fields are specified. The following is an
-example of chainloading a different GNU/Linux system.
+Varies slightly depending on bootloader.  For @code{grub}, this is anything that
+the @code{chainloader} directive can accept
+(@pxref{Chain-loading,,, grub, GNU GRUB manual}). For @code{uki-efi}, this is
+any efi binary to be installed alongside the system. The following is an example
+of chainloading a different GNU/Linux system.
 
 @lisp
 (bootloader
@@ -42682,10 +42754,6 @@ Invoking guix system
 supported by the bootloader being used.  The next time the system
 boots, it will use the specified system generation.
 
-The bootloader itself is not being reinstalled when using this
-command.  Thus, the installed bootloader is used with an updated
-configuration file.
-
 The target generation can be specified explicitly by its generation
 number.  For example, the following invocation would switch to system
 generation 7:
@@ -42706,11 +42774,10 @@ Invoking guix system
 @end example
 
 Currently, the effect of invoking this action is @emph{only} to switch
-the system profile to an existing generation and rearrange the
-bootloader menu entries.  To actually start using the target system
-generation, you must reboot after running this action.  In the future,
-it will be updated to do the same things as @command{reconfigure},
-like activating and deactivating services.
+the system profile to an existing generation and reinstall the bootloader.  To
+actually start using the target system generation, you must reboot after
+running this action.  In the future, it will be updated to do the same things
+as @command{reconfigure}, like activating and deactivating services.
 
 This action will fail if the specified generation does not exist.
 
@@ -42886,11 +42953,9 @@ Invoking guix system
 When using the @code{qcow2} image type, the returned image is in qcow2
 format, which the QEMU emulator can efficiently use. @xref{Running Guix
 in a VM}, for more information on how to run the image in a virtual
-machine.  The @code{grub-bootloader} bootloader is always used
-independently of what is declared in the @code{operating-system} file
-passed as argument.  This is to make it easier to work with QEMU, which
-uses the SeaBIOS BIOS by default, expecting a bootloader to be installed
-in the Master Boot Record (MBR).
+machine.  Currently, QEMU as packaged in Guix does not have UEFI support,
+so you should select a bootloader for BIOS systems in your
+@code{operating-system} configuration.
 
 @cindex docker-image, creating docker images
 When using the @code{docker} image type, a Docker image is produced.
@@ -43208,7 +43273,6 @@ Invoking guix deploy
 ;; forwarded to the host's loopback interface.
 
 (use-service-modules networking ssh)
-(use-package-modules bootloaders)
 
 (define %system
   (operating-system
@@ -43216,7 +43280,9 @@ Invoking guix deploy
    (timezone "Etc/UTC")
    (bootloader (bootloader-configuration
                 (bootloader grub-bootloader)
-                (targets '("/dev/vda"))
+                (targets (list (bootloader-target
+                                 (type 'disk)
+                                 (device "/dev/sda"))))
                 (terminal-outputs '(console))))
    (file-systems (cons (file-system
                         (mount-point "/")
@@ -47800,6 +47866,12 @@ partition Reference
 this flag set, usually the root one. The @code{'esp} flag identifies a
 UEFI System Partition.
 
+@item @code{target} (default: @var{#f})
+If provided, this partition provides itself as a bootloader target
+(@pxref{Bootloader Configuration}).  Most commonly, this is used to provide the
+@code{'root} and @code{'esp} targets, with the root partition and EFI System
+Partition, respectively, though this can provide any target necessary.
+
 @item @code{initializer} (default: @code{#false})
 The partition initializer procedure as a gexp.  This procedure is called
 to populate a partition.  If no initializer is passed, the
@@ -47848,6 +47920,7 @@ Instantiate an Image
     (label "GNU-ESP")
     (file-system "vfat")
     (flags '(esp))
+    (target 'esp)
     (initializer (gexp initialize-efi-partition)))
    (partition
     (size (* 50 MiB))
@@ -47864,14 +47937,15 @@ Instantiate an Image
     (label root-label)
     (file-system "ext4")
     (flags '(boot))
+    (target 'root)
     (initializer (gexp initialize-root-partition))))))
 @end lisp
 
-Note that the first and third partitions use generic initializers
-procedures, initialize-efi-partition and initialize-root-partition
-respectively.  The initialize-efi-partition installs a GRUB EFI loader
-that is loading the GRUB bootloader located in the root partition.  The
-initialize-root-partition instantiates a complete system as defined by
+Note that the first and third partitions use generic initializer
+procedures, @code{initialize-efi-partition} and @code{initialize-root-partition}
+respectively.  @code{initialize-efi-partition} simply creates the directory
+structure for an EFI bootloader to install itself to.
+@code{initialize-root-partition} instantiates a complete system as defined by
 the @code{%simple-os} operating-system.
 
 You can now run:
@@ -47929,10 +48003,6 @@ Instantiate an Image
 @code{i686} machines, supporting BIOS or UEFI booting.
 @end defvar
 
-@defvar efi32-disk-image
-Same as @code{efi-disk-image} but with a 32 bits EFI partition.
-@end defvar
-
 @defvar iso9660-image
 An ISO-9660 image composed of a single bootable partition.  This image
 can also be used on most @code{x86_64} and @code{i686} machines.
@@ -48023,10 +48093,6 @@ image-type Reference
 Build an image based on the @code{efi-disk-image} image.
 @end defvar
 
-@defvar efi32-raw-image-type
-Build an image based on the @code{efi32-disk-image} image.
-@end defvar
-
 @defvar qcow2-image-type
 Build an image based on the @code{mbr-disk-image} image but with the
 @code{compressed-qcow2} image format.
@@ -48054,14 +48120,14 @@ image-type Reference
 @defvar pinebook-pro-image-type
 Build an image that is targeting the Pinebook Pro machine.  The MBR
 image contains a single partition starting at a @code{9MiB} offset.  The
-@code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be
+@code{u-boot-pinebook-pro-rk3399-bootloader} bootloader can be
 installed in this gap.
 @end defvar
 
 @defvar rock64-image-type
 Build an image that is targeting the Rock64 machine.  The MBR image
 contains a single partition starting at a @code{16MiB} offset.  The
-@code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in
+@code{u-boot-rock64-rk3328-bootloader} bootloader can be installed in
 this gap.
 @end defvar
 
-- 
2.45.2