Page MenuHomeFreeBSD
Differential D36435 Diff 110113 stand/man/loader.efi.8

Changeset View

Standalone View

View Options

stand/man/loader.efi.8

.\" .\"
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
.\" .\"
.\" 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
.\" are met: .\" are met:
.\" 1. Redistributions of source code must retain the above copyright .\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer. .\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright .\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the .\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution. .\" documentation and/or other materials provided with the distribution.
.\" .\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE. .\" SUCH DAMAGE.
.\" .\"
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd August 31, 2022 .Dd September 4, 2022
.Dt LOADER.EFI 8 .Dt LOADER.EFI 8
.Os .Os
.Sh NAME .Sh NAME
.Nm loader.efi .Nm loader.efi
.Nd UEFI kernel loader .Nd UEFI kernel loader
.Sh DESCRIPTION .Sh DESCRIPTION
On UEFI systems, On UEFI systems,
.Nm .Nm
▲ Show 20 Lines • Show All 158 Lines • ▼ Show 20 Lines
.It Fl Dh Ta RB_SERIAL | RB_MULTIPLE Ta Serial, Video Ta Serial .It Fl Dh Ta RB_SERIAL | RB_MULTIPLE Ta Serial, Video Ta Serial
.El .El
.Pp .Pp
.Nm .Nm
does not implement the probe 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
During very early bootstrap, when creating kernel page tables and other data
structures neeeded for the initial operations, kernel already needs to
allocate memory.
Because kernel cannot even parse the firmware tables describing available
memory without allocating, the bootstrap is problematic.
To solve the issue, kernel makes assumption that some memory after the
staging area where the kernel itself, together with modules and metadata,
as loaded by
.Nm ,
is availiable for use, without causing corruption to any firmware data.
.Pp
It is up to the loader to ensure that the staging area is larger than just
the loaded kernel and other data, by some the extra slop.
Loader cannot guess how large slop should be, it is dynamically consumed
gbeUnsubmitted
Done
Inline Actions

large the slop

gbe: large the slop
by kernel.
By default, the slop on amd64 is set to 8MB.
impUnsubmitted
Done
Inline Actions

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.

imp: The kernel must parse the firmware memory map tables to know what memory it can use. Since it…
.Pp
The
.Ic staging_slop
command allows to change the slop size.
It takes the single argument, the size of the slop in bytes.
.Ss amd64 Nocopy
BIOS loaders on i386 and amd64 put the staging area containing
kernel and auxillary data like modules and metadata, starting at
the physical address
.Ad 2M ,
then enables paging with identical mapping for low
.Ad 1G .
Initial port of the EFI
.Nm
followed the same scheme for handing control to kernel, since it allowed
avoiding modifications for loader/kernel hand-off protocol,
and for the kernel page table bootstrap.
.Pp
This approach is incompatible with the UEFI specification, and practically
caused troubles on many boards, because UEFI BIOS is free to use any memory
for its own needs.
The applications like
.Nm
must only use memory explicitly allocated using boot interfaces.
It also potentially destroyed UEFI runtime interfaces data.
.Pp
Eventually loader and kernel were improved to avoid this peculiarity.
For backward bug-compatibility, and to allow booting older kernels
with newer loader, a control was added.
.Pp
The nocopy behaviour can be controlled by the loader
.Ic copy_staging Cm param
command, where
impUnsubmitted
Done
Inline Actions

"originally" "eventually" "newer" and "older" are great terms to describe this problem generally.
However, let's say I have a random kernel. How do I know if it is an 'older' one that needs to be copied down to 2MB, or if it's a newer one that can tolerate being loaded anywhere? Having some rough release versions here would be quite helpful. I work on this stuff all the time, and I don't know the cutoff line.

Also, the information is all good, but I think something like the following would be better:

.Nm
will load the kernel into memory that is 2MB aligned below 1GB.
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
.... (rest as before)

This removes some of the history, to be true, but retains the relevant bits for users to decide if they
might need this as a workaround for older kernels. I debated adding that this workaround is only for
older machines whose kernel fits between 2MB and the first memory above that that the firmware
reserves, etc, but couldn't find a good way to say that which wasn't confusing. It's more for the 'upgrade'
scenario where you've upgraded the boot loader, but want to boot the old kernel to resolve some issue
with the new.

imp: "originally" "eventually" "newer" and "older" are great terms to describe this problem…
kibAuthorUnsubmitted
Done
Inline Actions

"originally" "eventually" "newer" and "older" are great terms to describe this problem generally.
However, let's say I have a random kernel. How do I know if it is an 'older' one that needs to be copied down to 2MB, or if it's a newer one that can tolerate being loaded anywhere? Having some rough release versions here would be quite helpful. I work on this stuff all the time, and I don't know the cutoff line.

There is exact information below, how to determine if the kernel supports loading at any 2MB physical, the "kernphys" symbol presence.

It's more for the 'upgrade' scenario where you've upgraded the boot loader, but want to boot the old kernel to resolve some issue with the new.

For upgrade scenario, the automation should work. My intent in providing this information was more for the cases where kernel regressed by e.g. stopping exporting the symbol for whatever reason, e.g. if stripped to aggressively. Then user at least has some clue where to start looking.

I took your text. and moved the background into a note. I still want the motivation to be present in the man page.

kib: > "originally" "eventually" "newer" and "older" are great terms to describe this problem…
impUnsubmitted
Not Done
Inline Actions

Most people won't know to look at for kernphys symbol, even after reading this man page. They will have a system that isn't booting. While the automation should work, it is still a good idea to document when the symbol appeared in our release timeline to help less technical users that might need this workaround decide whether or not to try it, so I like that you've included it. I think the current text strikes a good balance between motivation and practical effect.

imp: Most people won't know to look at for kernphys symbol, even after reading this man page. They…
.Cm param
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 capability of boostraping
from non-2M physical base.
Kernel reports its capability by exporting the symbol
.Va kernphys .
.El
.Pp
Arm64 loaders operated in the
.Sq nocopy
mode from the inception, there is no need and no control for it.
.Ss amd64 Faults
Programming mistakes and memory corruption often trigger CPU faults.
The
.Nm
is not an exception from this, because it executes in x86 protected mode.
To ease debugging faults, amd64
.Nm
allows to provide detailed reporting of the CPU state at the time
of the fault.
impUnsubmitted
Done
Inline Actions

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 2MB aligned location, so do not provide
.Ic copy_staging .

imp: Arm64 loaders have operated in the .Sq nocopy mode from their inception, so there is no .Ic…
.Pp
The
.Nm
command
.Ic grab_faults
installs a handler for faults directly in the IDT, avoiding the use of
the UEFI debugging interface
.Fn EFI_DEBUG_SUPPORT_PROTOCOL.RegisterExceptionCallback .
The interface is left available for advanced debuggers in 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 the fault in the
.Nm
environment for testing purposes.
It executes
.Nm 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
The location of the UEFI kernel loader within the system. The location of the UEFI kernel loader within the system.
.El .El
.Ss EFI System Partition .Ss EFI System Partition
.Nm .Nm
is installed on the ESP (EFI System Partition) in one of the following locations: is installed on the ESP (EFI System Partition) in one of the following locations:
▲ Show 20 Lines • Show All 62 Lines • Show Last 20 Lines