|
| 1 | +# The Boot Loader Interface |
| 2 | + |
| 3 | +systemd can interface with the boot loader to receive performance data and |
| 4 | +other information, and pass control information. This is only supported on EFI |
| 5 | +systems. Data is transferred between the boot loader and systemd in EFI |
| 6 | +variables. All EFI variables use the vendor UUID |
| 7 | +`4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`. |
| 8 | + |
| 9 | +* The EFI Variable `LoaderTimeInitUSec` contains the timestamp in microseconds |
| 10 | + when the loader was initialized. This value is the time spent in the firmware |
| 11 | + for initialization, it is formatted as numeric, NUL-terminated, decimal |
| 12 | + string, in UTF-16. |
| 13 | + |
| 14 | +* The EFI Variable `LoaderTimeExecUSec` contains the timestamp in microseconds |
| 15 | + when the loader finished its work and is about to execute the kernel. The |
| 16 | + time spent in the loader is the difference between `LoaderTimeExecUSec` and |
| 17 | + `LoaderTimeInitUSec`. This value is formatted the same way as |
| 18 | + `LoaderTimeInitUSec`. |
| 19 | + |
| 20 | +* The EFI variable `LoaderDevicePartUUID` contains the partition GUID of the |
| 21 | + ESP the boot loader was run from formatted as NUL-terminated UTF16 string, in |
| 22 | + normal GUID syntax. |
| 23 | + |
| 24 | +* The EFI variable `LoaderConfigTimeout` contains the boot menu time-out |
| 25 | + currently in use. It may be modified both by the boot loader and by the |
| 26 | + host. The value should be formatted as numeric, NUL-terminated, decimal |
| 27 | + string, in UTF-16. The time is specified in µs. |
| 28 | + |
| 29 | +* Similarly, the EFI variable `LoaderConfigTimeoutOneShot` contains a boot menu |
| 30 | + time-out for a single following boot. It is set by the OS in order to request |
| 31 | + display of the boot menu on the following boot. When set overrides |
| 32 | + `LoaderConfigTimeout`. It is removed automatically after being read by the |
| 33 | + boot loader, to ensure it only takes effect a single time. This value is |
| 34 | + formatted the same way as `LoaderConfigTimeout`. If set to `0` the boot menu |
| 35 | + time-out is turned off, and the menu is shown indefinitely. |
| 36 | + |
| 37 | +* The EFI variable `LoaderEntries` may contain a series of boot loader entry |
| 38 | + identifiers, one after the other, each individually NUL terminated. This may |
| 39 | + be used to let the OS know which boot menu entries were discovered by the |
| 40 | + boot loader. A boot loader entry identifier should be a short, non-empty |
| 41 | + alphanumeric string (possibly containing `-`, too). The list should be in the |
| 42 | + order the entries are shown on screen during boot. See below regarding a |
| 43 | + recommended vocabulary for boot loader entry identifiers. |
| 44 | + |
| 45 | +* The EFI variable `LoaderEntryDefault` contains the default boot loader entry |
| 46 | + to use. It contains a NUL-terminated boot loader entry identifier. |
| 47 | + |
| 48 | +* Similarly, the EFI variable `LoaderEntryOneShot` contains the default boot |
| 49 | + loader entry to use for a single following boot. It is set by the OS in order |
| 50 | + to request booting into a specific menu entry on the following boot. When set |
| 51 | + overrides `LoaderEntryDefault`. It is removed automatically after being read |
| 52 | + by the boot loader, to ensure it only takes effect a single time. This value |
| 53 | + is formatted the same way as `LoaderEntryDefault`. |
| 54 | + |
| 55 | +* The EFI variable `LoaderEntrySelected` contains the boot loader entry |
| 56 | + identifier that was booted. It is set by the boot loader and read by |
| 57 | + the OS in order to identify which entry has been used for the current boot. |
| 58 | + |
| 59 | +* The EFI variable `LoaderFeatures` contains a 64bit unsigned integer with a |
| 60 | + number of flags bits that are set by the boot loader and passed to the OS and |
| 61 | + indicate the features the boot loader supports. Specifically, the following |
| 62 | + bits are defined: |
| 63 | + |
| 64 | + * `1 << 0` → The boot loader honours `LoaderConfigTimeout` when set. |
| 65 | + * `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set. |
| 66 | + * `1 << 2` → The boot loader honours `LoaderEntryDefault` when set. |
| 67 | + * `1 << 3` → The boot loader honours `LoaderEntryOneShot` when set. |
| 68 | + * `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT). |
| 69 | + |
| 70 | +If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze` |
| 71 | +will include them in its boot-time analysis. If `LoaderDevicePartUUID` is set, |
| 72 | +systemd will mount the ESP that was used for the boot to `/boot`, but only if |
| 73 | +that directory is empty, and only if no other file systems are mounted |
| 74 | +there. The `systemctl reboot --boot-loader-entry=…` and `systemctl reboot |
| 75 | +--boot-loader-menu=…` commands rely on the `LoaderFeatures` , |
| 76 | +`LoaderConfigTimeoutOneShot`, `LoaderEntries`, `LoaderEntryOneShot` variables. |
0 commit comments