.Ss Staging Slop
The kernel needs to allocate memory during very early bootstrap,
when creating kernel page tables and other data structures needed for initial operations.
Because the kernel cannot even parse the firmware tables describing available memory without allocating,
this makes bootstrapping problematic.
To solve this issue,
the kernel assumes that some memory after the staging area
.Po
where the kernel itself, together with modules and metadata, as loaded by
.Nm ,
resides
.Pc
is available for use,
without causing corruption of any firmware data.
.Pp
It is up to the loader to ensure that the staging area is larger than just the loaded kernel, modules, and metadata, by an extra
.Dq slop
amount.
By default, amd64 reserves 8MB.
The
.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
BIOS loaders on i386 and amd64 put the staging area starting at the physical address
.Ad 2M ,
then enables paging with identical mapping for the low
.Ad 1G .
The initial port of
.Nm
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.
.Pp
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
.Nm
must only use memory explicitly allocated using boot interfaces.
The original way also potentially destroyed UEFI runtime interfaces data.
.Pp
Eventually,
.Nm
and the kernel were improved to avoid this problem.
For backward bug-compatibility,
and to allow booting older kernels with newer
.Nm ,
this
.Sq nocopy
behaviour can be controlled by the loader
.Ic copy_staging
command.
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 .
.El
.Pp
Arm64 loaders have operated in the
.Sq nocopy
mode from their inception,
so there is no
.Ic copy_staging
command on that platform.
.Ss amd64 Faults
Because it executes in x86 protected mode,
the amd64 version of
.Nm
is susceptible to CPU faults due to programmer mistakes and memory corruption.
To make debugging such faults easier, amd64
.Nm
can provide detailed reporting of the CPU state at the time of the fault.
.Pp
The
.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.
The
.Ic ungrab_faults
command tries to deinstall the fault handler, returning TSS and IDT
CPU tables to their pre-installation state.
The
.Ic fault
command produces a fault in the
.Nm
environment for testing purposes,
by executing the
.Ic ud2
processor instruction.