Toggle diff (393 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index a3338b098a..194fbbf69c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2529,12 +2529,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
@@ -17297,7 +17294,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
@@ -17603,8 +17602,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.
@@ -18799,7 +18800,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
@@ -42437,18 +42440,8 @@ 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.
-
-@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}.
+The bootloader to use. Available bootloaders, in addition to what
+target types they require, are as follows:
@itemize
@vindex depthcharge-veyron-speedy-bootloader
@@ -42457,118 +42450,105 @@ Bootloader Configuration
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
+@acronym{UEFI, Unified Extensible Firmware Interface}. It requires an
+@code{'esp} target providing a mount point @code{path} for the EFI
+System Partition. If root is mounted over NFS, a PXE client will load
+the boot files and Guix System from a
+@acronym{TFTP, Trivial File Transfer Protocol} server, discovered via
+@acronym{DHCP, Dynamic Host Configuration Protocol}.
+
+@vindex extlinux-bootloader
+@item @code{extlinux-bootloader}
+Extlinux for "legacy" BIOS systems which use an MBR partition table.
+It requires a @code{'disk} target providing either a @code{device},
+@code{label}, or @code{uuid}.
+
+@vindex extlinux-gpt-bootloader
+@item @code{extlinux-gpt-bootloader}
+This is the same as above, but for systems with a GPT partition table.
-@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-nanopi-r4s-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-orangepi-zero-2w-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-qemu-riscv64-bootloader
+@vindex u-boot-rock64-rk3328-bootloader
+@vindex u-boot-rockpro64-rk3399-bootloader
+@vindex u-boot-rpi-2-bootloader
+@vindex u-boot-rpi-3-bootloader
+@vindex u-boot-rpi-4-bootloader
+@vindex u-boot-rpi-bootloader
+@vindex u-boot-sifive-unmatched-bootloader
+@vindex u-boot-starfive-visionfive2-bootloader
+@vindex u-boot-ts7970-q-2g-1000mhz-c-bootloader
+@vindex u-boot-wandboard-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{nanopi-r4s},
+@code{nintendo-nes-classic-edition}, @code{novena},
+@code{orangepi-r1-plus-lts-rk3328}, @code{orangepi-zero-2w},
+@code{pine64-plus}, @code{pine64-lts}, @code{pinebook},
+@code{pinebook-pro-rk3399}, @code{puma-rk3399}, @code{qemu-riscv64},
+@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}, and @code{wandboard}.
+
+Each of these require a @code{'disk} target providing either a @code{device},
+@code{label}, or @code{uuid}, except the @code{ts7970-q-2g-1000mhz-c}
+and @code{qemu-riscv64} boards. Here 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 use a generated extlinux config.
+However U-Boot can be configured to run a UEFI application, if you want
+to chain load another bootloader.
+@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
@@ -42578,6 +42558,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.
@@ -42689,6 +42692,51 @@ Bootloader Configuration
@end deftp
+@vindex bootloader-target
+Configuring bootloader targets uses a specialized record designed for clarity
+and to abstract over the varying user-supplied paths bootloaders. 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.
+
+@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.
+Using @code{uuid} and @code{label} to refer to a filesystem's UUID or
+label is vastly preferred over using @code{device} to refer to block
+devices, as they can vary per boot and may not exist 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
@@ -42700,6 +42748,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"))
@@ -42715,6 +42765,29 @@ 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. For GRUB,
+this is what @dfn{root} (@pxref{root,,, grub, GNU GRUB manual}) is set
+to for this menu entry.
+
+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{
