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,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