Changeset View
Standalone View
stand/efi/gptboot/gptboot.efi.8
- This file was copied from stand/i386/gptboot/gptboot.8.
.\" Copyright (c) 2013 Warren Block | .\" Copyright (c) 2013 Warren Block All rights reserved. | ||||||||||
.\" All rights reserved. | .\" Copyright (c) 2021 Warner Losh | ||||||||||
.\" | .\" | ||||||||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||||||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||||||||
.\" are met: | .\" are met: | ||||||||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||||||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||||||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||||||||
.\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | ||||||||||
.\" documentation and/or other materials provided with the distribution. | .\" documentation and/or other materials provided with the distribution. | ||||||||||
.\" | .\" | ||||||||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND | ||||||||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||||||||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||||||||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE | ||||||||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||||||||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||||||||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||||||||
.\" | .\" | ||||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||||||||
.\" | .\" | ||||||||||
.Dd April 30, 2019 | .Dd April 6, 2021 | ||||||||||
.Dt GPTBOOT 8 | .Dt GPTBOOT.EFI 8 | ||||||||||
.Os | .Os | ||||||||||
.Sh NAME | .Sh NAME | ||||||||||
.Nm gptboot | .Nm gptboot.efi | ||||||||||
.Nd GPT bootcode for UFS on BIOS-based computers | .Nd GPT bootcode for UFS on UEFI computers | ||||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||||||||
.Nm | .Nm | ||||||||||
is used on BIOS-based computers to boot from a UFS partition on a | is used on UEFI computers to boot from a UFS partition on a | ||||||||||
GPT-partitioned disk. | GPT-partitioned disk. | ||||||||||
.Nm | .Nm | ||||||||||
is installed in a | is installed in the EFI System Partition (ESP). | ||||||||||
.Cm freebsd-boot | For BIOS-based computers, | ||||||||||
partition with | see | ||||||||||
.Xr gpart 8 . | .Xr gptboot 8 | ||||||||||
for details. | |||||||||||
While conceptually similar, the details differ. | |||||||||||
rpokalaUnsubmitted Done Inline Actionsrpokala: > For BIOS-based computers,
> .Xr gpart 8
> is used instead.
```
BIOS-based systems use
.Xr… | |||||||||||
.Nm | |||||||||||
works only with UFS root file systems. | |||||||||||
Users with ZFS partitions should use | |||||||||||
.Xr loader.efi 8 | |||||||||||
with | |||||||||||
.Xr bectl 8 | |||||||||||
to control what dataset is used for root. | |||||||||||
Done Inline ActionsWhen what is booted ... rpokala: `When what is booted` ... | |||||||||||
Done Inline ActionsI have trouble parsing this. pstef: I have trouble parsing this. | |||||||||||
.Pp | .Pp | ||||||||||
What UEFI computers boot is usually controlled via the mechanisms explained in | |||||||||||
.Xr efibootmgr 8 | |||||||||||
Done Inline ActionsYou might make mechanism plural, as in the previous sentence. mhorne: You might make mechanism plural, as in the previous sentence. | |||||||||||
using | |||||||||||
.Xr loader.efi 8 | |||||||||||
or | |||||||||||
.Xr boot1.efi 8 . | |||||||||||
However, some setups cannot use those mechanisms. | |||||||||||
When the users cannot rely on host-supplied UEFI variables | |||||||||||
Done Inline Actionss/reply/rely/ rpokala: s/reply/rely/ | |||||||||||
or they want the contents of the media alone to decide root, | |||||||||||
.Nm | |||||||||||
Done Inline Actions
Perhaps: When deciding what to boot cannot depend on host-supplied UEFI variables, or when bugs in the UEFI implementation prevent that, .Nm is used to bridge the gap. rpokala: > When what boots cannot depend on host-supplied UEFI variables, or
> when bugs in the UEFI… | |||||||||||
Done Inline Actionsreworded a little differently to avoid the maybe too informal / idiomatic 'bridge the gap'. imp: reworded a little differently to avoid the maybe too informal / idiomatic 'bridge the gap'. | |||||||||||
accomplishes these goals. | |||||||||||
Done Inline ActionsUsually the expanded version comes first, then the initialization: is installed in the EFI System Partition (ESP). rpokala: Usually the expanded version comes first, then the initialization:
```
is installed in the EFI… | |||||||||||
.Pp | |||||||||||
When it starts, | When it starts, | ||||||||||
.Nm | .Nm | ||||||||||
first reads the GPT and determines which drive and partition to | first reads the GPT and determines which drive and partition to | ||||||||||
boot from, as described under | boot from, as described under | ||||||||||
.Sx BOOTING , | .Sx BOOTING , | ||||||||||
below. | below. | ||||||||||
If it does not find an eligible partition, or if the user hits a | If it does not find an eligible partition, it returns to the UEFI | ||||||||||
key within three seconds, | firmware. | ||||||||||
Done Inline Actions
firmware, so the next bootable item in the UEFIs Boot Manager's rpokala: > BIOS so the next bootable item in the UEFI's Boot Manager's
```
firmware, so the next… | |||||||||||
Done Inline ActionsI wonder if you should put a comma here, or rewrite. If it does not find an eligible partition, control is returned to the UEFI BIOS, so the next bootable item (...) list is tried. crees: I wonder if you should put a comma here, or rewrite.
If it does not find an eligible partition… | |||||||||||
Done Inline ActionsSorry, last one- I think rpakola's suggestion of s,BIOS,firmware, was right here as well. crees: Sorry, last one- I think rpakola's suggestion of s,BIOS,firmware, was right here as well. | |||||||||||
Done Inline Actions"firmware" rpokala: "firmware" | |||||||||||
.Nm | The firmware will then try the next bootable item in the UEFI Boot Manager's | ||||||||||
Done Inline Actions
list is tried. rpokala: > list.
```
list is tried.
``` | |||||||||||
switches from auto-boot to interactive mode. | list, if any, usually a different disk. | ||||||||||
Interactive mode allows manual selection of the disk, partition, | |||||||||||
filename, and boot option flags, as described in | |||||||||||
.Xr boot 8 . | |||||||||||
.Sh IMPLEMENTATION NOTES | .Sh IMPLEMENTATION NOTES | ||||||||||
The GPT standard allows a variable number of partitions, but | The GPT standard allows a variable number of partitions, but | ||||||||||
.Nm | .Nm | ||||||||||
only boots from tables with 128 partitions or less. | only boots from tables with 128 partitions or less. | ||||||||||
.Sh PARTITION ATTRIBUTES | .Sh PARTITION ATTRIBUTES | ||||||||||
.Nm | .Nm | ||||||||||
checks and manages several attributes of GPT UFS partitions. | checks and manages several attributes of GPT UFS partitions. | ||||||||||
These flags are | |||||||||||
.Fx | |||||||||||
specific and non-standard. | |||||||||||
.Bl -tag -width ".Cm bootfailed" | .Bl -tag -width ".Cm bootfailed" | ||||||||||
.It Cm bootme | .It Cm bootme | ||||||||||
Attempt to boot from this partition. | Attempt to boot from this partition. | ||||||||||
If more than one partition has the | If more than one partition has the | ||||||||||
.Cm bootme | .Cm bootme | ||||||||||
attribute set, | attribute set, | ||||||||||
.Nm | .Nm | ||||||||||
will attempt to boot each one until successful. | will attempt to boot each one until successful. | ||||||||||
Show All 21 Lines | |||||||||||
and | and | ||||||||||
.Sx "POST-BOOT ACTIONS" | .Sx "POST-BOOT ACTIONS" | ||||||||||
below for details. | below for details. | ||||||||||
.El | .El | ||||||||||
.Sh USAGE | .Sh USAGE | ||||||||||
For normal usage, the user does not have to set or manage any of the | For normal usage, the user does not have to set or manage any of the | ||||||||||
partition attributes. | partition attributes. | ||||||||||
.Nm | .Nm | ||||||||||
will boot from the first UFS partition found. | will boot from the first UFS partition found on the device. | ||||||||||
.Pp | .Pp | ||||||||||
The | The | ||||||||||
.Cm bootonce | .Cm bootonce | ||||||||||
attribute can be used for testing an upgraded operating system on | attribute can be used for testing an upgraded operating system on | ||||||||||
an already-working computer. | an already-working computer. | ||||||||||
The existing system partition is left untouched, and the new version | The existing system partition is left untouched, and the new version | ||||||||||
of the operating system to be tested is installed on another partition. | of the operating system to be tested is installed on another partition. | ||||||||||
The | The | ||||||||||
▲ Show 20 Lines • Show All 81 Lines • ▼ Show 20 Lines | |||||||||||
The | The | ||||||||||
.Cm bootfailed | .Cm bootfailed | ||||||||||
attributes are cleared from all the partitions. | attributes are cleared from all the partitions. | ||||||||||
The | The | ||||||||||
.Cm bootonce | .Cm bootonce | ||||||||||
attribute is cleared from the partition that successfully booted. | attribute is cleared from the partition that successfully booted. | ||||||||||
There is normally only one of these. | There is normally only one of these. | ||||||||||
.Sh FILES | .Sh FILES | ||||||||||
.Bl -tag -width /boot/gptboot -compact | .Bl -tag -width /boot/gptboot.efi -compact | ||||||||||
.It Pa /boot/gptboot | .It Pa /boot/gptboot.efi | ||||||||||
bootcode binary | bootcode binary | ||||||||||
.It Pa /boot.config | .It Pa /boot/efi/efi/boot/bootx64.efi | ||||||||||
parameters for the boot blocks | Default boot loader for amd64 systems. | ||||||||||
.Pq optional | .It Pa /boot/efi/efi/boot/bootaa64.efi | ||||||||||
Default boot loader for arm64 systems. | |||||||||||
.It Pa /boot/efi/efi/boot/bootarm.efi | |||||||||||
Done Inline Actions
mhorne: | |||||||||||
Default boot loader for arm systems. | |||||||||||
Done Inline Actions
mhorne: | |||||||||||
Done Inline ActionsSo this is now official? Cool. imp: So this is now official? Cool. | |||||||||||
.It Pa /boot/efi/efi/boot/bootriscv64.efi | |||||||||||
Default boot loader for riscv systems. | |||||||||||
.El | .El | ||||||||||
.Sh EXAMPLES | .Sh EXAMPLES | ||||||||||
.Nm | .Nm | ||||||||||
is installed in a | is installed in the ESP with | ||||||||||
.Cm freebsd-boot | .Xr cp 1 . | ||||||||||
partition, usually the first partition on the disk. | |||||||||||
A | |||||||||||
.Dq protective MBR | |||||||||||
.Po | |||||||||||
see | |||||||||||
.Xr gpart 8 | |||||||||||
.Pc | |||||||||||
is typically installed in combination with | |||||||||||
.Nm . | |||||||||||
.Pp | .Pp | ||||||||||
Install | Install | ||||||||||
.Nm | .Nm | ||||||||||
on the | into the ESP for the system. | ||||||||||
.Pa ada0 | This assumes the ESP is mounted in the standard | ||||||||||
drive: | .Pa /boot/efi | ||||||||||
.Bd -literal -offset indent | directory. | ||||||||||
gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0 | For amd64, use the following | ||||||||||
.Bd -literal -offset indent -compact | |||||||||||
cp /boot/gptboot.efi /boot/efi/efi/boot/bootx64.efi | |||||||||||
.Ed | .Ed | ||||||||||
For other systems, use the file listed in the | |||||||||||
.Sx FILES | |||||||||||
section. | |||||||||||
.Pp | .Pp | ||||||||||
.Nm | |||||||||||
can also be installed without the PMBR: | |||||||||||
.Bd -literal -offset indent | |||||||||||
gpart bootcode -p /boot/gptboot -i 1 ada0 | |||||||||||
.Ed | |||||||||||
.Pp | |||||||||||
Set the | Set the | ||||||||||
.Cm bootme | .Cm bootme | ||||||||||
attribute for partition 2: | attribute for partition 2: | ||||||||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||||||||
gpart set -a bootme -i 2 ada0 | gpart set -a bootme -i 2 ada0 | ||||||||||
.Ed | .Ed | ||||||||||
.Pp | .Pp | ||||||||||
Set the | Set the | ||||||||||
.Cm bootonce | .Cm bootonce | ||||||||||
attribute for partition 2, automatically also setting the | attribute for partition 2, automatically also setting the | ||||||||||
.Cm bootme | .Cm bootme | ||||||||||
attribute: | attribute: | ||||||||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||||||||
gpart set -a bootonce -i 2 ada0 | gpart set -a bootonce -i 2 ada0 | ||||||||||
.Ed | .Ed | ||||||||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||||||||
.Xr boot.config 5 , | |||||||||||
.Xr rc.conf 5 , | .Xr rc.conf 5 , | ||||||||||
.Xr boot 8 , | .Xr boot 8 , | ||||||||||
.Xr gpart 8 | .Xr efibootmgr 8 , | ||||||||||
.Xr gpart 8 , | |||||||||||
.Xr gptboot 8 , | |||||||||||
.Xr loader.efi 8 | |||||||||||
Done Inline Actionsgpart isn't used for UEFI, so you can drop that. But I'd add .Xr gptboot 8 and .Xr loader.efi 8 (vestigial though the latter may be at the moment). rpokala: `gpart` isn't used for UEFI, so you can drop that. But I'd add
```
.Xr gptboot 8
```
and
```
. | |||||||||||
Done Inline Actionsgpart is used with UEFI to mark partitions as bootme or bootonce. imp: gpart is used with UEFI to mark partitions as `bootme` or `bootonce`.
| |||||||||||
.Sh HISTORY | .Sh HISTORY | ||||||||||
.Nm | .Nm | ||||||||||
appeared in FreeBSD 7.1. | appeared in | ||||||||||
.Fx 13.0 | |||||||||||
.Sh AUTHORS | .Sh AUTHORS | ||||||||||
This manual page written by | This manual page written by | ||||||||||
.An Warner Losh Aq imp@FreeBSD.org . | |||||||||||
Done Inline ActionsIs that an alias? :) crees: Is that an alias? :) | |||||||||||
It is based heavily on the | |||||||||||
.Xr gptboot 8 | |||||||||||
man page by | |||||||||||
.An Warren Block Aq wblock@FreeBSD.org . | .An Warren Block Aq wblock@FreeBSD.org . |