Toggle diff (371 lines)
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
