From patchwork Fri Feb 13 21:17:32 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1856 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=1771017477; bh=XaQGwxdK2MU1nPNI3kQ7K4Cm8GTioOuWCtyUSR8tFQg=; 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=mtQu3VYVwfLX8kmiWI2UBYw3WurWSoP+OsPivMrKcu3TgeOyHGjB7fy3xEsQzMw99 OO6HXzDusv/J2UgAojOA9RCg7dnYsK8mQScEUGGsbh9KciQPfKXw3CmLRVMJKaB8Jx M8EFfzXomTxw75b52ha1NJ3uGXfX3oQmVsyK/SZH/il0BEgmrIk4DHhZlj5in5TykV fYVg1GUzzjrPq04+j0vheWVueeVuT591+mwj+CVteAjY6iNgBN5W65CZHmi04Q/z7/ Fg/vgy0+Fq3A3gX1d4qYz+jN6ZAP6pIBfDk0/tlQgDOB7Yws+4r0kBsj8YqyHRGwgO 03FOOdSeil4dA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id E0A8669B42 for ; Fri, 13 Feb 2026 14:17:57 -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 vkKscUbj1vQ6 for ; Fri, 13 Feb 2026 14:17:57 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017477; bh=XaQGwxdK2MU1nPNI3kQ7K4Cm8GTioOuWCtyUSR8tFQg=; 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=mtQu3VYVwfLX8kmiWI2UBYw3WurWSoP+OsPivMrKcu3TgeOyHGjB7fy3xEsQzMw99 OO6HXzDusv/J2UgAojOA9RCg7dnYsK8mQScEUGGsbh9KciQPfKXw3CmLRVMJKaB8Jx M8EFfzXomTxw75b52ha1NJ3uGXfX3oQmVsyK/SZH/il0BEgmrIk4DHhZlj5in5TykV fYVg1GUzzjrPq04+j0vheWVueeVuT591+mwj+CVteAjY6iNgBN5W65CZHmi04Q/z7/ Fg/vgy0+Fq3A3gX1d4qYz+jN6ZAP6pIBfDk0/tlQgDOB7Yws+4r0kBsj8YqyHRGwgO 03FOOdSeil4dA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id CFF4269B3E for ; Fri, 13 Feb 2026 14:17:57 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017476; bh=qZc7ePSwSZ3gjqaEGfvOf7D2umT1AYovEBuOT0dxOow=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=eRJQ3z+YmaN2B1+FFYPCr3JMPWdSWHZ4Z+aMQZ9NmQ4xwWEBGM7KfsOEb0uNSf8oY M2/N7pBPppkXBxMoJobyF/ekeaUOYVxfuZuC4ape6VKhTMOsjV4B0OQAv05JwN5QSn 40fx6bhDViRcE1HBUsGpGfZHub4wyXrWQivipfIUGL+jgzt4HRmTlsLSfDGuuEufxS AW0zRnW5mnhNK3qrdiaeymdMeF5faz21B6AiqAZVwlswT1KsAtU7nD7H6So4Z74G8i o/1NGBe3Za1jdJg+BEIMpE2wVWhtl7RyzkdKm+uKx+xdMZbS93C1BvhJu7TWbWzjoN YhcYHErFUrw/w== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 754CF69B3D; Fri, 13 Feb 2026 14:17:56 -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 Td3X3TVD47tv; Fri, 13 Feb 2026 14:17:56 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017472; bh=4pRb6M449iL7KztWO1ZtFOXYMiiat7HDYSiC2e7C8Yw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sI5ZNpoeXfiJsii1MZMI+JFE/mfGoF20FYqElfgnBXMUKVr25Uv7UGv/bVowiyDbs wKkq1QCzf+BsTSDFdO9rbRZUjYlloLstahHpE7fb9oB8UK1M4JN/l73jGQyuCQDrAU Nt6LOOw0LBhjFaRdySM6zYwgJzmHMsiS0QuOjXpXoFhmwrUx3woYU74D7r5V30Mk2m duWbMJqI5axK6I+hVqIC1ajGq6fg1+q8R3B5tGHajHyZH/Hndlc4Uvqp7WxuOjHfBv a+3fjeXv30fOcZQ5HSyE6HOwvQtfk6r3/K1NI7AmpFWXeWvC+e7rdad/ynH171NBPd +OCU0yEvP8Sjw== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 1ECC569B31; Fri, 13 Feb 2026 14:17:52 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Fri, 13 Feb 2026 14:17:32 -0700 Message-ID: <20260213211739.381127-2-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: 27JPO7O3IUHBQOZGH4EGRLQYNOTNMGNP X-Message-ID-Hash: 27JPO7O3IUHBQOZGH4EGRLQYNOTNMGNP 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 1/5] doc: bls: Fix Sphinx cross-references and improve text 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 Use proper references in the "See Also" section and tighten some of the prose. Co-developed-by: Claude Opus 4.6 Signed-off-by: Simon Glass --- doc/usage/bls.rst | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/doc/usage/bls.rst b/doc/usage/bls.rst index f96652bd242..128092ae25b 100644 --- a/doc/usage/bls.rst +++ b/doc/usage/bls.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0+ -Boot Loader Specification (BLS) Type #1 Support -================================================ +Boot Loader Specification (BLS) +=============================== U-Boot supports Boot Loader Specification (BLS) Type #1 boot entries as defined in the `Boot Loader Specification`_. @@ -26,7 +26,7 @@ Enable BLS support with:: CONFIG_BOOTMETH_BLS=y -This automatically selects ``CONFIG_PXE_UTILS`` for boot execution. +This automatically selects ``CONFIG_PXE_UTILS`` for booting. BLS Entry Format ---------------- @@ -75,6 +75,11 @@ are not currently supported by U-Boot: * ``uki-url`` - Remote UKI reference * ``profile`` - Multi-profile UKI selector +Fields that support multiple occurrences: + +* ``options`` - All values are concatenated with spaces +* ``initrd`` - All paths are loaded consecutively in memory + .. _Unified Kernel Images: https://uapi-group.org/specifications/specs/unified_kernel_image/ U-Boot Extensions @@ -109,26 +114,22 @@ FITs can be specified in two ways: fit /boot/image.fit The PXE boot infrastructure handles FIT parsing automatically in both cases. - -Multiple Values ---------------- - -Fields that support multiple occurrences: - -* ``options`` - All values are concatenated with spaces -* ``initrd`` - All paths are loaded consecutively in memory +The second option is preferred since the standard 'best match' algorithm +(enabled by ``CONFIG_FIT_BEST_MATCH=y``) should normally used to select the +correct configuration. Usage ----- -BLS boot entries are discovered automatically during standard boot:: +BLS boot entries are discovered automatically by standard boot:: => bootflow scan => bootflow list => bootflow select 0 => bootflow boot -The BLS entry at ``loader/entry.conf`` is discovered as a bootflow. +The BLS entry at ``loader/entry.conf`` on any available media is recognised as +a bootflow. Implementation Notes -------------------- @@ -154,5 +155,7 @@ Current Limitations See Also -------- -* doc/develop/bootstd.rst - Standard boot framework -* doc/usage/cmd/bootflow.rst - Bootflow command reference +* :doc:`/develop/bootstd/index` +* :doc:`/usage/cmd/bootflow` +* `Boot Loader Specification `_ +* `Unified Kernel Image `_ 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 From patchwork Fri Feb 13 21:17:34 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1858 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=1771017488; bh=Pu/aPhgkgy0oix1VfZKKxPZ29vihZZJwA1rM9LHuPKE=; 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=tne3aLuBwgj26aQqsGJUkUi3nCSWW/hCfTpqlimCp6wKT+amWv3c6G6G1vuklsp/5 4AlSXV7NgZNvDO2ZmZBvwlNUwF33svIGvoMhSZ+DpfJYUFCnHEcyXqm6lcfiNzcHJz OYa6/E52/e9KfOREuIFw9VoIwy8RBdQlOiTPORw1i+J8KfcH6Id8eeJsURnlpmtHol l/9zaal4tnfjiXp/6SKkqZB1yXkAajhTEWtP73ax4qumRc0e4H3R2EUQx+ZqBcwdYK tSljrxh2QAIdKFfxqDKe0KhaZywLQthV9AlMfqLQ8ATitwGsxUgXgGS0waf1+YSfM8 rGlrs3xpD//9g== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 9054469B45 for ; Fri, 13 Feb 2026 14:18:08 -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 5elpWGdixQ1O for ; Fri, 13 Feb 2026 14:18:08 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017488; bh=Pu/aPhgkgy0oix1VfZKKxPZ29vihZZJwA1rM9LHuPKE=; 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=tne3aLuBwgj26aQqsGJUkUi3nCSWW/hCfTpqlimCp6wKT+amWv3c6G6G1vuklsp/5 4AlSXV7NgZNvDO2ZmZBvwlNUwF33svIGvoMhSZ+DpfJYUFCnHEcyXqm6lcfiNzcHJz OYa6/E52/e9KfOREuIFw9VoIwy8RBdQlOiTPORw1i+J8KfcH6Id8eeJsURnlpmtHol l/9zaal4tnfjiXp/6SKkqZB1yXkAajhTEWtP73ax4qumRc0e4H3R2EUQx+ZqBcwdYK tSljrxh2QAIdKFfxqDKe0KhaZywLQthV9AlMfqLQ8ATitwGsxUgXgGS0waf1+YSfM8 rGlrs3xpD//9g== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 8101769B31 for ; Fri, 13 Feb 2026 14:18:08 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017485; bh=wUzv6PE86pnr61FIzCm2shyzuFTFZR/YHGg+WLvW0uU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=WUvHNP+PSk4G/81Uut2VO+HfG1ojoB0cgE4WwJWa4EdDGXc0XfoYZ5xtr8QZ46pSq mrklhmi8kAI1ndefQ2oda4C9eDdLGVcyjQBeSAB5O5ucJkUhzZTWRQjpyGoMaKvXCS h0ullsbvvYRC12lsw09Zl8Z52oWixxZDNNIBV3VEprMoQCXcR7rvlyYFOZIu9IhyCJ En4xAYa3OzZsZP3gibGGOZK4iEwFdpM9tqy0VlxNUEjFPAbXOI8zh2KY471RbbBGuw RPlUndvlivRH/qbEVxwFpW4Lpz2tlc7Olw/NjhqW1RdbltOobyscamGPXjLqLH5bTR S4i72NlObDQOw== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id BF90969B3D; Fri, 13 Feb 2026 14:18:05 -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 oxU2ff1lLInT; Fri, 13 Feb 2026 14:18:05 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017481; bh=g/yH9W1dnZGaHqN50FRbjE5TPbdhdRe83hZrrX85RYI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=E7oCz9//6Ly8NtewTC0N0N5IrpiEI0WXpiL9HhkseB9NkveDAAn2Fz60IpCsdV9M4 r21y6WzXGGep1XrIKkPULF9NWHbWO51+uLnqZrGQYn4cSSTNKmLyCkYWtS8lcbE0q/ kIZlIn9ZxTr2oUdu3vpklT6cfEKu+MIlRth0vNS89AJ/2pWFiW6bToDkzJAfYMjjC9 Fu8/Evg1BqgORyxX83+rA8nJMiu0PxMQOBVZJtRrB5+SDHEEp1PGFV0CscvyihPrBl j185RTeuJWePys30egcV69zwyoGSSd9YtAeTotouDACvPYJ3uP5Hx6DSmEUbfgi+h1 wxK39VmZaHhAA== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 71B2669B31; Fri, 13 Feb 2026 14:18:01 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Fri, 13 Feb 2026 14:17:34 -0700 Message-ID: <20260213211739.381127-4-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: MVFUS46XV37CU3P54LW6KQVW5EIQYV5F X-Message-ID-Hash: MVFUS46XV37CU3P54LW6KQVW5EIQYV5F 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 3/5] doc: bootstd: Add developer docs for the EFI 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 are missing a page for the EFI bootmeth. Add one describing the discovery and boot phases for both block and network devices, and link it from the toctree and overview. Co-developed-by: Claude Opus 4.6 Signed-off-by: Simon Glass --- doc/develop/bootstd/efi.rst | 25 +++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- doc/develop/uefi/uefi.rst | 3 +++ 4 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 doc/develop/bootstd/efi.rst diff --git a/doc/develop/bootstd/efi.rst b/doc/develop/bootstd/efi.rst new file mode 100644 index 00000000000..abd1ab158aa --- /dev/null +++ b/doc/develop/bootstd/efi.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +EFI Bootmeth +============= + +The EFI bootmeth allows U-Boot to boot an operating system by loading and +running an EFI application from a disk or network device. This follows the +approach used by many Linux distributions to provide a standard boot path. + +When invoked on a block device, ``distro_efi_try_bootflow_files()`` searches for +the architecture-specific EFI binary in ``/EFI/BOOT/`` (e.g. +``bootaa64.efi``). If found, the bootflow is marked as ready. The function also +tries to locate a matching device tree using ``efi_get_distro_fdt_name()``. + +When invoked on a network device, ``distro_efi_read_bootflow_net()`` performs a +DHCP request with PXE vendor-class and architecture identifiers, then retrieves +the EFI binary via TFTP. A device tree is also fetched if available. + +At boot time, ``distro_efi_boot()`` loads the EFI binary into memory (for block +devices) and calls ``efi_bootflow_run()`` to execute it via the EFI loader. + +The compatible string "u-boot,distro-efi" is used for the driver. It is present +if `CONFIG_BOOTMETH_EFI` is enabled. + +See :doc:`/develop/uefi/uefi` for general UEFI implementation details. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index cee792ffc98..bbdcb154724 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -10,6 +10,7 @@ Standard Boot extlinux pxelinux bls + efi pxe_api qfw android diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 34ee42c79e0..60ba247e005 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -440,7 +440,7 @@ 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 + - :doc:`EFI ` boot using bootefi from disk or network - EFI boot using boot manager - :doc:`extlinux / syslinux ` boot from a storage device - :doc:`extlinux / syslinux ` boot from a network (PXE) diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index ef53c4c35dd..a5131fa2d49 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -64,6 +64,9 @@ Therefore the bootefi command uses the device path of the block device partition or the network adapter and the file name of the most recently loaded PE-COFF file when setting up the loaded image protocol. +See :doc:`/develop/bootstd/efi` for how standard boot discovers and launches +EFI binaries automatically. + Launching a UEFI binary from a FIT image ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From patchwork Fri Feb 13 21:17:35 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1859 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=1771017493; bh=QR/PMeprVl4xBefJNmmsNS5eww4BY3TnMUOdgnP8Me4=; 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=vRNDOIshbSvnRRH19X0dvNI1UWe0sihTlTBIgOzseZITDwa6AKTPlo1ljXg3sneBW 7YSwoJRb4BbLV5L/ZuWLpc7QYTKndKt2gik/+e670gPa4V5uDXMhIESJHoTHKBEQKj JuHtRCb0a5sYr2NzWZ6GjjQPj9UXO8rwAwjDz9iorngpjmkA1OAu5vGXq1SN2B3DN5 HBRTLfLVpuEaZDQb9T9nXXsxlZFcYKN0CAGjGIdr48y1AtzxsA/rhxPIlhDJD8Ws/h OgXBpcRsTOLaNW3OU9e7yyyTYKhOvnVF7cH8eA9KNPhdhnaRXJXeyoz4bZsa5o7G9X BCkePUigqs7tQ== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 05EB469B47 for ; Fri, 13 Feb 2026 14:18: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 pzbW9UkDW0aE for ; Fri, 13 Feb 2026 14:18:12 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017492; bh=QR/PMeprVl4xBefJNmmsNS5eww4BY3TnMUOdgnP8Me4=; 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=G+4e9fUFO8tNRhyiAj5AO5D/5+ucx4uT2i69u+r3wvQ3VAWtmgiubxmtc40qgOQDf RSCx22vXS1jP6U/OkP81yC0wfhpcjmOXGnCVOHjeNvb9C4tVfNqiHZfO304axyDByg z8LfLiFoq895l5+/aW3pQnOjo1T0PnQY+mlDLeKP8ZWjl1mitOA54m9jc8lI/8KZtJ LwLXEeuXyG61wA3lr/44fwu15oghNL4Ha6XZDBg5icakVK6PD6cuUUiEGImVoM+tiN b+XlcSn/iaq2NIWyS2cG7s0XPy7ImPa67E3HUfT6Kifst5IhxGKA+l0fz5QJ7eGQaO 6N587zZSojUtQ== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id EA54569B3D for ; Fri, 13 Feb 2026 14:18:12 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017490; bh=0vwkdPKX+YqWBDXsjPK7arQnQTxj5MiQ2IA2p+/s2dU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MIWARd2dACCsYL3WN0ORwE8gmIxX5Pdj/xvL0TEPsWjEQMn60C2mTrkZWbrYfZ7f1 2ChExQb16zboSttqZgwOYcSr8Ss9HBfxhyIwu1TdgIdq03PnHZh5/7lcMrtquQnkvu yQlGJj1O0fIqDMeze9wThuxP1/xu9meY2on+jR4DpLYd/L1QipmoFwz8M3XSju4FJi l0SZD7jObd5T61gF2PhxqjHSrXYyId6tQsErAfWi5qe5QEcO86XipMuRxt36QZgsIf biz/h+11sgXD7WbAel9SsDAAruMWjYBf6StbPK6ofkU9gn+KBXJ+mU6ElukILqXpt+ yYzQGzGkO7tEA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id ED71269B3D; Fri, 13 Feb 2026 14:18:10 -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 k7W8ZH4xUeli; Fri, 13 Feb 2026 14:18:10 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017486; bh=e78pkU8mvqDIRf/YqHbM8GZBf7U4Q6jIO7wXYOAaTFA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=p3+FnJ9QWG2EI/SbNiS9nnbWeO5c/ZRLozw0Omi6pYxQpw1X3R9YicwvFCm9syjp2 kIZPz1fE88zKkxftbY/yLjuxqNRlQrhUZKVwRbrwM8g2OlZss9SvcigGookYiabQiQ T4I7gHXO+C0V4Gn3x+jDwUYSLYaqChPkhz6Lyt391lgcKQi9kRMnSEzqfDt+3KHs0q 2kC+ri8i4EBhIoYdpiNxtLs8YB1PD8VpJQeai50fVGMtzKj+BP2lWuR2ZHwn8COE5m hamQJDodWoMb4qyr5wM7fYWkRShpklgS8Ak/5jAEbSYSHzYI7P+pkDKVvJl1ApZvfG hqwg3bzVCfC2w== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 0E3A369A62; Fri, 13 Feb 2026 14:18:06 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Fri, 13 Feb 2026 14:17:35 -0700 Message-ID: <20260213211739.381127-5-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: TEXPW5RGLFGJZIZNNL4PZAFU6EPQ3DQ6 X-Message-ID-Hash: TEXPW5RGLFGJZIZNNL4PZAFU6EPQ3DQ6 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 4/5] doc: bootstd: Add docs for EFI boot-manager 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 EFI boot-manager bootmeth is listed in the overview but has no dedicated page. Add one describing its global nature, BootOrder-based discovery and delegation to efi_bootmgr_run() for booting. Co-developed-by: Claude Opus 4.6 Signed-off-by: Simon Glass --- doc/develop/bootstd/efi_mgr.rst | 29 +++++++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- doc/develop/uefi/uefi.rst | 3 +++ 4 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 doc/develop/bootstd/efi_mgr.rst diff --git a/doc/develop/bootstd/efi_mgr.rst b/doc/develop/bootstd/efi_mgr.rst new file mode 100644 index 00000000000..c45840906d6 --- /dev/null +++ b/doc/develop/bootstd/efi_mgr.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +EFI Boot Manager Bootmeth +========================= + +The EFI boot-manager bootmeth delegates boot-device selection to the UEFI boot +manager. Rather than scanning filesystems for a specific binary, it checks +whether a ``BootOrder`` EFI variable exists and, if so, marks the bootflow as +ready. + +This is a global bootmeth: it is not tied to a particular bootdev but is +invoked once during each scan. The ``BOOTMETHF_GLOBAL`` flag is set at bind +time, and the global priority is ``BOOTDEVP_6_NET_BASE`` so that it runs just +before very slow devices, giving filesystem-based methods a chance to complete +first. + +During discovery, ``efi_mgr_read_bootflow()`` initialises the EFI object list +and looks up the ``BootOrder`` variable. If the variable is present the +bootflow is marked ready; otherwise the method is skipped. + +At boot time, ``efi_mgr_boot()`` calls ``efi_bootmgr_run()`` which walks the +``BootOrder`` list and launches the first viable EFI application. No file +loading is done by the bootmeth itself. + +The compatible string "u-boot,efi-bootmgr" is used for the driver. It is +present if `CONFIG_BOOTMETH_EFI_BOOTMGR` is enabled. + +See :doc:`/develop/uefi/uefi` for general UEFI implementation details and +:doc:`/usage/cmd/eficonfig` for configuring boot entries. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index bbdcb154724..9f958da62de 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -11,6 +11,7 @@ Standard Boot pxelinux bls efi + efi_mgr pxe_api qfw android diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 60ba247e005..0bcf988a458 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -441,7 +441,7 @@ Bootmeth drivers are provided for booting from various media: - :doc:`BLS ` Boot Loader Specification Type #1 entries - :doc:`ChromiumOS ` ChromiumOS boot from a disk - :doc:`EFI ` boot using bootefi from disk or network - - EFI boot using boot manager + - :doc:`EFI boot manager ` using UEFI BootOrder variables - :doc:`extlinux / syslinux ` boot from a storage device - :doc:`extlinux / syslinux ` boot from a network (PXE) - :doc:`sandbox ` used only for testing diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index a5131fa2d49..118b6411d05 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -666,6 +666,9 @@ UEFI variables. Booting according to these variables is possible via:: bootefi bootmgr [fdt address] +See :doc:`/develop/bootstd/efi_mgr` for how standard boot integrates the +EFI boot manager. + As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot command 'efidebug' can be used to set the variables. From patchwork Fri Feb 13 21:17:36 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1860 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=1771017497; bh=DeVxIm2nDnoCyIll07sUXPFl6oGnpkDrwxjuowtmY40=; 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=vowMN0apgcsungcMC03GJARYjI874o0wsuXFHRRKwtmLWhEIoUG98n2oZxeBV4u4O /y+CilCyBcqNvMlwfaPoMGLysEVxqOuT4UlVQxB9CM0UFBwrAzY3xNzM1Z5a3LpK4v vidpT286o8JMoY/wAX6qBOHz4VbuxpTX6Mr+s6LaDET+ZzgbdntSB1bOaiX4e2v8Hq 4VSaj6AaQCQEw7bBw87PifGSeQx/kW2zSiNwYhOVaDsscULdsatvpXd3GEoS8hM2i6 Q1jH4waqnEOdTenh+AlrdRLCjgzVryYwsCPz/BitoXbpTAwcGNjoi7tp3dcOH4k3JE nScZGrBxUemJA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id D27C269A62 for ; Fri, 13 Feb 2026 14:18:17 -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 hZrBHKui-9RX for ; Fri, 13 Feb 2026 14:18:17 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017497; bh=DeVxIm2nDnoCyIll07sUXPFl6oGnpkDrwxjuowtmY40=; 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=vowMN0apgcsungcMC03GJARYjI874o0wsuXFHRRKwtmLWhEIoUG98n2oZxeBV4u4O /y+CilCyBcqNvMlwfaPoMGLysEVxqOuT4UlVQxB9CM0UFBwrAzY3xNzM1Z5a3LpK4v vidpT286o8JMoY/wAX6qBOHz4VbuxpTX6Mr+s6LaDET+ZzgbdntSB1bOaiX4e2v8Hq 4VSaj6AaQCQEw7bBw87PifGSeQx/kW2zSiNwYhOVaDsscULdsatvpXd3GEoS8hM2i6 Q1jH4waqnEOdTenh+AlrdRLCjgzVryYwsCPz/BitoXbpTAwcGNjoi7tp3dcOH4k3JE nScZGrBxUemJA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id BBD3069B31 for ; Fri, 13 Feb 2026 14:18:17 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017495; bh=y0IlteQaC+h/vFCMPPduZWFuZ45JMXZ8ZYxTBojtoGE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=aUHbT1qUZhiN+OC5G0TJku62JshkMkW+zeDdyEfUDT4jl1DoNA8gVpU8Gji3ulMLh hHz56rQEyXQpoje/XLAEaD6XhWHv9geMucsO0sVy56JSPIAGINPPATZQ4hkYCg7ydf E9vlgEeIxYRQ8vQGtsmYSxZTc2TrW5erG72vQhVknnIEx/gaOfdfndS5oqSgmUFuG1 qj7BYBj7SDrUhH35fUegM09JbawZAjCZv2NaLTxkDJqkKW/eEZQc24w/X7nf9yrHKg 97OBrvnxFthL7ER7thkyrEr684xpOkVYt55pEeLkoa783VpGBX79eclw7VvkFka4NA 2kweXkMmaZ+7A== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 5D2E069B3D; Fri, 13 Feb 2026 14:18:15 -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 13_2vhoXuvNa; Fri, 13 Feb 2026 14:18:15 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1771017490; bh=I6p8JhcKmOIZrAnwG9A0KfLn+QDqFA4dP+zS5kNJ1R4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=m9lNQMtZQaKj8FTpSX9mzetSB3kPr/5D8wIuVMMtGSKhpn3MUtxmx4HtGRsl6OKa6 QoKe0qCalNDSLHUyCdKBBZCkzYW9BZfkdx5bKNu6RlxOl2x38Pzy+4x2HmiZT6Roz5 oXs4W6jljTKyQKnbjf5SXnRME90JF0+qpeirf9WRWJHxkmLOLXXtzepgj0gnAVV3uR hFgMbDIf7N24dzH77lKjU5OdBcMWZ5/DR1jRsaHIoymmrOW7mmLEZdfXu2ZQaeNC9C MLGUoVsvmszuZUXL2/RJpfGroteUaSP4RqpVqcbxZliU4iSMdwYLt2F0+gSi1QLI4A 3rZwZke6AJTQQ== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 9EFA369B31; Fri, 13 Feb 2026 14:18:10 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Fri, 13 Feb 2026 14:17:36 -0700 Message-ID: <20260213211739.381127-6-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: 7J4AONJ5AAPKQQIGQN6FR7Z3EVVG4TPN X-Message-ID-Hash: 7J4AONJ5AAPKQQIGQN6FR7Z3EVVG4TPN 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 5/5] doc: bootstd: Add developer documentation for FEL 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 FEL bootmeth has no documentation at all. Add a developer page describing how it detects FEL-booted sunxi boards via environment variables and executes the pre-loaded script. Also add it to the toctree and overview list. Co-developed-by: Claude Opus 4.6 Signed-off-by: Simon Glass --- doc/board/allwinner/sunxi.rst | 3 +++ doc/develop/bootstd/fel.rst | 24 ++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + 4 files changed, 29 insertions(+) create mode 100644 doc/develop/bootstd/fel.rst diff --git a/doc/board/allwinner/sunxi.rst b/doc/board/allwinner/sunxi.rst index d0c89b956b1..58e5848519e 100644 --- a/doc/board/allwinner/sunxi.rst +++ b/doc/board/allwinner/sunxi.rst @@ -306,6 +306,9 @@ bootstrap U-Boot by just providing our venerable u-boot-sunxi-with-spl.bin:: Additional binaries like a kernel, an initial ramdisk or a boot script, can also be uploaded via FEL, check the Wiki's `FEL page`_ for more details. +See :doc:`/develop/bootstd/fel` for details on how standard boot handles +FEL-booted boards. + .. _`Arm Trusted Firmware-A`: https://www.trustedfirmware.org/projects/tf-a/ .. _`docs/plat/allwinner.rst`: https://trustedfirmware-a.readthedocs.io/en/latest/plat/allwinner.html .. _`crust`: https://github.com/crust-firmware/crust diff --git a/doc/develop/bootstd/fel.rst b/doc/develop/bootstd/fel.rst new file mode 100644 index 00000000000..10001baeee5 --- /dev/null +++ b/doc/develop/bootstd/fel.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +FEL Bootmeth +============= + +The FEL bootmeth supports booting Allwinner (sunxi) boards that have been +started via the USB FEL protocol. The SPL places a boot script in memory and +records its address before jumping to U-Boot proper. + +This is a global bootmeth: it is not tied to a particular bootdev but is +invoked once during each scan. + +During discovery, ``fel_read_bootflow()`` checks for the ``fel_booted`` and +``fel_scriptaddr`` environment variables. These are set by SPL when the board +is FEL-booted. If either is missing the method is skipped. + +At boot time, ``fel_boot()`` reads the script address from ``fel_scriptaddr`` +and executes it with ``cmd_source_script()``. No files are loaded from a +filesystem; the script was already placed in memory by the FEL loader. + +The compatible string "u-boot,fel-bootmeth" is used for the driver. It is +present if `CONFIG_BOOTMETH_FEL` is enabled. + +See :doc:`/board/allwinner/sunxi` for general Allwinner board information. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 9f958da62de..5cbc020343f 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -12,6 +12,7 @@ Standard Boot bls efi efi_mgr + fel pxe_api qfw android diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 0bcf988a458..f219eb3adf7 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -442,6 +442,7 @@ Bootmeth drivers are provided for booting from various media: - :doc:`ChromiumOS ` ChromiumOS boot from a disk - :doc:`EFI ` boot using bootefi from disk or network - :doc:`EFI boot manager ` using UEFI BootOrder variables + - :doc:`FEL ` boot over USB on Allwinner (sunxi) boards - :doc:`extlinux / syslinux ` boot from a storage device - :doc:`extlinux / syslinux ` boot from a network (PXE) - :doc:`sandbox ` used only for testing