From patchwork Tue Mar 24 22:19:06 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 2057 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=1774390797; bh=ZTv5qr2jKb2tmkhjMtcbqVOPYNe6RarQ/BvgHr1up1c=; 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=dGKm8gpkHkL1vmlJ6x5gajaaVuxh4+FC8tisPrcepBxID2P7d9mkHv7+F6NC4Y1Xe xQwKf+TatBVBbS1bYVkhO6m5/wAnlLVvJS5QTSZ59A0FjjDKCM4RM88wJVVV699sWO TblFY4dWV7rdbfJkJ41oiQU7p+JfkmpJIncFVfdvJWVYQOurrFqzIsxKt1UtXPbtVU FUFMpCX6V8E8ShioY6gy9vzLbsD949OO+aJCKWQTvXp6E41ksTglbGsAPr2NrOILJs IelNl7wyGm6WREodVCmAnSIb/3cdRBGq5AT5aCknJ3avzTyr71i+snx9UWXPnieoMz /dIc0TQGnIoDA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 610846A256 for ; Tue, 24 Mar 2026 16:19:57 -0600 (MDT) 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 3k3lxhIro5aq for ; Tue, 24 Mar 2026 16:19:57 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1774390795; bh=ZTv5qr2jKb2tmkhjMtcbqVOPYNe6RarQ/BvgHr1up1c=; 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=C9K08w62tptSFNIHsN15bse5GV8eRKnoRmmUFiITbiKe9UBDg4L9xWvrZC04db2qN z/wsIflAK5ZV+y1HHnbBRbJZMCIvqI+9U4yArGQx2iYVrPhcVV0KIQCEXYZ15CwUDF 6DbjFDtKQtidZZzTszKE5GOlj3Zyc11YzyobaL+mL9wJ+8BHh0AFzkP/rPWIwO81ca Ir+NfzPAT5QcBAXJ6Eusq6SHexvOO6TiGNNurJ/kEkbVEYBwDgP0VDmotusySRgOmg Jmng4Tw/oJWknh/9HIr+lBeO9aobq+0fnsHdA5SMt757S+PWqm3Tb46kQXPQ9QNVyS NrlHW9u68HRLQ== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id EEC206A23D for ; Tue, 24 Mar 2026 16:19:55 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1774390794; bh=ZPj097caCSsRbDaYtrh3ncuKZDuyciUoOC8QU16fO/E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=j9ctU4XTxG84417maV0tk80PE4HnFEAe4rtIRTAwCgVdTcV04M8cKvKTNia8B2Vh8 69JEe1sjbEu9xfkgibahl+UNyF6pUBjHlmoYlQDGU4ZVyhupVp3W87OPZ3wxZfL4gX qmtubxrWyDnvZoNPbnz862cwErm8x7Uj3mWk9yMfLoOyFLSv1gRrMfMktkv8nIG44n 9r2AM7VGttU/fXKiG50O5BGl8dJKgTTdIkARtuDkGKCq/Vs8wQIh4YqvAO+XxxRlmh jo51qTxjA569aknCWpFOS6vFG4x+Bnnd6RTPuxa10LQqEfvIb/aP9W07l5+Q2umg0L lSoGtLveCkpTA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 4C5DF6A24C; Tue, 24 Mar 2026 16:19:54 -0600 (MDT) 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 w3MOJJMEQq5r; Tue, 24 Mar 2026 16:19:54 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1774390791; bh=EpdrH5t8qfv1Sn6N/argdBa3zVizuSk453TcxJRWoG0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lpXMjRg3kwuCyI/8QuebOz+lQEcjR4xCGa+hQthSmWmmWGQIiIMld68D2X5qSbIA5 AYFW/Q3QJaQ0hCcdA+ji83m7PBvkNi+40zcjhLY5qB3nypKhltFQvrBevjp+EF8jOG mSIrhjtxlIl/8+enYUedyCW2Iu5STcFD7XqCo4GAea6qQOqgvQVCcZ06rM+cTJ/6mZ 2JAcz8VJhmV9CM/5tyruwHoAmA25UXvosoPQZIx7z5sUTsisLxDHE9/pNfnQrB4QMs /SMOVN6lsYS1NCMaLg4j6wDK/GAuJems6SpWkTfCnqWibPe4prxz7s2UxK5cwJnhDa rLziknVYpIbdg== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id DCDF26A228; Tue, 24 Mar 2026 16:19:50 -0600 (MDT) From: Simon Glass To: U-Boot Concept Date: Tue, 24 Mar 2026 16:19:06 -0600 Message-ID: <20260324221911.3678307-13-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260324221911.3678307-1-sjg@u-boot.org> References: <20260324221911.3678307-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: WJRQGU5JVYN6EZHHMA2W2AVBY2EUSSIF X-Message-ID-Hash: WJRQGU5JVYN6EZHHMA2W2AVBY2EUSSIF 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 X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 12/12] doc: bootstd: Document multi-entry bootflow scanning 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 overview to show the entry column in the iteration table and describe how BOOTMETHF_MULTI bootmeths produce multiple bootflows per partition, including the entry_name shown in bootflow info. Update the extlinux doc to explain that each label becomes a separate bootflow, that include directives are processed during scanning, and that pxe_boot_entry() boots a specific entry directly. Update the BLS doc to mention multi-entry support for entries directory scanning. Signed-off-by: Simon Glass --- doc/develop/bootstd/bls.rst | 4 ++++ doc/develop/bootstd/extlinux.rst | 12 ++++++----- doc/develop/bootstd/overview.rst | 37 +++++++++++++++++++++----------- 3 files changed, 36 insertions(+), 17 deletions(-) diff --git a/doc/develop/bootstd/bls.rst b/doc/develop/bootstd/bls.rst index 7dc4a9de4ff..327ab7c1c55 100644 --- a/doc/develop/bootstd/bls.rst +++ b/doc/develop/bootstd/bls.rst @@ -13,6 +13,10 @@ 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. +The bootmeth sets ``BOOTMETHF_MULTI`` so that each ``.conf`` file in the +entries directory produces a separate bootflow. The ``bflow->entry`` field +selects which file to use during scanning. + 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 diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst index 0c8526d7325..304a96689b8 100644 --- a/doc/develop/bootstd/extlinux.rst +++ b/doc/develop/bootstd/extlinux.rst @@ -18,12 +18,14 @@ Note that the :doc:`pxelinux` uses the same file format, but in a network context. When invoked on a bootdev, this bootmeth searches for the file and creates a -bootflow if found. +bootflow for each label defined in the configuration. Since an extlinux config +can contain several labels (each pointing to a different kernel), the bootmeth +sets the ``BOOTMETHF_MULTI`` flag so that the iterator produces one bootflow per +label. The ``bflow->entry`` field selects which label to use. Include directives +are processed during scanning so labels from included files are also discovered. -When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up -the context, then ``pxe_process_str()`` to process the file. Depending on the -contents, this may boot an operating system or provide a list of options to -the user, perhaps with a timeout. +When the bootflow is booted, ``pxe_boot_entry()`` parses the config, walks to +the selected label and boots it directly. The compatible string "u-boot,extlinux" is used for the driver. It is present if `CONFIG_BOOTMETH_EXTLINUX` is enabled. diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index f070f54efd7..0066bb5efee 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -654,19 +654,32 @@ sets it to zero and increments the second counter. You can think of all the counters together as a number with three digits which increment in order, with the least-sigificant digit on the right, counting like this: - ======== ======= ======= - bootdev part method - ======== ======= ======= - 0 0 0 - 0 0 1 - 0 0 2 - 0 1 0 - 0 1 1 - 0 1 2 - 1 0 0 - 1 0 1 + ======== ======= ======= ======= + bootdev part method entry + ======== ======= ======= ======= + 0 0 0 0 + 0 0 0 1 + 0 0 0 2 + 0 0 1 0 + 0 0 2 0 + 0 1 0 0 + 0 1 0 1 + 0 1 0 2 + 0 1 1 0 + 0 1 2 0 + 1 0 0 0 + 1 0 0 1 ... - ======== ======= ======= + ======== ======= ======= ======= + +If a bootmeth sets the ``BOOTMETHF_MULTI`` flag, it can produce multiple +bootflows from a single partition. Each bootflow is called an `entry`. In the +table above, the `entry` column shows how the iterator tries entry 0, 1, 2, ... +for such a bootmeth before moving to the next method. For bootmeths without +``BOOTMETHF_MULTI``, the entry is always 0 and the column can be ignored. The +entry index is passed to the bootmeth via ``bflow->entry``. Each bootflow also +stores an ``entry_name`` (e.g. the extlinux label or BLS title) which is shown +in ``bootflow info`` alongside the entry number. The maximum value for `method` is `num_methods - 1` so when it exceeds that, it goes back to 0 and the next `part` is considered. The maximum value for that is