Page MenuHomeFreeBSD
Files F147894451

D36435.1784710802.diff
No OneTemporary
Actions

Size
4 KB
Referenced Files
None
Subscribers
None

D36435.1784710802.diff
View Options

diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8
--- 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 <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
.\" modification, are permitted provided that the following conditions
@@ -27,7 +32,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd August 31, 2022
+.Dd September 4, 2022
.Dt LOADER.EFI 8
.Os
.Sh NAME
@@ -202,6 +207,105 @@
.Fl P
functionality where we use the video console if a keyboard is connected and a
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
+by kernel.
+By default, the slop on amd64 is set to 8MB.
+.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
+.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.
+.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
.Bl -tag -width "/boot/loader.efi"
.It Pa /boot/loader.efi

File Metadata

Mime Type
text/plain
Expires
Wed, Jul 22, 9:00 AM (2 h, 33 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
29226532
Default Alt Text
D36435.1784710802.diff (4 KB)

Event Timeline