Page MenuHomeFreeBSD

gptboot.efi: Add man page
ClosedPublic

Authored by imp on Apr 5 2021, 7:08 PM.

Details

Summary

Add a man page for gptboot.efi. Describe when and how to use this as it differes
from the BIOS cases. Include cross reference for the preferred method described
in efibootmgr(8) as well as cross links in both gptboot(8) and gptboot.efi(8) to
the other.

This man page was heavily copied from the gptboot.8 man page by Warren Block.
They are different enough to need separate man pages for clarity, but there's
enough similarity that I worry about the duplication. In the really long term,
gptboot(8) will disappear, so having the same info here will help when that
day comes.

Not fixed at this time is the need to document boot1.efi and to overhaul
loader.8 to fold in changes from the last several years.

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 38353
Build 35242: arc lint + arc unit

Event Timeline

imp requested review of this revision.Apr 5 2021, 7:08 PM
rpokala added inline comments.
stand/efi/gptboot/gptboot.efi.8
42

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

When what is booted ...

70

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
71

list.

list is tried.
pstef added inline comments.
stand/efi/gptboot/gptboot.efi.8
49

I have trouble parsing this.

crees added a subscriber: crees.

A couple of suggestions inline.

stand/efi/gptboot/gptboot.efi.8
70

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.

277

Is that an alias? :)

Add better hints to look elsewhere and fix a typo.

With due attention to @rpokola 's comment above, great.

stand/efi/gptboot/gptboot.efi.8
70

Sorry, last one- I think rpakola's suggestion of s,BIOS,firmware, was right here as well.

imp marked 7 inline comments as done.Apr 5 2021, 7:39 PM

updating coming, mark everything as done since I think the next update addresses these items.

Rewrite text that was unclear based on feedback from reviewers.

minor copyright tweak due to all rights reserved being ambiguous otherwise.

start to crossref boot1.efi. loader.efi is still hopeless.

This is excellent. If duplication is a concern, maybe PARTITION ATTRIBUTES could just be a pointer to gptboot.8.

stand/efi/gptboot/gptboot.efi.8
52

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

225
226
stand/efi/gptboot/gptboot.efi.8
60

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

"firmware"

imp marked 4 inline comments as done.Apr 5 2021, 8:02 PM
imp added inline comments.
stand/efi/gptboot/gptboot.efi.8
226

So this is now official? Cool.

imp marked an inline comment as done.

Changes from mhorne.

More from Ravi and move definition of ESP earlier to first use.

imp marked 2 inline comments as done.Apr 5 2021, 8:09 PM
imp added inline comments.
stand/efi/gptboot/gptboot.efi.8
60

reworded a little differently to avoid the maybe too informal / idiomatic 'bridge the gap'.

stand/efi/gptboot/gptboot.efi.8
38–62

Usually the expanded version comes first, then the initialization:

is installed in the EFI System Partition (ESP).
58

s/reply/rely/

imp marked an inline comment as done.

more nits from rpokala

imp marked 2 inline comments as done.Apr 6 2021, 3:16 AM
stand/efi/gptboot/gptboot.efi.8
268–271

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

stand/i386/gptboot/gptboot.8
42

.Xr gpart.efi 8

.Xr gptboot.efi 8
imp marked 2 inline comments as done.Apr 6 2021, 4:46 AM
imp added inline comments.
stand/efi/gptboot/gptboot.efi.8
268–271

gpart is used with UEFI to mark partitions as bootme or bootonce.

imp marked an inline comment as done.

update for latest feedback from rpokala

This revision is now accepted and ready to land.Apr 6 2021, 5:00 AM
This revision was automatically updated to reflect the committed changes.