From f6a33a1c961688f9ec41fc1119dd4bd04d4a294c Mon Sep 17 00:00:00 2001 From: Nikita Travkin Date: Wed, 17 Sep 2025 15:50:30 +0500 Subject: [PATCH] specs/bls: Add devicetree-dir key There are many devices that require booting with devicetree. Until now, most of those devices were of embedded kind where one would be expected to maintain a device-specific OS image. For those devices it makes sense to just hardcode devicetree name in the boot loader entry. In recent years, however, many devices became available that don't fit into such "embedded" category and instead would be more useful with a generic OS, such as Qualcomm WoA laptops. As those laptops can't be used with their terribly disfuncitonal ACPI implementation, distribution have to rely on manually loading appropriate devicetrees. Unfortunately, for rapidly evolving targets like those Qualcomm laptops, it's critical to boot the kernel with matching version of the devicetree, as many features are added rapidly. UKI images already have provisions to support such devices, namely .dtbauto section of the UKI that allows the implementation to include as many DTBs into the same image as one wants. However same can't be said for BLS#1 boot entries. To solve this discrepency, document a new "devicetree-dir" key, that would define path to a directory with devicetree files, letting the bootloader implementation to pick an appropriate devicetree and load it. --- specs/boot_loader_specification.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/specs/boot_loader_specification.md b/specs/boot_loader_specification.md index 8020ef08..7ddfb5ed 100644 --- a/specs/boot_loader_specification.md +++ b/specs/boot_loader_specification.md @@ -337,10 +337,18 @@ The following keys are recognized: Example: `devicetree 6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.armv7hl/tegra20-paz00.dtb` +* `devicetree-dir` refers to a directory with binary device tree files. + Bootloader should pick a device tree file compatible with the system. + The way, in which bootloader chooses the correct file is out of scope + for this specification. This key is optional and must be ignored if + the `devicetree` key exists. + + Example: `devicetree-dir 6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.armv7hl/` + * `devicetree-overlay` refers to a list of device tree overlays that should be applied by the boot loader. Multiple overlays are separated by spaces and applied in the same order as they are listed. This key is optional but - depends on the `devicetree` key. + depends on either `devicetree` key or `devicetree-dir` key. Example: `devicetree-overlay /6a9857a393724b7a981ebb5b8495b9ea/overlays/overlay_A.dtbo /6a9857a393724b7a981ebb5b8495b9ea/overlays/overlay_B.dtbo` @@ -385,8 +393,9 @@ i.e. it is a good idea that both images shipped as UEFI PE images and those which are not don't make unnecessary assumption on the underlying firmware, i.e. don't hard depend on legacy BIOS calls or UEFI boot services. -When Type #1 boot loader menu entry snippets refer to other files (for `linux`, -`initrd`, `efi`, `devicetree`, and `devicetree-overlay`), those files must be +When Type #1 boot loader menu entry snippets refer to other files or directories +(for `linux`, `initrd`, `efi`, `devicetree`, `devicetree-dir` and +`devicetree-overlay`), those files must be located on the same partition, and the paths must be absolute paths relative to the root of that file system. The naming of those files can be chosen by the installer. A recommended scheme is described in the next section. Paths should