diff --git a/404.html b/404.html index c0bc750..89a07f3 100644 --- a/404.html +++ b/404.html @@ -1 +1 @@ -404 Page not found | UAPI Group Specifications

404

Page Not Found

UAPI Group Specifications

\ No newline at end of file +404 Page not found | UAPI Group Specifications

404

Page Not Found

UAPI Group Specifications

\ No newline at end of file diff --git a/categories/index.html b/categories/index.html index f5f2e3c..a5ac467 100644 --- a/categories/index.html +++ b/categories/index.html @@ -1,4 +1,4 @@ -Categories | UAPI Group Specifications +Categories | UAPI Group Specifications
Categories diff --git a/en.search-data.min.754428460137de0cb44c0566c82a0eea833c2cd9d72a61e05e44e69cf5519d79.js b/en.search-data.min.1b8a345d5259d4378b32770600a03e018967abaefeaee73cb82956b88fdd8212.js similarity index 98% rename from en.search-data.min.754428460137de0cb44c0566c82a0eea833c2cd9d72a61e05e44e69cf5519d79.js rename to en.search-data.min.1b8a345d5259d4378b32770600a03e018967abaefeaee73cb82956b88fdd8212.js index 74c6dab..f97eb84 100644 --- a/en.search-data.min.754428460137de0cb44c0566c82a0eea833c2cd9d72a61e05e44e69cf5519d79.js +++ b/en.search-data.min.1b8a345d5259d4378b32770600a03e018967abaefeaee73cb82956b88fdd8212.js @@ -10,6 +10,7 @@ Optionally, an Extended Boot Loader Partition (XBOOTLDR partition for short) — Each partition type mentioned above can be present only once on the same disk. Note: These partitions are shared among all OS installations on the same disk. Instead of maintaining one boot partition per installed OS (as /boot/ was traditionally handled), all installed OSes use the same place for boot loader menu entries. For systems where the firmware is able to read file systems directly, the ESP must — and the MBR boot and GPT XBOOTLDR partition should — be a file system readable by the firmware. For most systems this means VFAT (16 or 32 bit). Applications accessing both partitions should hence not assume that fancier file system features such as symlinks, hardlinks, access control or case sensitivity are supported. +Note that the partitions described here are not the exclusive territory of this specification. This specification only defines semantics of the /loader/entries/ directory (along with the companion file /loader/entries.srel) and the /EFI/Linux/ directory inside the file system, but it doesn\u0026rsquo;t define other contents of the file system. Boot loaders, firmware, and other software implementing this specification may choose to place other files and directories in the same file system. For example, boot loaders might install their own boot code on the same partition; this is particularly common in the case of the ESP. Implementations of this specification must be able to operate correctly if files or directories other than /loader/entries/ and /EFI/Linux/ are found in the top level directory. Implementations that add their own files or directories to the file systems should use well-named directories, to make name collisions between multiple users of the file system unlikely. The \$BOOT Partition Placeholder # In the text below, the placeholder \$BOOT will be used to refer to the partition determined as follows: On disks with an MBR partition table: → the boot partition, as described above On disks with a GPT partition table: → the XBOOTLDR partition if it exists @@ -24,16 +25,15 @@ These partitions shall be determined during installation time, and /etc/fstab en Mount Points # It is recommended to mount \$BOOT (either XBOOTLDR or the ESP) to /boot/. If both XBOOTLDR and the ESP are present, the ESP should be mounted to /efi/. Effectively, this means that /boot/ is the location where new boot entries shall be written to. For the boot loader itself, the situation is more complicated, because its files may be located under /boot/ or /efi/, depending on whether XBOOTLDR exists. (Mounting the ESP to /boot/efi/, as was traditionally done, is not recommended. Such a nested setup complicates an implementation via direct autofs mounts — as implemented by systemd for example —, as establishing the inner autofs will trigger the outer one. Mounting the two partitions via autofs is recommended because the simple VFAT file system has weak data integrity properties and should remain unmounted whenever possible.) -Boot Loader Entries # This specification defines two types of boot loader entries. The first type is text based, very simple, and suitable for a variety of firmware, architecture and image types (\u0026ldquo;Type #1\u0026rdquo;). The second type is specific to EFI, but allows single-file images that embed all metadata in the kernel binary itself, which is useful to cryptographically sign them as one file for the purpose of SecureBoot (\u0026ldquo;Type #2\u0026rdquo;). +Boot Loader Entries # This specification defines two types of boot loader entries. The first type is text based, very simple, and suitable for a variety of firmware, architecture and image types (\u0026ldquo;Type #1\u0026rdquo;). The second type is specific to EFI, but allows single-file images that combine the kernel binary with the configuration, initrd, and other components of the boot loader entry. This is also useful because the file can be cryptographically signed for the purposes of SecureBoot (\u0026ldquo;Type #2\u0026rdquo;, Unified Kernel Images). Not all boot loader entries will apply to all systems. For example, Type #1 entries that use the efi key and all Type #2 entries only apply to EFI systems. Entries using the architecture key might specify an architecture that doesn\u0026rsquo;t match the local one. Boot loaders should ignore all entries that don\u0026rsquo;t match the local platform and what the boot loader can support, and hide them from the user. Only entries matching the feature set of boot loader and system shall be considered and displayed. This allows image builders to put together images that transparently support multiple different architectures. -Note that the three partitions described above are not supposed to be the exclusive territory of this specification. This specification only defines semantics of the /loader/entries/ directory (along with the companion file /loader/entries.srel) and the /EFI/Linux/ directory inside the file system, but it doesn\u0026rsquo;t intend to define contents of the rest of the file system. Boot loaders, firmware, and other software implementing this specification may choose to place other files and directories in the same file system. For example, boot loaders that implement this specification might install their own boot code on the same partition; this is particularly common in the case of the ESP. Implementations of this specification must be able to operate correctly if files or directories other than /loader/entries/ and /EFI/Linux/ are found in the top level directory. Implementations that add their own files or directories to the file systems should use well-named directories, to make name collisions between multiple users of the file system unlikely. Type #1 Boot Loader Specification Entries # /loader/entries/ in \$BOOT is the primary directory containing Type #1 drop-in snippets defining boot entries, one .conf file for each boot menu item. Each OS may provide one or more such entries. If the ESP is separate from \$BOOT it may also contain a /loader/entries/ directory, where the boot loader should look for boot entry snippets, as an additional source. The boot loader should enumerate both directories and present a merged list to the user. Note that this is done for compatibility only: while boot loaders should look in both places, OSes should only add their files to \$BOOT. Note: In all cases the /loader/entries/ directory should be located directly in the root of the ESP or XBOOTLDR filesystem. Specifically, the /loader/entries/ directory should not be located under the /EFI/ subdirectory on the ESP. The file name of the boot entry snippets is used for identification of the boot item but shall never be presented to the user in the UI. The file name may be chosen freely but should be unique enough to avoid clashes between OS installations. More specifically, it is suggested to include the entry-token (see kernel-install) or machine ID (see /etc/machine-id), and the kernel version (as returned by uname -r, including the OS identifier), so that the whole filename is \$BOOT/loader/entries/\u0026lt;entry-token-or-machine-id\u0026gt;-\u0026lt;version\u0026gt;.conf. Example: \$BOOT/loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf. In order to maximize compatibility with file system implementations and restricted boot loader environments, and to minimize conflicting character use with other programs, file names shall be chosen from a restricted character set: ASCII upper and lower case characters, digits, \u0026ldquo;+\u0026rdquo;, \u0026ldquo;-\u0026rdquo;, \u0026ldquo;_\u0026rdquo; and \u0026ldquo;.\u0026rdquo;. Also, the file names should have a length of at least one and at most 255 characters (including the file name suffix). -These boot loader menu snippets shall be UNIX-style text files (i.e. lines separated by a single newline character), in the UTF-8 encoding. The boot loader menu snippets are loosely inspired by Grub1\u0026rsquo;s configuration syntax. Lines beginning with \u0026ldquo;#\u0026rdquo; are used for comments and shall be ignored. The first word of a line is used as key and is separated by one or more spaces from the value. +These boot loader menu snippets shall be UNIX-style text files (i.e. lines separated by a single newline character), in the UTF-8 encoding. The boot loader menu snippets are loosely inspired by Grub1\u0026rsquo;s configuration syntax. Lines beginning with \u0026ldquo;#\u0026rdquo; are used for comments and shall be ignored. The first word of a line is used as key and is separated by one or more spaces from the value. The rest of the line contains the value, a literal string. Type #1 Boot Loader Entry Keys # The following keys are recognized: title is a human-readable title for this menu item to be displayed in the boot menu. It is a good idea to initialize this from the PRETTY_NAME= of os-release. This name should be descriptive and does not have to be unique. If a boot loader discovers two entries with the same title it should show more than just the raw title in the UI, for example by appending the version field. This field is optional. Example: title Fedora 18 (Spherical Cow) @@ -44,11 +44,12 @@ machine-id is the machine ID of the OS. This can be used by boot loaders and app Example: machine-id 4098b3f648d74c13b1f04ccfba7798e8 sort-key is a short string used for sorting entries on display. This should typically be initialized from the IMAGE_ID= or ID= fields of os-release, possibly with an additional suffix. This field is optional. Example: sort-key fedora -linux is the Linux kernel image to execute and takes a path relative to the root of the file system containing the boot entry snippet itself. It is recommended that every distribution creates an entry-token/machine-id and version specific subdirectory and places its kernels and initrd images there (see below). +linux specifies the Linux kernel image to execute. The value is a path relative to the root of the file system containing the boot entry snippet itself. +It is recommended that every distribution creates a subdirectory specific to the entry-token or machine-id, and underneath that, subdirectories specific to the kernel version, and places places the kernel and initrd images there (see below). Example: linux /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux -initrd is the initrd cpio image to use when executing the kernel. This key may appear more than once in which case all specified images are used, in the order they are listed. -Example: initrd 6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd -efi refers to an arbitrary EFI program. If this key is set, and the system is not an EFI system, this entry should be hidden. +initrd specifies the initrd to use when executing the kernel (cpio image). The value is a path relative to the root of the file system containing the boot entry snippet itself. This key may appear more than once, in which case all specified images are used, in the order they are listed. +Example: +initrd /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd initrd /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/modules efi refers to an arbitrary EFI program. If this key is set, and the system is not an EFI system, this entry should be hidden. options shall contain kernel parameters to pass to the Linux kernel to spawn. This key is optional and may appear more than once in which case all specified parameters are combined in the order they are listed. Example: options root=UUID=6d3376e4-fc93-4509-95ec-a21d68011da2 quiet devicetree refers to the binary device tree to use when executing the kernel. This key is optional. diff --git a/en.search.min.bb98677af40b38d431935529772ab91ba2727b6e10e385b47db24d6ed31b0d28.js b/en.search.min.2271c959113e55f3cd796ba2a8c8c03b979217785515556e8c96471e55916c11.js similarity index 89% rename from en.search.min.bb98677af40b38d431935529772ab91ba2727b6e10e385b47db24d6ed31b0d28.js rename to en.search.min.2271c959113e55f3cd796ba2a8c8c03b979217785515556e8c96471e55916c11.js index 4fd715f..6c1d108 100644 --- a/en.search.min.bb98677af40b38d431935529772ab91ba2727b6e10e385b47db24d6ed31b0d28.js +++ b/en.search.min.2271c959113e55f3cd796ba2a8c8c03b979217785515556e8c96471e55916c11.js @@ -1 +1 @@ -"use strict";(function(){const e=document.querySelector("#book-search-input"),t=document.querySelector("#book-search-results");if(!e)return;e.addEventListener("focus",n),e.addEventListener("keyup",s),document.addEventListener("keypress",i);function i(t){if(e===document.activeElement)return;const n=String.fromCharCode(t.charCode);if(!a(n))return;e.focus(),t.preventDefault()}function a(t){const n=e.getAttribute("data-hotkeys")||"";return n.indexOf(t)>=0}function n(){e.removeEventListener("focus",n),e.required=!0,o("/specifications/flexsearch.min.js"),o("/specifications/en.search-data.min.754428460137de0cb44c0566c82a0eea833c2cd9d72a61e05e44e69cf5519d79.js",function(){e.required=!1,s()})}function s(){for(;t.firstChild;)t.removeChild(t.firstChild);if(!e.value)return;const n=window.bookSearchIndex.search(e.value,10);n.forEach(function(e){const n=r("
    • "),s=n.querySelector("a"),o=n.querySelector("small");s.href=e.href,s.textContent=e.title,o.textContent=e.section,t.appendChild(n)})}function o(e,t){const n=document.createElement("script");n.defer=!0,n.async=!1,n.src=e,n.onload=t,document.head.appendChild(n)}function r(e){const t=document.createElement("div");return t.innerHTML=e,t.firstChild}})() \ No newline at end of file +"use strict";(function(){const e=document.querySelector("#book-search-input"),t=document.querySelector("#book-search-results");if(!e)return;e.addEventListener("focus",n),e.addEventListener("keyup",s),document.addEventListener("keypress",i);function i(t){if(e===document.activeElement)return;const n=String.fromCharCode(t.charCode);if(!a(n))return;e.focus(),t.preventDefault()}function a(t){const n=e.getAttribute("data-hotkeys")||"";return n.indexOf(t)>=0}function n(){e.removeEventListener("focus",n),e.required=!0,o("/specifications/flexsearch.min.js"),o("/specifications/en.search-data.min.1b8a345d5259d4378b32770600a03e018967abaefeaee73cb82956b88fdd8212.js",function(){e.required=!1,s()})}function s(){for(;t.firstChild;)t.removeChild(t.firstChild);if(!e.value)return;const n=window.bookSearchIndex.search(e.value,10);n.forEach(function(e){const n=r("
    • "),s=n.querySelector("a"),o=n.querySelector("small");s.href=e.href,s.textContent=e.title,o.textContent=e.section,t.appendChild(n)})}function o(e,t){const n=document.createElement("script");n.defer=!0,n.async=!1,n.src=e,n.onload=t,document.head.appendChild(n)}function r(e){const t=document.createElement("div");return t.innerHTML=e,t.firstChild}})() \ No newline at end of file diff --git a/index.html b/index.html index cf8f537..43e64a5 100644 --- a/index.html +++ b/index.html @@ -1,4 +1,4 @@ -UAPI Group Specifications | UAPI Group Specifications +UAPI Group Specifications | UAPI Group Specifications
    UAPI Group Specifications diff --git a/specs/boot_loader_specification/index.html b/specs/boot_loader_specification/index.html index 2617b75..cc214b3 100644 --- a/specs/boot_loader_specification/index.html +++ b/specs/boot_loader_specification/index.html @@ -1,6 +1,6 @@ Boot Loader Specification | UAPI Group Specifications +Operating systems cooperatively manage boot loader menu entry directories that contain drop-in files, making multi-boot scenarios easy to support. Boot menu entries are defined via two simple formats that can be understood by different boot loader implementations, operating systems, and userspace programs.">Boot Loader Specification | UAPI Group Specifications
    Boot Loader Specification

    The Boot Loader Specification @@ -32,10 +32,24 @@ /boot/ was traditionally handled), all installed OSes use the same place for boot loader menu entries.

    For systems where the firmware is able to read file systems directly, the ESP must — and the MBR boot and GPT XBOOTLDR partition should — be a file system -readable by the firmware. For most systems this means VFAT (16 or 32 -bit). Applications accessing both partitions should hence not assume that +readable by the firmware. For most systems this means VFAT (16 or 32 bit). +Applications accessing both partitions should hence not assume that fancier file system features such as symlinks, hardlinks, access control or -case sensitivity are supported.

    The $BOOT Partition Placeholder +case sensitivity are supported.

    Note that the partitions described here are not the exclusive territory of this specification. +This specification only defines semantics of the /loader/entries/ directory +(along with the companion file /loader/entries.srel) +and the /EFI/Linux/ directory inside the file system, +but it doesn’t define other contents of the file system. +Boot loaders, firmware, and other software implementing this specification +may choose to place other files and directories in the same file system. +For example, +boot loaders might install their own boot code on the same partition; +this is particularly common in the case of the ESP. +Implementations of this specification must be able to operate correctly if +files or directories other than /loader/entries/ and /EFI/Linux/ are found in the top level directory. +Implementations that add their own files or directories to the file systems +should use well-named directories, +to make name collisions between multiple users of the file system unlikely.

    The $BOOT Partition Placeholder #

    In the text below, the placeholder $BOOT will be used to refer to the partition determined as follows:

    1. On disks with an MBR partition table: → the boot partition, as described above

    2. On disks with a GPT partition table: → the XBOOTLDR partition if it exists

    3. Otherwise, on disks with a GPT partition table: → the ESP

    $BOOT is the primary place to put boot menu entry resources into, but typically not the only one. Most importantly, boot loaders should also pick up @@ -62,32 +76,21 @@ the inner autofs will trigger the outer one. Mounting the two partitions via autofs is recommended because the simple VFAT file system has weak data integrity properties and should remain unmounted whenever possible.)

    Boot Loader Entries -#

    This specification defines two types of boot loader entries. The first type is -text based, very simple, and suitable for a variety of firmware, architecture -and image types (“Type #1”). The second type is specific to EFI, but allows -single-file images that embed all metadata in the kernel binary itself, which -is useful to cryptographically sign them as one file for the purpose of -SecureBoot (“Type #2”).

    Not all boot loader entries will apply to all systems. For example, Type #1 +#

    This specification defines two types of boot loader entries. +The first type is text based, very simple, +and suitable for a variety of firmware, architecture and image types (“Type #1”). +The second type is specific to EFI, +but allows single-file images that combine the kernel binary +with the configuration, initrd, and other components of the boot loader entry. +This is also useful because the file can be cryptographically signed +for the purposes of SecureBoot (“Type #2”, Unified Kernel Images).

    Not all boot loader entries will apply to all systems. For example, Type #1 entries that use the efi key and all Type #2 entries only apply to EFI systems. Entries using the architecture key might specify an architecture that doesn’t match the local one. Boot loaders should ignore all entries that don’t match the local platform and what the boot loader can support, and hide them from the user. Only entries matching the feature set of boot loader and system shall be considered and displayed. This allows image builders to put together -images that transparently support multiple different architectures.

    Note that the three partitions described above are not supposed to be the -exclusive territory of this specification. This specification only defines -semantics of the /loader/entries/ directory (along with the companion file -/loader/entries.srel) and the /EFI/Linux/ directory inside the file system, -but it doesn’t intend to define contents of the rest of the file system. Boot -loaders, firmware, and other software implementing this specification may -choose to place other files and directories in the same file system. For -example, boot loaders that implement this specification might install their own -boot code on the same partition; this is particularly common in the case of the -ESP. Implementations of this specification must be able to operate correctly if -files or directories other than /loader/entries/ and /EFI/Linux/ are found -in the top level directory. Implementations that add their own files or -directories to the file systems should use well-named directories, to make name -collisions between multiple users of the file system unlikely.

    Type #1 Boot Loader Specification Entries +images that transparently support multiple different architectures.

    Type #1 Boot Loader Specification Entries #

    /loader/entries/ in $BOOT is the primary directory containing Type #1 drop-in snippets defining boot entries, one .conf file for each boot menu item. Each OS may provide one or more such entries.

    If the ESP is separate from $BOOT it may also contain a /loader/entries/ @@ -113,12 +116,14 @@ with other programs, file names shall be chosen from a restricted character set: ASCII upper and lower case characters, digits, “+”, “-”, “_” and “.”. Also, the file names should have a length of at least one and at most 255 -characters (including the file name suffix).

    These boot loader menu snippets shall be UNIX-style text files (i.e. lines -separated by a single newline character), in the UTF-8 encoding. The -boot loader menu snippets are loosely inspired by Grub1’s configuration syntax. -Lines beginning with “#” are used for comments and shall be ignored. The first -word of a line is used as key and is separated by one or more spaces from the -value.

    Type #1 Boot Loader Entry Keys +characters (including the file name suffix).

    These boot loader menu snippets shall be UNIX-style text files +(i.e. lines separated by a single newline character), +in the UTF-8 encoding. +The boot loader menu snippets are loosely inspired by Grub1’s configuration syntax. +Lines beginning with “#” are used for comments and shall be ignored. +The first word of a line is used as key +and is separated by one or more spaces from the value. +The rest of the line contains the value, a literal string.

    Type #1 Boot Loader Entry Keys #

    The following keys are recognized: