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 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,111 @@ .Fl P functionality where we use the video console if a keyboard is connected and a serial console otherwise. +.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. .Sh FILES .Bl -tag -width "/boot/loader.efi" .It Pa /boot/loader.efi