Differential D29591 Diff 86865 stand/efi/gptboot/gptboot.efi.8

Changeset View

Standalone View

stand/efi/gptboot/gptboot.efi.8

This file was copied from stand/i386/gptboot/gptboot.8.

.\" .\"

.\" 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 a UEFI ESP with the

.Cm freebsd-boot .Xr cp 1

partition with command.

.Xr gpart 8 . For BIOS-based computers,

see

.Xr gptboot 8

rpokalaUnsubmitted

Done

For BIOS-based computers,
.Xr gpart 8
is used instead.

BIOS-based systems use
.Xr gptboot 8
instead, which is installed with
.Xr gpart 8 .

rpokala: > For BIOS-based computers, > .Xr gpart 8 > is used instead. ``` BIOS-based systems use .Xr…

for details.

While conceptually similar, the details differ.

.Nm

works only with UFS root file systems.

Users with ZFS partitions should use

.Xr loader.efi 8

with

rpokalaUnsubmitted

Done

When what is booted ...

rpokala: `When what is booted` ...

pstefUnsubmitted

Done

I have trouble parsing this.

pstef: I have trouble parsing this.

.Xr bectl 8

to control what dataset is used for root.

.Pp .Pp

mhorneUnsubmitted

Done

You might make mechanism plural, as in the previous sentence.

mhorne: You might make mechanism plural, as in the previous sentence.

What UEFI computers boot is usually controlled via the mechanisms explained in

.Xr efibootmgr 8

using

.Xr loader.efi 8

.Xr boot1.efi 8 .

rpokalaUnsubmitted

Done

s/reply/rely/

rpokala: s/reply/rely/

However, some setups cannot use those mechanisms.

When what boots cannot depend on host-supplied UEFI variables, or

rpokalaUnsubmitted

Done

When what boots cannot depend on host-supplied UEFI variables, or
when bugs in the UEFI implementation prevent that,
.Nm
is used to bridge the gap.

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…

impAuthorUnsubmitted

Done

reworded 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'.

when bugs in the UEFI implementation prevent that,

.Nm

is used to bridge the gap.

rpokalaUnsubmitted

Done

Usually 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, firmwarm.

rpokalaUnsubmitted

Done

BIOS so the next bootable item in the UEFI's Boot Manager's

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…

creesUnsubmitted

Done

I 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…

creesUnsubmitted

Done

Sorry, 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.

rpokalaUnsubmitted

Done

"firmware"

rpokala: "firmware"

.Nm The firmware will then try the next bootable item in the UEFI Boot Manager's

rpokalaUnsubmitted

Done

list.

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

mhorneUnsubmitted

Done

Default boot loader for arm64 systems.

- .It Pa /boot/efi/efi/boot/bootar.efi

+ .It Pa /boot/efi/efi/boot/bootarm.efi

Default boot loader for arm systems.

mhorne:

Default boot loader for arm systems.

mhorneUnsubmitted

Done

.It Pa /boot/efi/efi/boot/bootar.efi

Default boot loader for arm systems.

+ .It Pa /boot/efi/efi/boot/bootriscv64.efi

+ Default boot loader for riscv systems.

.El

.Sh EXAMPLES

mhorne:

impAuthorUnsubmitted

Done

So 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 (EFI System Partition) with

.Cm freebsd-boot .Xr cp 1 .

partition, usually the first partition on the disk.

.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 efibootmgr 8 ,

.Xr gpart 8 .Xr gpart 8

rpokalaUnsubmitted

Done

gpart 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 ``` .

impAuthorUnsubmitted

Done

gpart 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 .

creesUnsubmitted

Done

Is 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 .