From patchwork Fri Feb 13 20:24:13 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1855 Return-Path: X-Original-To: u-boot-concept@u-boot.org Delivered-To: u-boot-concept@u-boot.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771014313; bh=zgHRKEn0pIPKsfjz59h1YsyrH0pBqMfXYT3rcj8o60Q=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=gtaDsM8kozzJxyaoGSe5mue69FoBPYPy1f4RQ+x50FxkUTEtD8HV0tAAXd3zIXbXj y5Q4QIaKmQtnTtZA6pdijYNJekLwBPw/OzINQnzlSMqq9JqCAaIq86pyKa3w3YMket LWFtwMoWpP2M3nBLb8GFSlXFlsHaXXeMbNlw9VOggwGABA4nTQl6KZnNd8A8uGMxcJ cBhqWgGGDruRkXDpuIM9aRrbCJCSC5u4ND+fy8flOzzkTVYuAI/llad0LKBN9Ew9iv g7yQco+pCMCCNND55Mfzr2zCQaw20cqpykhRiPLhgPECtZoA7bY1w44NNqnWv/6OmS OVqZKi2QEwnPA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 2DF6169B34 for ; Fri, 13 Feb 2026 13:25:13 -0700 (MST) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10024) with ESMTP id mgVCFp8WGXbh for ; Fri, 13 Feb 2026 13:25:13 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771014313; bh=zgHRKEn0pIPKsfjz59h1YsyrH0pBqMfXYT3rcj8o60Q=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=gtaDsM8kozzJxyaoGSe5mue69FoBPYPy1f4RQ+x50FxkUTEtD8HV0tAAXd3zIXbXj y5Q4QIaKmQtnTtZA6pdijYNJekLwBPw/OzINQnzlSMqq9JqCAaIq86pyKa3w3YMket LWFtwMoWpP2M3nBLb8GFSlXFlsHaXXeMbNlw9VOggwGABA4nTQl6KZnNd8A8uGMxcJ cBhqWgGGDruRkXDpuIM9aRrbCJCSC5u4ND+fy8flOzzkTVYuAI/llad0LKBN9Ew9iv g7yQco+pCMCCNND55Mfzr2zCQaw20cqpykhRiPLhgPECtZoA7bY1w44NNqnWv/6OmS OVqZKi2QEwnPA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 1AB3969A66 for ; Fri, 13 Feb 2026 13:25:13 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771014311; bh=TQisWVumTcDV4sW8OT50jqvQjLE3uk2ll+0/4o/wgsc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JoKCs51sbzLt9FiFF6M8nXiyrFNMapIno6VZylHopZLF2wiKIRMnYUggW2DmnWV2i du11hTmvNF0g40Jkhe8tl9nip2d8hiUMt6vzMONr//+nztn2BOglPRi0RA/j+hiSxm 17qPROwe7C6P1IAqLLmlef/8UYygH/whRc7ab7h8mLZTIzdK6ZEghR0/nDrE6CRwnk MZtcIp2ady/6ShYCc8j5ATvvU13BSIoFn8KynsjkipNXCeFNbox8xyAnRwal2iyohv 2V/uUrybVPC2+OC0opSf2UkH5MiQ2aNzMfmfZcMJe5dLYnxb/dMVG3qn6App2PN2qG PiwU1TAvYNE4w== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id C4B1269B3A; Fri, 13 Feb 2026 13:25:11 -0700 (MST) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10026) with ESMTP id WqU5Q4labGYL; Fri, 13 Feb 2026 13:25:11 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771014306; bh=IAROsKHkBnc/hVqjk6f6RAuz3+UNn1OjsvfQXobPHPk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ne18DLoCejsWYMrG2kUXJdJLLo7Ytli38VnGvV8hI4AcUe0cTSiUGARy+R9UWVtyM FIjfkOkkQBRDtu2AORCazauyP+egjxVi0CyBK5N24cUCNIdUdwsYkFqJamSzZ5LCTO aKl/D4xhDcNrSfwnLYe/Xe+pMisosdptBUlE6RNgmI0+suTqcnPg6XEXj2ijany+n+ r3iDkpfB96OLx2VE8g84AlDZziAmoJHVobKuAFNN5Yu8d2dhrWVX4Ag7LwQ2KtPgku o50FTekI23To+/SY44EC7jn/J2Kg0dUu6tfAPuu8SDnyN1Jruu5jbWdholhtHC56kw 4kOHk7A5dnQOA== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 3497369B0E; Fri, 13 Feb 2026 13:25:06 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Fri, 13 Feb 2026 13:24:13 -0700 Message-ID: <20260213202417.223068-9-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260213202417.223068-1-sjg@u-boot.org> References: <20260213202417.223068-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: KSYSARHYB5XQORMK4J7DT3EOEUNJVDII X-Message-ID-Hash: KSYSARHYB5XQORMK4J7DT3EOEUNJVDII X-MailFrom: sjg@u-boot.org X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Simon Glass , "Claude Opus 4 . 6" X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 8/8] doc: bls: Update for FIT and multi-initrd support List-Id: Discussion and patches related to U-Boot Concept Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Simon Glass Update the BLS documentation to reflect recent changes: - Document the 'fit' field as a U-Boot extension for specifying FIT images explicitly - Update initrd to note that all paths are now loaded - Add references to the Unified Kernel Image spec for the unsupported EFI/UKI fields - Remove outdated "only first initrd" limitation Co-developed-by: Claude Opus 4.6 Signed-off-by: Simon Glass --- doc/usage/bls.rst | 54 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/doc/usage/bls.rst b/doc/usage/bls.rst index 5f5f0efb8a4..f96652bd242 100644 --- a/doc/usage/bls.rst +++ b/doc/usage/bls.rst @@ -46,8 +46,9 @@ Supported Fields **Required (at least one):** -* ``linux`` - Path to Linux kernel image (Type #1); supports FITs with +* ``linux`` - Path to Linux kernel image; supports FITs with ``path#config`` syntax +* ``fit`` - Path to FIT (U-Boot extension, not in the BLS spec) **Optional:** @@ -55,30 +56,59 @@ Supported Fields * ``version`` - OS version identifier (parsed but not used for sorting) * ``options`` - Kernel command line parameters (may appear multiple times; all occurrences are concatenated) -* ``initrd`` - Initial ramdisk path (may appear multiple times, but only first - is used due to PXE limitation) +* ``initrd`` - Initial ramdisk path (may appear multiple times; all initrds + are loaded) * ``devicetree`` - Device tree blob path * ``devicetree-overlay`` - Device tree overlays (parsed but not yet supported) * ``architecture`` - Target architecture (parsed but not used for filtering) * ``machine-id`` - OS identifier (parsed but not used for filtering) * ``sort-key`` - Primary sorting key (parsed but not used for sorting) -**Not supported (out of scope for Type #1):** +**Not supported:** -* ``efi`` - EFI program path (Type #2/UKI) +These fields relate to `Unified Kernel Images`_ (UKIs), which combine a UEFI +boot stub, kernel, initrd and other resources into a single UEFI PE file. They +are not currently supported by U-Boot: + +* ``efi`` - EFI program path * ``uki`` - Unified Kernel Image path * ``uki-url`` - Remote UKI reference * ``profile`` - Multi-profile UKI selector +.. _Unified Kernel Images: https://uapi-group.org/specifications/specs/unified_kernel_image/ + +U-Boot Extensions +----------------- + +The following fields are U-Boot extensions not defined in the BLS spec: + +* ``fit`` - Specifies a FIT path, as an alternative to ``linux``. When + ``fit`` is present it takes priority over ``linux``. This allows the entry to + explicitly indicate that the image is a FIT, rather than relying on the + ``path#config`` syntax in the ``linux`` field. + +Example:: + + title Ubuntu 24.04 + version 6.8.0 + fit /boot/ubuntu-6.8.0.fit + options root=/dev/sda3 ro quiet + initrd /boot/initrd-6.8.0.img + FIT Support ----------- -U-Boot's BLS implementation works seamlessly with FITs using the standard -``path#config`` syntax in the ``linux`` field:: +FITs can be specified in two ways: + +1. Using the ``linux`` field with ``path#config`` syntax:: linux /boot/image.fit#config-1 -The PXE boot infrastructure handles FIT parsing automatically. +2. Using the ``fit`` field (U-Boot extension):: + + fit /boot/image.fit + +The PXE boot infrastructure handles FIT parsing automatically in both cases. Multiple Values --------------- @@ -86,8 +116,7 @@ Multiple Values Fields that support multiple occurrences: * ``options`` - All values are concatenated with spaces -* ``initrd`` - Multiple paths can be specified, but only the first is used - (limitation of PXE boot infrastructure) +* ``initrd`` - All paths are loaded consecutively in memory Usage ----- @@ -115,11 +144,12 @@ Current Limitations ------------------- * Only single entry file, not multiple entries directory scanning -* Only first initrd used (PXE infrastructure limitation) * No devicetree-overlay support * No architecture/machine-id filtering * No version-based or sort-key sorting -* No UKI/Type #2 support +* No `Unified Kernel Image`_ (UKI) support + +.. _Unified Kernel Image: https://uapi-group.org/specifications/specs/unified_kernel_image/ See Also --------