git: a79a53da7d99 - stable/13 - loader.efi(8): document slop control, amd64 nocopy, and amd64 fault commands

From: Warner Losh <>
Date: Tue, 24 Jan 2023 22:12:29 UTC
The branch stable/13 has been updated by imp:


commit a79a53da7d99aaf8b95ae96d74b5683e3b307797
Author:     Konstantin Belousov <>
AuthorDate: 2022-09-04 07:36:35 +0000
Commit:     Warner Losh <>
CommitDate: 2023-01-24 21:49:33 +0000

    loader.efi(8): document slop control, amd64 nocopy, and amd64 fault commands
    Reviewed by:    imp
    Discussed with: gbe (man pages)
    English wording help by:        rpokala
    Sponsored by:   The FreeBSD Foundation
    MFC after:      3 days
    Differential revision:
    (cherry picked from commit 85c8c0b77d164f00e7e6e1e94544c82041d43223)
 stand/man/loader.efi.8 | 117 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 116 insertions(+), 1 deletion(-)

diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8
index 139988b111d4..b15ae53f2f9d 100644
--- a/stand/man/loader.efi.8
+++ b/stand/man/loader.efi.8
@@ -3,6 +3,11 @@
 .\" Copyright (c) 2019-2022 Netflix, Inc
 .\" Copyright (c) 2022 Mateusz Piotrowski <>
+.\" Copyright 2022 The FreeBSD Foundation, Inc.
+.\" Part of this documentation was written by
+.\" Konstantin Belousov <> under sponsorship
+.\" from the FreeBSD Foundation.
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -27,7 +32,7 @@
 .\" $FreeBSD$
-.Dd August 31, 2022
+.Dd September 4, 2022
@@ -202,6 +207,116 @@ does not implement the probe
 .Fl P
 functionality where we use the video console if a keyboard is connected and a
 serial console otherwise.
+.Ss Staging Slop
+The kernel must parse the firmware memory map tables to know what memory
+it can use.
+Since it must allocate memory to do this,
+ensures there's extra memory available, called
+.Dq slop ,
+after everything it loads
+the kernel, modules and metadata
+for the kernel to bootstrap the memory allocator.
+By default, amd64 reserves 8MB.
+.Ic staging_slop
+command allows for tuning the slop size.
+It takes a single argument, the size of the slop in bytes.
+.Ss amd64 Nocopy
+will load the kernel into memory that is 2MB aligned below 4GB.
+It cannot load to a fixed address because the UEFI firmware may reserve
+arbitrary memory for its use at runtime.
+Prior to
+.Fx 13.1 ,
+kernels retained the old BIOS-boot protocol of loading at exactly 2MB.
+Such kernels must be copied from their loaded location to 2MB prior
+starting them up.
+.Ic copy_staging
+command is used to enable this copying for older kernels.
+It takes a single argument
+which can be one of
+.Bl -tag -width disable
+.It Ar disable
+Force-disable copying staging area to
+.Ad 2M .
+.It Ar enable
+Force-enable copying staging area to
+.Ad 2M .
+.It Ar auto
+Selects the behaviour based on the kernel's capability of boostraping
+from non-2M physical base.
+The kernel reports this capability by exporting the symbol
+.Va kernphys .
+Arm64 loaders have operated in the
+.Sq nocopy
+mode from their inception, so there is no
+.Ic copy_staging
+command on that platform.
+Riscv, 32-bit arm and arm64 have always loaded at any
+.Ad 2MB
+aligned location, so do not provide
+.Ic copy_staging .
+.Bd -ragged -offset indent
+.Sy Note.
+BIOS loaders on i386 and amd64 put the staging area starting
+at the physical address
+.Ad 2M ,
+then enable paging with identical mapping for the low
+.Ad 1G .
+The initial port of
+followed the same scheme for handing control to the kernel,
+since it avoided modifications for the loader/kernel hand-off protocol,
+and for the kernel page table bootstrap.
+This approach is incompatible with the UEFI specification,
+and as a practical matter, caused troubles on many boards,
+because UEFI firmware is free to use any memory for its own needs.
+Applications like
+must only use memory explicitly allocated using boot interfaces.
+The original way also potentially destroyed UEFI runtime interfaces data.
+and the kernel were improved to avoid this problem.
+.Ss amd64 Faults
+Because it executes in x86 protected mode, the amd64 version of
+is susceptible to CPU faults due to programmer mistakes and
+memory corruption.
+To make debugging such faults easier, amd64
+can provide detailed reporting of the CPU state at the time
+of the fault.
+.Ic grab_faults
+command installs a handler for faults directly in the IDT,
+avoiding the use of the UEFI debugging interface
+.Fn EFI_DEBUG_SUPPORT_PROTOCOL.RegisterExceptionCallback .
+That interface is left available for advanced debuggers in
+the UEFI environment.
+.Ic ungrab_faults
+command tries to deinstall the fault handler, returning TSS and IDT
+CPU tables to their pre-installation state.
+.Ic fault
+command produces a fault in the
+environment for testing purposes, by executing the
+.Ic ud2
+processor instruction.
 .Bl -tag -width "/boot/loader.efi"
 .It Pa /boot/loader.efi