From nobody Thu Aug 29 18:50:36 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 4Wvr2N4Ndlz52Q0g; Thu, 29 Aug 2024 18:50:36 +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 4Wvr2N3YHVz44Dq; Thu, 29 Aug 2024 18:50:36 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1724957436; 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=abGNh4VyEnFys/1PaAczgtzBZl/snInrTmvJfqHAJgk=; b=sPlEqtYMmQN6vvsqh4hPprU+I4he+uenghoAoTRr8VD3o4HY7lQ8YrSEGLljGiAWdYULld nv+DRKtfd5BojYf5YxdN8Sp6aGFT5CzRzDKWY1EAbdZisBkLudo+lp2S4kUu1wWDBipA88 kfKB0Qe4cw9RHsKbP7wf9g+AHtn+03RAnxEsW1nwM/TCqCVeuaYKMAR6BS09yFGvsR7ed+ Q76bhgpo2azMcy4n93w4QjSXi8WevFm4dv4hb/6MnWKuV8YJhqsaCaTq4npHZLb5qMzXFg V2KXaOkn7hguGeLw1TLzLB6fCD3nBG5lU84wtMbQaeOGJ2F/Eg4dFLApwtlfGw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1724957436; a=rsa-sha256; cv=none; b=XjeUUhEFD4AIfrcmFyemBmB+KNWtDlBZfIfdBPAdySTily2G8TMB6w7a9zTkC02ZVMRl1x 65zXhScjzP0MVgA3JTcGAiUYETA5Xf1tYA4JnF1/fdNP9sRfshQs11Ar24OZtO3vFc0b7k urGjVp4j/0eoNJfRd0f+CFVMnzTZylIdIuMYjmnw0yKa6mWEZUVRLscDsbmck2cdNQREmi 9XQYYuk9iD+KuZ9O5Pp2sqvyboQ+YUJNg0giTtSQQxtTYNGDp2mKcLddwgKZ6O+IdzCmzt +JkIl3qTy3Tv0wL41rDTa4hH/5b3aLbRj1pziIJ7HnFYT1QlKMfnXS6LhEtrkw== 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=1724957436; 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=abGNh4VyEnFys/1PaAczgtzBZl/snInrTmvJfqHAJgk=; b=NZzibFJazGzEVgnC6suMWqaHrVDEm/dDsUG2DMT3ACqWnTl5tx9Y76GBQa8Qv2BCvCPK9L sLzh0o1Wv/0kd2DSyaoIZ1jfCNm54AO7Q5CeIDIGqOdXvkTva+iRTEoi+hivSkN6cyuuDt GWC27+4fn6uRSTy+omcl75Ytg7OIKFGM9Yaur0/280uUhLxGtItaAK2Fj+HV+rnDtFGxsV gpQB3TinubOtsn12Lc9Pir2/7RePiBxpsb4OT02trwpjGrJMVws5xmgxj5TXJnvcaJptJP fEZa5qeLZ/FCHCyCkQ7ubIx/+IdHCkfmJyXDSVqLwB0vPdwxFIIaVlJ3K1szLQ== 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 4Wvr2N38cTzT8M; Thu, 29 Aug 2024 18:50:36 +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 47TIoatt062311; Thu, 29 Aug 2024 18:50:36 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 47TIoaNi062308; Thu, 29 Aug 2024 18:50:36 GMT (envelope-from git) Date: Thu, 29 Aug 2024 18:50:36 GMT Message-Id: <202408291850.47TIoaNi062308@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: faf94e22a3da - releng/13.4 - 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/releng/13.4 X-Git-Reftype: branch X-Git-Commit: faf94e22a3da99dc35abe21b2d8e79f5eefd31f2 Auto-Submitted: auto-generated The branch releng/13.4 has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=faf94e22a3da99dc35abe21b2d8e79f5eefd31f2 commit faf94e22a3da99dc35abe21b2d8e79f5eefd31f2 Author: Warner Losh AuthorDate: 2024-08-20 15:44:38 +0000 Commit: Warner Losh CommitDate: 2024-08-29 18:50:49 +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) (cherry picked from commit e95ffda78ac0d61b8c17100e2061fd7542323f0d) Approved-by: re (cperciva) --- 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 37f56cf7be3f..4dd9f66790f8 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 September 4, 2022 +.Dd August 20, 2024 .Dt LOADER.EFI 8 .Os .Sh NAME @@ -345,43 +345,141 @@ The default location for the ESP mount point is documented in The following examples 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.