Merge pull request #9350 from poettering/bls-fixes

various fixes to the systemd-boot documentation

5 files changed, 80 insertions, 54 deletions

diff --git a/NEWS b/NEWS
index ddf6b031e..10f632216 100644
--- a/NEWS
+++ b/NEWS
@@ -302,6 +302,13 @@ CHANGES WITH 239 in spe:
           https://github.com/systemd/systemd/blob/master/doc/PORTABLE_SERVICES.md
           https://github.com/systemd/systemd/blob/master/doc/CODE_QUALITY.md
 
+        * The Boot Loader Specification has been added to the source tree.
+
+          https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md
+
+          While moving it into our source tree we have updated it and further
+          changes are now accepted through the usual github PR workflow.
+
         * pam_systemd will now look for PAM userdata fields systemd.memory_max,
           systemd.tasks_max, systemd.cpu_weight, systemd.io_weight set by
           earlier PAM modules. The data in these fields is used to initialize
diff --git a/doc/BOOT_LOADER_SPECIFICATION.md b/doc/BOOT_LOADER_SPECIFICATION.md
index d31bd341f..dc67f2ffc 100644
--- a/doc/BOOT_LOADER_SPECIFICATION.md
+++ b/doc/BOOT_LOADER_SPECIFICATION.md
@@ -34,12 +34,14 @@ The EFI specification provides a boot options logic that can offer similar funct
 
 Everything described below is located on a placeholder file system `$BOOT`. The installer program should pick `$BOOT` according to the following rules:
 
-* If the OS is installed on a disk with MBR disk label, and a partition with the MBR type id of 0xEA already exists it should be used as `$BOOT`.
-* Otherwise, if the the OS is installed on a disk with MBR disk label, a new partition with MBR type id of 0xEA shall be created, of a suitable size (let's say 500MB), and it should be used as `$BOOT`.
-* If the OS is installed on a disk with GPT disk label, and a partition with the GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 already exists, it should be used as `$BOOT`.
-* Otherwise, if the OS is installed on a disk with GPT disk label, and an ESP partition (i.e. with the GPT type UID of c12a7328-f81f-11d2-ba4b-00a0c93ec93b) already exists and is large enough (let's say 250MB) and otherwise qualifies, it should be used as `$BOOT`.
-* Otherwise, if the OS is installed on a disk with GPT disk label, and if the ESP partition already exists but is too small, a new suitably sized (let's say 500MB) partition with GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 shall be created and it should be used as `$BOOT`.
-* Otherwise, if the OS is installed on a disk with GPT disk label, and no ESP partition exists yet, a new suitably sized (let's say 500MB) ESP should be created and should be used as `$BOOT`.
+* On disks with MBR disk labels
+  * If the OS is installed on a disk with MBR disk label, and a partition with the MBR type id of 0xEA already exists it should be used as `$BOOT`.
+  * Otherwise, if the the OS is installed on a disk with MBR disk label, a new partition with MBR type id of 0xEA shall be created, of a suitable size (let's say 500MB), and it should be used as `$BOOT`.
+* On disks with GPT disk labels
+  * If the OS is installed on a disk with GPT disk label, and a partition with the GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 already exists, it should be used as `$BOOT`.
+  * Otherwise, if the OS is installed on a disk with GPT disk label, and an ESP partition (i.e. with the GPT type UID of c12a7328-f81f-11d2-ba4b-00a0c93ec93b) already exists and is large enough (let's say 250MB) and otherwise qualifies, it should be used as `$BOOT`.
+  * Otherwise, if the OS is installed on a disk with GPT disk label, and if the ESP partition already exists but is too small, a new suitably sized (let's say 500MB) partition with GPT type GUID of bc13c2ff-59e6-4262-a352-b275fd6f7172 shall be created and it should be used as `$BOOT`.
+  * Otherwise, if the OS is installed on a disk with GPT disk label, and no ESP partition exists yet, a new suitably sized (let's say 500MB) ESP should be created and should be used as `$BOOT`.
 
 This placeholder file system shall be determined during _installation time_, and an fstab entry maybe be created. It should be mounted to either /boot or /efi. Additional locations like /boot/efi, with /boot being a separate file system, might be supported by implementations. This is not recommended because the mounting of `$BOOT` is then dependent on and requires the mounting of the intermediate file system.
 
@@ -64,12 +66,13 @@ These configuration snippets shall be Unix-style text files (i.e. line separatio
 * `version` shall contain a human readable version string for this menu item. This is usually the kernel version and is intended for use by OSes to install multiple kernel versions at the same time with the same `title` field. This field shall be in a syntax that is useful for Debian-style version sorts, so that the boot loader UI can determine the newest version easily and show it first or preselect it automatically. This field is optional. Example: `3.7.2-201.fc18.x86_64`
 * `machine-id` shall contain the machine ID of the OS `/etc/machine-id`. This is useful for boot loaders and applications to filter out boot entries, for example to show only a single newest kernel per OS, or to group items by OS, or to maybe filter out the currently booted OS in UIs that want to show only other installed operating systems. This ID shall be formatted as 32 lower case hexadecimal characters (i.e. without any UUID formatting). This key is optional. Example: `4098b3f648d74c13b1f04ccfba7798e8`
 * `linux` refers to the kernel to spawn, and shall be a path relative to the `$BOOT` directory. It is recommended that every distribution creates a machine id and version specific subdirectory below `$BOOT` and places its kernels and initial RAM disk images there. Example: `/6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux`.
-* `initrd` refers to the initrd to use when executing the kernel. This also shall be a path relative to the `$BOOT` directory. This key is optional. Example: `6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd`
+* `initrd` refers to the initrd to use when executing the kernel. This also shall be a path relative to the `$BOOT` directory. This key is optional. This key may appear more than once in which case all specified images are used, in the order they are listed. Example: `6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd`
 * `efi` to spawn arbitrary EFI programs. This also takes a path relative to `$BOOT`. This key is only available on EFI systems.
 * `options` shall contain kernel parameters to pass to the Linux kernel to spawn. This key is optional.
 * `devicetree` refers to the binary device tree to use when executing the
 kernel. This also shall be a path relative to the `$BOOT` directory. This
 key is optional. Example: `6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.armv7hl/tegra20-paz00.dtb`
+* `architecture` refers to the UEFI architecture this entry is defined for. If specified and this does not match the local UEFI system architecture the entry is hidden.
 
 Each configuration drop-in snippet must include at least a `linux` or an `efi` key, and is otherwise not valid. Here's an example for a complete drop-in file:
 
@@ -131,8 +134,7 @@ There are a couple of items that are out of focus for this specifications:
 
 ## Links
 
-<strike>http://www.freedesktop.org/wiki/Software/gummiboot/</strike><br>
-https://www.freedesktop.org/software/systemd/man/systemd-boot.html<br>
-https://www.freedesktop.org/software/systemd/man/bootctl.html
+[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
+[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)
 
-http://pkgs.fedoraproject.org/cgit/grub2.git/tree/0460-blscfg-add-blscfg-module-to-parse-Boot-Loader-Specif.patch?h=f20
+[Obsolete patch adding Boot Loader Specification support to GNU grub 2](http://pkgs.fedoraproject.org/cgit/grub2.git/tree/0460-blscfg-add-blscfg-module-to-parse-Boot-Loader-Specif.patch?h=f20)
diff --git a/man/bootctl.xml b/man/bootctl.xml
index 0f8d0e014..9521dc9d9 100644
--- a/man/bootctl.xml
+++ b/man/bootctl.xml
@@ -126,7 +126,7 @@
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-      <ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader Specification</ulink>,
+      <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>,
       <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
     </para>
   </refsect1>
diff --git a/man/kernel-install.xml b/man/kernel-install.xml
index 6d8201af1..cd9756662 100644
--- a/man/kernel-install.xml
+++ b/man/kernel-install.xml
@@ -167,7 +167,7 @@
     <para>
       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>
+      <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>
     </para>
   </refsect1>
 
diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml
index 09efbd34a..5cd8a3815 100644
--- a/man/systemd-boot.xml
+++ b/man/systemd-boot.xml
@@ -25,48 +25,51 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>systemd-boot</command> or <command>sd-boot</command> is a simple
-    UEFI boot manager, previously known as <command>gummiboot</command>. It provides
-    a graphical menu to select the entry to boot and an editor for the kernel command
-    line. systemd-boot is only useful on machines using UEFI.
-    </para>
-
-    <para>systemd-boot loads information from the EFI system partition (ESP), usually
-    mounted at <filename>/boot</filename>, <filename>/efi</filename>, or
-    <filename>/boot/efi</filename>. Configuration file fragments, kernels, initrds,
-    other EFI images need to reside on the ESP. Linux kernels must be built with
-    <option>CONFIG_EFI_STUB</option> to be able to be directly executed as an EFI
-    image. systemd-boot will automatically list other boot entries registered as EFI boot
-    variables, and a list of kernels from configuration files following the <ulink
-    url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader
-    Specification</ulink> located under <filename>/loader/entries/</filename> on the
-    ESP.</para>
-
-    <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    may be used to copy kernel images onto the ESP and to generate entries compliant
-    with the Boot Loader Specification.
-    <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    may be 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
+    <para><command>systemd-boot</command> (short: <command>sd-boot</command>) is a simple UEFI boot manager. It
+    provides a graphical menu to select the entry to boot and an editor for the kernel command line. systemd-boot
+    supports systems with an UEFI firmware only.</para>
+
+    <para>systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at
+    <filename>/boot</filename>, <filename>/efi</filename>, or <filename>/boot/efi</filename> during OS
+    runtime. Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on
+    the ESP. Linux kernels must be built with <option>CONFIG_EFI_STUB</option> to be able to be directly executed as an
+    EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following
+    sources:</para>
+
+    <itemizedlist>
+      <listitem><para>Boot entries defined with <ulink
+      url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
+      Specification</ulink> description files located in <filename>/loader/entries/</filename> on the ESP. These
+      usually describe Linux kernel images with associated initrd images, but alternatively may also describe
+      arbitrary other EFI executables.</para></listitem>
+
+      <listitem><para>Unified kernel images following the <ulink
+      url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot
+      Loader Specification</ulink>, as executable EFI binaries in
+      <filename>/EFI/Linux/</filename> on the ESP</para></listitem>
+
+      <listitem><para>The Microsoft Windows EFI boot manager, if installed</para></listitem>
+
+      <listitem><para>The Apple MacOS X boot manager, if installed</para></listitem>
+
+      <listitem><para>The EFI Shell binary, if installed</para></listitem>
+
+      <listitem><para>A reboot into the UEFI firmware setup option, if supported by the firmware</para></listitem>
+    </itemizedlist>
+
+    <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> may be
+    used to copy kernel images onto the ESP and to generate description files compliant with the Boot Loader
+    Specification. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> may be
+    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>.
     </para>
   </refsect1>
 
   <refsect1>
-    <title>Configuration</title>
-
-    <para>systemd-boot reads configuration like the timeout and default entry from
-    <filename>/loader/loader.conf</filename> on the ESP and from EFI variables. See
-    <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-    </para>
-  </refsect1>
-
-  <refsect1>
     <title>Key bindings</title>
     <para>The following keys may be used in the boot menu:</para>
 
@@ -171,7 +174,7 @@
         <term>7</term>
         <term>8</term>
         <term>9</term>
-        <listitem><para>Entry number 1 .. 9</para></listitem>
+        <listitem><para>Boot entry number 1 … 9</para></listitem>
       </varlistentry>
     </variablelist>
 
@@ -220,13 +223,27 @@
   </refsect1>
 
   <refsect1>
+    <title>Files</title>
+
+    <para>The files systemd-boot reads generally reside on the UEFI ESP which is usually mounted to
+    <filename>/boot/</filename>, <filename>/efi/</filename> or <filename>/boot/efi</filename> during OS
+    runtime. systemd-boot reads runtime configuration such as the boot timeout and default entry from
+    <filename>/loader/loader.conf</filename> on the ESP (in combination with data read from EFI variables). See
+    <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Boot entry
+    description files following the <ulink
+    url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
+    Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP. Unified kernel boot entries
+    following the <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot
+    Loader Specification</ulink> are read from <filename>/EFI/Linux/</filename> on the ESP.</para>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader Specification</ulink>,
-      <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>,
-      <ulink url="https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/">upstream wiki page</ulink>
+      <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>,
+      <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>
     </para>
   </refsect1>
 </refentry>