picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #10805 from poettering/migrate-boot-loader-interface 

migrate boot loader interface doc from wiki into markdown (split out of #10495)
This commit is contained in:
Lennart Poettering 2018-11-16 17:55:08 +01:00 committed by GitHub
parent 464e48f495 6fdc4831bb
commit 14c4da2ffe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 100 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
docs/BOOT_LOADER_INTERFACE.md Normal file
View File

@ -0,0 +1,76 @@
# The Boot Loader Interface
systemd can interface with the boot loader to receive performance data and
other information, and pass control information. This is only supported on EFI
systems. Data is transferred between the boot loader and systemd in EFI
variables. All EFI variables use the vendor UUID
`4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`.
* The EFI Variable `LoaderTimeInitUSec` contains the timestamp in microseconds
when the loader was initialized. This value is the time spent in the firmware
for initialization, it is formatted as numeric, NUL-terminated, decimal
string, in UTF-16.
* The EFI Variable `LoaderTimeExecUSec` contains the timestamp in microseconds
when the loader finished its work and is about to execute the kernel. The
time spent in the loader is the difference between `LoaderTimeExecUSec` and
`LoaderTimeInitUSec`. This value is formatted the same way as
`LoaderTimeInitUSec`.
* The EFI variable `LoaderDevicePartUUID` contains the partition GUID of the
ESP the boot loader was run from formatted as NUL-terminated UTF16 string, in
normal GUID syntax.
* The EFI variable `LoaderConfigTimeout` contains the boot menu time-out
currently in use. It may be modified both by the boot loader and by the
host. The value should be formatted as numeric, NUL-terminated, decimal
string, in UTF-16. The time is specified in µs.
* Similarly, the EFI variable `LoaderConfigTimeoutOneShot` contains a boot menu
time-out for a single following boot. It is set by the OS in order to request
display of the boot menu on the following boot. When set overrides
`LoaderConfigTimeout`. It is removed automatically after being read by the
boot loader, to ensure it only takes effect a single time. This value is
formatted the same way as `LoaderConfigTimeout`. If set to `0` the boot menu
time-out is turned off, and the menu is shown indefinitely.
* The EFI variable `LoaderEntries` may contain a series of boot loader entry
identifiers, one after the other, each individually NUL terminated. This may
be used to let the OS know which boot menu entries were discovered by the
boot loader. A boot loader entry identifier should be a short, non-empty
alphanumeric string (possibly containing `-`, too). The list should be in the
order the entries are shown on screen during boot. See below regarding a
recommended vocabulary for boot loader entry identifiers.
* The EFI variable `LoaderEntryDefault` contains the default boot loader entry
to use. It contains a NUL-terminated boot loader entry identifier.
* Similarly, the EFI variable `LoaderEntryOneShot` contains the default boot
loader entry to use for a single following boot. It is set by the OS in order
to request booting into a specific menu entry on the following boot. When set
overrides `LoaderEntryDefault`. It is removed automatically after being read
by the boot loader, to ensure it only takes effect a single time. This value
is formatted the same way as `LoaderEntryDefault`.
* The EFI variable `LoaderEntrySelected` contains the boot loader entry
identifier that was booted. It is set by the boot loader and read by
the OS in order to identify which entry has been used for the current boot.
* The EFI variable `LoaderFeatures` contains a 64bit unsigned integer with a
number of flags bits that are set by the boot loader and passed to the OS and
indicate the features the boot loader supports. Specifically, the following
bits are defined:
* `1 << 0` → The boot loader honours `LoaderConfigTimeout` when set.
* `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set.
* `1 << 2` → The boot loader honours `LoaderEntryDefault` when set.
* `1 << 3` → The boot loader honours `LoaderEntryOneShot` when set.
* `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT).
If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze`
will include them in its boot-time analysis. If `LoaderDevicePartUUID` is set,
systemd will mount the ESP that was used for the boot to `/boot`, but only if
that directory is empty, and only if no other file systems are mounted
there. The `systemctl reboot --boot-loader-entry=…` and `systemctl reboot
--boot-loader-menu=…` commands rely on the `LoaderFeatures` ,
`LoaderConfigTimeoutOneShot`, `LoaderEntries`, `LoaderEntryOneShot` variables.

39
docs/index.md
View File

@ -1,25 +1,18 @@
# systemd Documentation
* [The Boot Loader Specification](BOOT_LOADER_SPECIFICATION.md)
* [Control Group APIs and Delegation](CGROUP_DELEGATION.md)
* [The systemd Community Conduct Guidelines](CODE_OF_CONDUCT.md)
* [Code Quality Tools](CODE_QUALITY.md)
* [Contributing](CONTRIBUTING.md)
* [Porting systemd To New Distributions](DISTRO_PORTING.md)
* [Known Environment Variables](ENVIRONMENT.md)
* [Portable Services Introduction](PORTABLE_SERVICES.md)
* [Steps to a successful release](RELEASE.md)
* [What settings are currently available for transient units?](TRANSIENT-SETTINGS.md)
* [Notes for Translators](TRANSLATORS.md)
* [Users, Groups, UIDs and GIDs on `systemd` systems](UIDS-GIDS.md)
* [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT)
* [The Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)
* [The Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
* [Control Group APIs and Delegation](https://systemd.io/CGROUP_DELEGATION)
* [The systemd Community Conduct Guidelines](https://systemd.io/CODE_OF_CONDUCT)
* [Code Quality Tools](https://systemd.io/CODE_QUALITY)
* [Coding style](https://systemd.io/CODING_STYLE)
* [Contributing](https://systemd.io/CONTRIBUTING)
* [Porting systemd To New Distributions](https://systemd.io/DISTRO_PORTING)
* [Known Environment Variables](https://systemd.io/ENVIRONMENT)
* [Hacking on systemd](https://systemd.io/HACKING)
* [Portable Services Introduction](https://systemd.io/PORTABLE_SERVICES)
* [Steps to a successful release](https://systemd.io/RELEASE)
* [What settings are currently available for transient units?](https://systemd.io/TRANSIENT-SETTINGS)
* [Notes for Translators](https://systemd.io/TRANSLATORS)
* [Users, Groups, UIDs and GIDs on `systemd` systems](https://systemd.io/UIDS-GIDS)

2
man/bootctl.xml
View File

@ -148,7 +148,7 @@
<para>
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
<ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
</para>
</refsect1>
</refentry>

10
man/systemd-boot.xml
View File

@ -63,9 +63,8 @@
used from a running system to locate the ESP, list available entries, and install systemd-boot itself.</para>
<para>systemd-boot will provide information about the time spent in UEFI firmware using the <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>. This
information can be displayed using
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This information can be displayed
using <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</refsect1>
@ -343,8 +342,7 @@
<listitem><para>Information about the time spent in various parts of the boot loader. Set by the boot
loader. Use <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
to view this data. These variables are defined by the <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader
Interface</ulink>.</para></listitem>
url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
@ -412,7 +410,7 @@
<citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
<ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
</para>
</refsect1>
</refentry>

5
tools/make-index-md.sh
View File

@ -4,12 +4,13 @@ set -eu
cd "$@"/docs/
(
echo "# systemd Documentation"
echo -e "# systemd Documentation\n"
for f in *.md ; do
if [ "x$f" != "xindex.md" ] ; then
t=`grep "^# " "$f" | head -n 1 | sed -e 's/^#\s*//'`
echo -e "\n* [$t]($f)"
u="https://systemd.io/"`echo "$f" | sed -e 's/.md$//'`
echo "* [$t]($u)"
fi
done
) > index.md