From nobody Tue Jan 24 22:12:29 2023 X-Original-To: dev-commits-src-all@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 4P1h6P6QSJz3bfxc; Tue, 24 Jan 2023 22:12:29 +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 4P1h6P4kwgz3D66; Tue, 24 Jan 2023 22:12:29 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1674598349; 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=hRRjWHWfRLK7NjauL9PuAkitgwSt7V7eHPNr5wOHnKY=; b=Okm/Dbg0sESegdqVyDgjSmban0vddN4fteE8einDFT5FNMKnhl8qgjuSqtbpvprverE9Tq aCN5RMzn4+1Evp951Y6zrRk+OIAd+Q3jlypsnOeyp0+X/kT44K31mXetbHWOToeyaz0KKq HF4k5MM8sD7HSux90NTWIc784K1aCuDYKoiyFqsfHuIq3kcQf+aHrxtMOrxUMjYR1uaGge dYqRGnJM/v+BhTv+pUSd8RD6UoWKJhF6ykF8JqNb3rduz1BvZWJs2OAz0LlqJ1yi+5euJO h31IudLsy8bJ3X8/RQ4YjmHqpQDROlJjZq5ACofytXXBqkiNJHTzdmQjqncCag== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1674598349; 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=hRRjWHWfRLK7NjauL9PuAkitgwSt7V7eHPNr5wOHnKY=; b=SjZ9HgWV6H+zR3qELWc+Secs817SriwFA0OdRoNDAYinGpwBwuuYhKtwz6U1t8IphSKYKG Nr/r54kG+EyBffG2WPuaW7KXFvptUSNmhPQ/J1vDXz0XqV2TSK8L4iJIu/AeRREf1ib2sO vNvIEsXb9/Ec1UyVI7SnwGEwZ9/iZjSbDc+B61vV67s+UMWppV8wEAyRxdy9dJ1piVMm+E x2pAUZYZZh45XI1Pg/r3h4ODE6X28qR96lKkPH8iCdma1wZHokSSnd9Lvgu8Q+qo9uGpmM K37SMR8/vDBAH2JJH4WXcrdjIAQVBZWik8Jp2/0ClvITcKwSgfk8GU5cQXJJ8Q== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1674598349; a=rsa-sha256; cv=none; b=xt4Fa7pnfYDJbVR5LwA8r60Ogr7bqtCRz3eOe36qAwwvEyMlU0LeZny75e5m4EVG5uSLjc j9v5AmRg2rYIMtkLLm5fJ0BgoRSqVEwB0t7TIfVWl1OFi0ds2mQqwEsXnUg9eXTBtU6AIl tCpJjhW7mu3BFPkfvP951iAl9UDTFLwVOkYit5wJ/nDj03Wm3zagbdv2f2yIdiMFIgONX3 OV9yvIqqoC0vFjCSF0K0VJBygykocQAMqM4rj+s7lr4t/0iJD2rShwGps+3puoPDkCGUv9 OJ75rfNxSU+P/MgWEY3oMGj3M4wzCnkUhM5uStjtEAa7qQHoygwi7BXSXM9Low== 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 4P1h6P2nftzQjc; Tue, 24 Jan 2023 22:12:29 +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 30OMCT6J087086; Tue, 24 Jan 2023 22:12:29 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 30OMCTh7087085; Tue, 24 Jan 2023 22:12:29 GMT (envelope-from git) Date: Tue, 24 Jan 2023 22:12:29 GMT Message-Id: <202301242212.30OMCTh7087085@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Warner Losh Subject: git: a79a53da7d99 - stable/13 - loader.efi(8): document slop control, amd64 nocopy, and amd64 fault commands List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/stable/13 X-Git-Reftype: branch X-Git-Commit: a79a53da7d99aaf8b95ae96d74b5683e3b307797 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=a79a53da7d99aaf8b95ae96d74b5683e3b307797 commit a79a53da7d99aaf8b95ae96d74b5683e3b307797 Author: Konstantin Belousov AuthorDate: 2022-09-04 07:36:35 +0000 Commit: Warner Losh CommitDate: 2023-01-24 21:49:33 +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 (cherry picked from commit 85c8c0b77d164f00e7e6e1e94544c82041d43223) --- 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