From nobody Thu Aug 29 18:12:16 2024 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 4WvqB90Tb0z5TKkW; Thu, 29 Aug 2024 18:12:17 +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 "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4WvqB8702rz41bk; Thu, 29 Aug 2024 18:12:16 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1724955137; 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=3qWZa4eMH/KqeLGASSJmoC6GjeZNk6gfkW8C1LKFIQo=; b=ZnqmskT/aSutCaYXwWeCt1TMdKSs5K0mPy9n3O1kvY9vvALqQ+C4nK9sGUakc6Og8pGf6k 8qwLvbWJ3TYRJcO6G6Lr0NphUQJHZzuKRFpT3YBPJFL3ckmUem5E75rl/w17EdlG2ZwxG1 kk8nurAmQvt4GF0ioK5KUBryK5XrX+PyIyExhaRySxhIsfhQ8engdhJxSgJj0GZSKs4Nh1 DYaxXbj+G+cnyZtoktoNIeR6RX14q1gTmSscd4AkvDzCdrdfaA9GNCiIe3I4+wtgKGmpOp 5SkDfxkdMS/PCFSofDFTXMsL/9zQb45ndiSzKxjzu751eh/Z4HtESq/3yLqp3A== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1724955137; a=rsa-sha256; cv=none; b=eAP8BO8Boc37jhLtGPKoTNehL4/bcpNEAlhLtGjXUny+aqeakfPX6SHYp6/dvUf0JGTjtE EEYS5zKJZiHLoV2dme68G6MhgXWA/4oFv13Rz1evtX7EFs1rlrnUQyYaybAm8V72WPPFG2 r/h+Vzqa0jPKSzKAi8HimV2itONUO6YVn1L4bxYz/2I5cCtUqtjsPoz3nm4wTWPX0aHshW wIFLWxtoKTUZuew6/bBzYXPL2d9D8MsJlRHqKGR7ZBru6G0jgapHIqkVESwTPtL5EF0jtt QnAE+2RSeLpCjSfcHKNeDKiVJckmZTsybA5TSdgsdg0ynRSM+3EeJj8yJuXr/Q== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1724955137; 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=3qWZa4eMH/KqeLGASSJmoC6GjeZNk6gfkW8C1LKFIQo=; b=P4KTjjMveEZDYtaTHHr8XyCYF0wdDFw7AuUH+AIaWoPJfNBSqSsgmD/xGPb4uSyh3XB+kT /aPfKveRBiYKvVV7fKvKQFFWvX+MEJCe3oq7K7tJpMRyeQZEzAh98qhgxGWHlwiDtjyCF3 f+jlGUtuAu7llTVmHtdfAsPUop4s1HmNnvJVEFXM6rhZNo9x3f4jGAiy0Mn28+l3Ch6PYk u9H8Ry+GEow8AC7WduZgtEuThvpE7F64HuuRVn/pyFDjEE1a5zi6UoRQg5/XhZmVAgEBLt 3JQrQmaIada+zD9Ab4EVaXVz/Qnb+PgEsJhDiA+tdPxQO1IfYLyhrpKkUjhSbA== 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 4WvqB86bHwzSD1; Thu, 29 Aug 2024 18:12:16 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 47TICGPK000733; Thu, 29 Aug 2024 18:12:16 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 47TICGnL000730; Thu, 29 Aug 2024 18:12:16 GMT (envelope-from git) Date: Thu, 29 Aug 2024 18:12:16 GMT Message-Id: <202408291812.47TICGnL000730@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: 455dc6ffa843 - stable/14 - loader.efi(8): beef up the updating the ESP 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: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-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/14 X-Git-Reftype: branch X-Git-Commit: 455dc6ffa843b20e2555f1884d1a07d47de78123 Auto-Submitted: auto-generated The branch stable/14 has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=455dc6ffa843b20e2555f1884d1a07d47de78123 commit 455dc6ffa843b20e2555f1884d1a07d47de78123 Author: Warner Losh AuthorDate: 2024-08-20 15:44:38 +0000 Commit: Warner Losh CommitDate: 2024-08-29 18:12:27 +0000 loader.efi(8): beef up the updating the ESP There's a huge variety of situations when booting with UEFI. Document more of them, hopefully better. Feedback from: jrtc27 MFC After: 3 days Sponsored by: Netflix (cherry picked from commit 871911a4ab738a54a88f3533f553f5eb68c28012) --- stand/man/loader.efi.8 | 142 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 120 insertions(+), 22 deletions(-) diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8 index cc24b25594f9..a0c0df9a9c35 100644 --- a/stand/man/loader.efi.8 +++ b/stand/man/loader.efi.8 @@ -30,7 +30,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd November 22, 2023 +.Dd August 20, 2024 .Dt LOADER.EFI 8 .Os .Sh NAME @@ -355,43 +355,141 @@ The default location for the ESP mount point is documented in The following example shows how to install a new .Nm on the ESP. +The exact placement is complicated due to the diversity of +installations, setups and situations. +In this section, paths that are all lower case are Unix paths. +Paths that are all upper case are relative to the ESP mount point, +though they may appear as lower case on your system because the +FAT filesystem of the ESP is case insensitive. .Pp -First, find the partition of type +Locate the ESP, which has its own partition type of .Dq efi : .Bd -literal -offset indent -# gpart list | grep -Ew '(Name|efi)' -1. Name: nvd0p1 - type: efi -2. Name: nvd0p2 -3. Name: nvd0p3 -4. Name: nvd0p4 -1. Name: nvd0 +# gpart show nda0 +=> 40 7501476448 nda0 GPT (3.5T) + 40 614400 1 efi (300M) + 614440 7500862048 2 freebsd-zfs (3.5T) .Ed .Pp The name of the ESP on this system is -.Pa nvd0p1 . +.Pa nda0p1 . +By default, this will be mounted on +.Pa /boot/efi . +To check: +.Bd -literal -offset indent +# mount | grep nda0p1 +/dev/nda0p1 on /boot/efi (msdosfs, local) +.Ed +If it's not mounted, you will need to mount it: +.Bd -literal -offset indent +# mount -t msdosfs /dev/nda0p1 /boot/efi +.Ed .Pp -Second, let's mount the ESP, copy -.Nm -to the special location reserved for -.Fx -EFI loaders, and unmount once finished: +.Xr efibootmgr 8 +reports what we booted from. +.Bd -literal -offset indent +# efibootmgr -v +Boot to FW : false +BootCurrent: 0001 +Timeout : 2 seconds +BootOrder : 0000, 0001, 0003, 0004, 0005, 0006, 0001, 0008, 000A, 000B, 000C, 000E, 0007 +... ++Boot0001* FreeBSD ZPOOL HD(1,GPT,b5d0f86b-265d-1e1b-18aa-0ed55e1e73bd,0x28,0x96000)/File(\EFI\FREEBSD\LOADER.EFI) + nda0p1:/EFI/FREEBSD/LOADER.EFI /boot/efi//EFI/FREEBSD/LOADER.EFI +... +.Ed +Often there are several options, depending on the BIOS. +The entry that we booted with is marked with a +.Sq + +at the start of the line, as shown above. +So in this case, this firmware is using +.Pa /EFI/FREEBSD/LOADER.EFI +from the ESP. +Often times it will be the UEFI +.Dq default +loader, which varies by architecture. +.Bl -column -offset indent "Architecture" "Default Path" +.It Sy Architecture Ta Sy Default Path +.It amd64 Ta Pa /EFI/BOOT/BOOTX64.EFI +.It arm Ta Pa /EFI/BOOT/BOOTARM.EFI +.It arm64 Ta Pa /EFI/BOOT/BOOTAA64.EFI +.It i386 Ta Pa /EFI/BOOT/BOOTIA32.EFI +.It riscv Ta Pa /EFI/BOOT/BOOTRISCV64.EFI +.El +However, care must be taken: some multiple-boot environments rely on a special +.Pa bootXXX.efi +to function. +Before updating a +.Pa bootXXX.efi +file, make sure it is the FreeBSD boot loader before updating it: +.Bd -literal -offset indent +# strings /boot/efi/EFI/BOOT/BOOTX64.EFI | grep FreeBSD | grep EFI +FreeBSD/amd64 EFI loader, Revision 3.0 +.Ed +.Pp +.Xr bsdinstall 8 +copies +.Pa loader.efi +to the default name if there wasn't one there before. +Check to see if they are copies before updating (with X64 substituted using the +above table): +.Bd -literal -offset indent +# cmp /boot/efi/EFI/FREEBSD/LOADER.EFI /boot/efi/EFI/BOOT/BOOOTX64.EFI +.Ed +Copy the loader: +.Bd -literal -offset indent +# cp /boot/loader.efi /boot/efi/EFI/FREEBSD/LOADER.EFI +.Ed +replacing the all caps part of the example with the proper path. +.Pp +If ESP path was +.Pa /FREEBSD/LOADER.EFI +and LOADER.EFI and BOOTX64.EFI were identical in the cmp step, +copy the loader to the default location: +.Bd -literal -offset indent +# cp /boot/loader.efi /boot/efi/EFI/BOOT/BOOTX64.EFI +.Ed +.Pp +.Bd -literal -offset indent +# umount /boot/efi +.Ed +Finally, if you mounted the ESP, you may wish to unmount it. .Bd -literal -offset indent -# mount_msdosfs /dev/nvd0p1 /boot/efi -# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi # umount /boot/efi .Ed .Sh SEE ALSO .Xr loader 8 , .Xr uefi 8 .Sh BUGS -Systems that do not have a -.Dv ConOut -variable set are not conformant with the standard, and likely have unexpected -results. -.Pp Non-x86 serial console handling is even more confusing and less well documented. .Pp Sometimes when the serial port speed isn't set, 9600 is used. Other times the result is typically 115200 since the speed remains unchanged from the default. +.Pp +U-Boot implements a subset of the UEFI standard. +Some versions do not support fetching loader variables, so +.Pa efibootmgr +may not work. +In addition, +.Pa efibootmgr +is not supported on armv7 or riscv. +In these instances, the user has to understand what was booted to update +it properly (and in most cases, it will be the FreeBSD path and the UEFI default +so just copy loader.efi there if there are loaders there). +Typically in these embedded situations, there is only one .efi file (loader.efi +or a copy of loader.efi). +The path to this file is typically the default removable path above. +.Pp +Managing booting multiple OSes on UEFI varies greatly, so extra caution when +updating the UEFI default loader. +.Pp +The old, now obsolete, boot1.efi was installed as bootx64.efi in +.Fx 10 +and earlier. +Since it was quite limited in functionality, we created very small +ESPs by default. +A modern loader.efi will not fit. +However, if the old boot1.efi still works, there's no need to update +it since it will chain boot /boot/loader.efi from a copy that +make installworld updates.