From patchwork Fri Feb 13 21:17:33 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1857 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=1771017483; bh=hUaBVbzCjmomt3L9SEB5sVjg28nw9ZAdt5lsTngFXJc=; 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=jr3xFZE2P9dSPunmXsRwHvYd+FtfpzvLr9xkaKfY8oigI+fTCrtriOUEf6SeszsBg ACflVmonfL+v9CtcMip2ZSi0YNGBb832+sdgnIzw4J5CaHDZhY5wP8Dk+LwaJoXuer f65ZjJBrycnS/89XNDItSi31TC6OH+/RYx9j+bnvYPxxIGGsntpn8CejfHoRAYstMO edV5cP5ShOEF02Quwpi6c55OBUn0+cAGsiu7NzaKXCfaoXgOmCfPss7wPzYW8Sfpnk WcxmPP87tfg9DhrDi6n1W/rRMw+XDsvzB6SoOlCOuURi3YQkItTnuu36NWJOHnCjXX pi4YQvBQWVy/w== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 0D01269B3D for ; Fri, 13 Feb 2026 14:18:03 -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 bG1GL1KD2INn for ; Fri, 13 Feb 2026 14:18:02 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017482; bh=hUaBVbzCjmomt3L9SEB5sVjg28nw9ZAdt5lsTngFXJc=; 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=mS84SDFYw3Q6fSZ/Kcly+ShMWWHr0ATQYZFEhQuN37nJOQm9pCRjalvyfrr9FKVmY mw1yLAY/+YzYnpY3JgVcSA3gsXwfI1qdSOetprVT45+q7D8PSE8Jj+KjJ1UlAT5U67 xBkop9WFWnmCJcz+JHDTy3UF5r6baRlf25lLXuVhokeOATl+2cepzltLI/7WgO4Jr3 hXzQXE5OxqFUTH/e7mDlu6KfB48RMfNa/34IbHxTj2Jk1jUlTOpTlQ5oTUhcGdzWKH Jc8VjAM8NS54iNjaqLJEJE+nfdFXC4xOe+9IWaGKRE5PU1uv2sRyos4n5rbgsKzLTn gd/VR5iA1agbg== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id E75B469B46 for ; Fri, 13 Feb 2026 14:18:02 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017481; bh=QkasTfg8QCcIne+U8LeJhTAoN4zIr0xLbVCLbQhPuhU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lAwVMSH1Yf/LGs/eO6m84gUhNdeTL+WEPuF3TV2GXjPe3AyCvBspNyD08M05bXL68 ybHs9Wa1GVpdqYunPw8h79d2/lk+lUxVajpQnQpjr3nZ6pSzN3ihLAGq4Vo3VxqQ0K KBCauYrPgjMoDJo3Tjj381/Tx0lD7WVQ4V3njqQz8sc5/39zE1V/atBIBbEYkM/S3o ky1lFDW8Jmlkufk2J3Zl1JTO1Z8F0NMorCUimfTCzNbmgVPTDKtgI+cXUnaIVhu6PB M4H/AvkTFidSx8PJEeS2DSN75a/sPqVi3BjDQ6wR/404N/dnOtxEPuXlP38A6FDe5U /3yVlR2ug3kBA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 3120B69A94; Fri, 13 Feb 2026 14:18:01 -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 0QiL_ljsN1Hv; Fri, 13 Feb 2026 14:18:01 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017477; bh=JERlIqwR8pP6oYXUqGByKY5elPc12QndWNzKx8tdS6Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=De7USQ0ZaerFlLlsPeRKykKJ4cEuIVEj6/rVp6tuJ2fRYxW6XjpSrCqlS9hWKPvH5 iG3T8a4Yxf5Ponvv9Q8J9BtRHP2s3UIEEuOONQbKKjkuQivhdzffe41GkLnHRpFVe0 /JpXwL36CPPIMqSga+8EHyWu1hZ9BTnlKF600q0bJX7tga40/GVaITvs4IVjLpraH4 soOtt487cQLkwjisL+io7meVWLOqdstvIogddSxvVxbGNFp7VMBm+2/q14g0fwh4MB NsjCnUqKVe2Z0auxDk7xhYtzuDnM5fU8D8c1IHqKQgqJH4uFlxpHJeUd8M/wEtYCrM sKZHl3Z/B+HRQ== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id AEA4069B31; Fri, 13 Feb 2026 14:17:56 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Fri, 13 Feb 2026 14:17:33 -0700 Message-ID: <20260213211739.381127-3-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260213211739.381127-1-sjg@u-boot.org> References: <20260213211739.381127-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: CHT2UXR5GBB3BHJAVNWB4ZGVXLTOX4IO X-Message-ID-Hash: CHT2UXR5GBB3BHJAVNWB4ZGVXLTOX4IO 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 2/5] doc: bls: Add developer documentation for BLS bootmeth 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 The bootstd developer docs cover each bootmethod but are missing one for BLS. Add a new page describing the implementation: discovery via bls_read_bootflow(), zero-copy enum-based parsing in bls_parse_entry(), and the PXE-label conversion used for booting. Also list BLS in the available-bootmeth-drivers table in the overview. Co-developed-by: Claude Opus 4.6 Signed-off-by: Simon Glass --- doc/develop/bootstd/bls.rst | 34 ++++++++++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + 3 files changed, 36 insertions(+) create mode 100644 doc/develop/bootstd/bls.rst diff --git a/doc/develop/bootstd/bls.rst b/doc/develop/bootstd/bls.rst new file mode 100644 index 00000000000..7dc4a9de4ff --- /dev/null +++ b/doc/develop/bootstd/bls.rst @@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +BLS Bootmeth +============ + +The `Boot Loader Specification`_ (BLS) bootmeth allows U-Boot to boot +operating systems configured with BLS Type #1 entries. This format is used by +Fedora, RHEL and other distributions. + +.. _Boot Loader Specification: https://uapi-group.org/specifications/specs/boot_loader_specification/ + +The entry file ``loader/entry.conf`` is searched for under each boot prefix +(``{"/", "/boot"}`` by default). These prefixes can be selected with the +`filename-prefixes` property in the bootstd device. + +When invoked on a bootdev, the ``bls_read_bootflow()`` function searches for the +entry file, reads it and passes it to ``bls_parse_entry()`` which processes +the key-value pairs into a ``struct bls_entry``. The parser uses an enum-based +token lookup to map field names, with most values pointing directly into the +bootflow buffer (zero-copy). Only ``options`` is allocated separately since +multiple occurrences are concatenated. Unknown fields are silently ignored for +forward compatibility. Images (kernel, initrd, devicetree) are registered in the +bootflow with ``bootflow_img_add()`` during discovery but not loaded until boot. + +At boot time, ``bls_to_pxe_label()`` converts the bootflow into a PXE label +structure, mapping BLS fields to their PXE equivalents (``title`` to menu, +``options`` to append, etc.). The existing ``pxe_load_files()`` and +``pxe_boot()`` infrastructure then handles file loading and execution, including +FIT support. + +The compatible string "u-boot,boot-loader-specification" is used for the driver. +It is present if `CONFIG_BOOTMETH_BLS` is enabled. + +See :doc:`/usage/bls` for usage details and field reference. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 35b7065aaad..cee792ffc98 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -9,6 +9,7 @@ Standard Boot overview extlinux pxelinux + bls pxe_api qfw android diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 208c371bb0e..34ee42c79e0 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -438,6 +438,7 @@ Available bootmeth drivers Bootmeth drivers are provided for booting from various media: - :doc:`Android ` bootflow (boot image v4) + - :doc:`BLS ` Boot Loader Specification Type #1 entries - :doc:`ChromiumOS ` ChromiumOS boot from a disk - EFI boot using bootefi from disk - EFI boot using boot manager