From nobody Tue Sep 06 15:55:57 2022 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4MMVNZ0WWFz4c5Yh; Tue, 6 Sep 2022 15:55:58 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4MMVNZ03rhz3F4s; Tue, 6 Sep 2022 15:55:58 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1662479758; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bvufZzaZ2Pqhe24vs/BJqtB91hBo7M1iUTgaHLR8IvI=; b=BmeLUGOTGoohrI3ZwvEqNaaRB0R9EGYZb5UrnUnv5ceNGp4FvsFW8B46kFUdj7GQZuIQ5p XC+xXNWdCM4f2azAfGVfCSmHnIqNK0y3gxHbtgC89JFyowKqC/NvFKm/P0MafprZDEEWG8 9TtWFoT/wamzNAklF0OgzT4+7/gOSFIY/BdpIGtpeZx0aVCvMt0RBXhL15aNhvEmrGSRQ3 hXKfgG+hlb89RlblPhKI6Jn0Pg9L4iKk4dFFolr6dQw1KKnRxpt3qZjhCpI1PsCXjodY3n ljMI7jSUA3ZQWmiCVEUjTj1IMGgDJ5nRt9Mq9AzDXnK98srFPwCXTH7TzkotMw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4MMVNY6710z1Cg6; Tue, 6 Sep 2022 15:55:57 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 286FtvrI071209; Tue, 6 Sep 2022 15:55:57 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 286FtvHO071208; Tue, 6 Sep 2022 15:55:57 GMT (envelope-from git) Date: Tue, 6 Sep 2022 15:55:57 GMT Message-Id: <202209061555.286FtvHO071208@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Konstantin Belousov Subject: git: 85c8c0b77d16 - main - loader.efi(8): document slop control, amd64 nocopy, and amd64 fault commands List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 85c8c0b77d164f00e7e6e1e94544c82041d43223 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1662479758; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bvufZzaZ2Pqhe24vs/BJqtB91hBo7M1iUTgaHLR8IvI=; b=OaR3zWaPUf7FQ9sXR/tVwKVJ3tddg79OaEwNOGFcYk651sUMLoK64tVMd49eOQAmOtCr4Z XYepnLSZ0vG6yp7VNOEWduDD9CkCtTg2qEyeP6pQBgdiepNa0Y73VoSgS/RJUY3Ivc8bI/ j25pOs/JfU4w2oQ1a5rZjOIa/CkrS4wIfKazVk+sUNRRjMeOu4CyUgU2uvpqi35+JUkEen FS3tXNBkZfGjaK002LrnzSEpZfpCnMICyZf3KEa0tJ6Tad/PB//5yYLPq5JDGx6PZFZE4b GmwJLHtZR43yLaXh5lKNelL4OUPCXDi8TFEu23Y41QKFJ8YiyqO5WxdoDw3eLA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1662479758; a=rsa-sha256; cv=none; b=gKCpDkvCFDEs7Z9hYOoBueIQpkRzB3s9PKyxWYDIBJ8iN4Y8kx5mas4BpvaBMJmOBKIuXA ZHTxnXO7oo2QW3Sa8AhNdStW2A3yglYGeJ+5upsdAdY/rHkWZRsBQBkLGVTDckzitFw1zl aA7/n0qnzcMpetgkyoJqVbgqPVezyTYBjjJZodkZWUM/E8aYOT2fkOOD+BPP+GLuFoKoo8 Y6RxrD6RxIkOfMFsakbykgb3ZeoVsjPa+qB6Jc2VUjJErbqW0KOJ/BTJD1V/gMrVJh7HPI jxXz7R4JYYIyTQveRt7KjgJZnWkJMGAq1xi5w6dOOGA/qxegeIWcO54/rFPe1A== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=85c8c0b77d164f00e7e6e1e94544c82041d43223 commit 85c8c0b77d164f00e7e6e1e94544c82041d43223 Author: Konstantin Belousov AuthorDate: 2022-09-04 07:36:35 +0000 Commit: Konstantin Belousov CommitDate: 2022-09-06 15:55:45 +0000 loader.efi(8): document slop control, amd64 nocopy, and amd64 fault commands Reviewed by: imp Discussed with: gbe (man pages) English wording help by: rpokala Sponsored by: The FreeBSD Foundation MFC after: 3 days Differential revision: https://reviews.freebsd.org/D36435 --- stand/man/loader.efi.8 | 117 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 116 insertions(+), 1 deletion(-) diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8 index 139988b111d4..b15ae53f2f9d 100644 --- 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,116 @@ does not implement the probe .Fl P functionality where we use the video console if a keyboard is connected and a serial console otherwise. +.Ss Staging Slop +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. +.Pp +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 +.Nm +will load the kernel into memory that is 2MB aligned below 4GB. +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 +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. +Riscv, 32-bit arm and arm64 have always loaded at any +.Ad 2MB +aligned location, so do not provide +.Ic copy_staging . +.Pp +.Bd -ragged -offset indent +.Sy Note. +BIOS loaders on i386 and amd64 put the staging area starting +at the physical address +.Ad 2M , +then enable 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. +.Ed +.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