I have reworded the proposed diff for better readability in English; please consider adopting any or all of these changes:
.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.
I love this information. Despite my extensive edits, I'm glad this is here.
The kernel must parse the firmware memory map tables to know what memory it can use.
"originally" "eventually" "newer" and "older" are great terms to describe this problem generally.
Also, the information is all good, but I think something like the following would be better:
This removes some of the history, to be true, but retains the relevant bits for users to decide if they
Arm64 loaders have operated in the
Riscv, 32-bit arm and arm64 have always loaded at any 2MB aligned location, so do not provide
There is exact information below, how to determine if the kernel supports loading at any 2MB physical, the "kernphys" symbol presence.
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.
Thanks for the updates based on my suggestions.
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.