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: https://reviews.freebsd.org/D36435
This commit is contained in:
parent
a8fac0ce78
commit
85c8c0b77d
@ -3,6 +3,11 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" Copyright (c) 2019-2022 Netflix, Inc
|
.\" Copyright (c) 2019-2022 Netflix, Inc
|
||||||
.\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org>
|
.\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org>
|
||||||
|
.\" Copyright 2022 The FreeBSD Foundation, Inc.
|
||||||
|
.\"
|
||||||
|
.\" Part of this documentation was written by
|
||||||
|
.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
|
||||||
|
.\" from the FreeBSD Foundation.
|
||||||
.\"
|
.\"
|
||||||
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
||||||
@ -27,7 +32,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd August 31, 2022
|
.Dd September 4, 2022
|
||||||
.Dt LOADER.EFI 8
|
.Dt LOADER.EFI 8
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -202,6 +207,116 @@ does not implement the probe
|
|||||||
.Fl P
|
.Fl P
|
||||||
functionality where we use the video console if a keyboard is connected and a
|
functionality where we use the video console if a keyboard is connected and a
|
||||||
serial console otherwise.
|
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,
|
||||||
|
.Nm
|
||||||
|
ensures there's extra memory available, called
|
||||||
|
.Dq slop ,
|
||||||
|
after everything it loads
|
||||||
|
.Po
|
||||||
|
the kernel, modules and metadata
|
||||||
|
.Pc
|
||||||
|
for the kernel to bootstrap the memory allocator.
|
||||||
|
.Pp
|
||||||
|
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
|
||||||
|
.Nm
|
||||||
|
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.
|
||||||
|
The
|
||||||
|
.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 .
|
||||||
|
.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.
|
||||||
|
Riscv, 32-bit arm and arm64 have always loaded at any
|
||||||
|
.Ad 2MB
|
||||||
|
aligned location, so do not provide
|
||||||
|
.Ic copy_staging .
|
||||||
|
.Pp
|
||||||
|
.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
|
||||||
|
.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.
|
||||||
|
.Ed
|
||||||
|
.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.
|
||||||
.Sh FILES
|
.Sh FILES
|
||||||
.Bl -tag -width "/boot/loader.efi"
|
.Bl -tag -width "/boot/loader.efi"
|
||||||
.It Pa /boot/loader.efi
|
.It Pa /boot/loader.efi
|
||||||
|
Loading…
Reference in New Issue
Block a user