From patchwork Tue Sep 30 23:25:52 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 466 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=1759274839; bh=q1lg4hohrxqW0wwNyL+LBl3X6H2oOroXqrB6Enaq3Jg=; 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=rFdulpaoyh3e49/XyS0qVzIWCAMLMArxX5GPHyrk/7RffdzSnr46Ku6wtq7xXqC21 7umucpJdyKxnIeFApOVXDWNMrJ3xVTY0vRuLacEmQ2lHajSftJzW5VEtwC++bZGgky l8RGNYDgICUeTeS+ujtSo8O5AQdRM2JqXhbxva4Vl5IeQ2n+VJ3ywsShBlha54s1DE GgS5a8ssfLcG6qy/CLWyx62ff76tVloLbCm+xwZHxNxVHG1XMPXaGsUQX9Bvqgwdyf zRyGiyI94pVZtjTG73C9oeWz+U/NMws0o3sBQ3BO9KlzvWMWOVzMMPiIuOKFwq1XfV maJ4hbrm3NKAA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 9C6AB67B7A for ; Tue, 30 Sep 2025 17:27:19 -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 4ImWTLdPf8CF for ; Tue, 30 Sep 2025 17:27:19 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1759274839; bh=q1lg4hohrxqW0wwNyL+LBl3X6H2oOroXqrB6Enaq3Jg=; 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=rFdulpaoyh3e49/XyS0qVzIWCAMLMArxX5GPHyrk/7RffdzSnr46Ku6wtq7xXqC21 7umucpJdyKxnIeFApOVXDWNMrJ3xVTY0vRuLacEmQ2lHajSftJzW5VEtwC++bZGgky l8RGNYDgICUeTeS+ujtSo8O5AQdRM2JqXhbxva4Vl5IeQ2n+VJ3ywsShBlha54s1DE GgS5a8ssfLcG6qy/CLWyx62ff76tVloLbCm+xwZHxNxVHG1XMPXaGsUQX9Bvqgwdyf zRyGiyI94pVZtjTG73C9oeWz+U/NMws0o3sBQ3BO9KlzvWMWOVzMMPiIuOKFwq1XfV maJ4hbrm3NKAA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 8A95067E2B for ; Tue, 30 Sep 2025 17:27:19 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1759274838; bh=leXV4Pyz5Gj8gW6zEyvO1E1daGxcjUnorDcxA1ymer8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tyi551BVG4AOqSOvxGJJAC4FxVK2DIY8rygYiOJ0Y6XlDh2pvQovMtZ4GZQkOfBOn HSb39/XdzQ5CVEpmSqtXCexoRmeYGIS5wbQoI7QL0cWbI8x7n4YicVmjIl7azi8osR NIc4XZVn3WWCAdEBnu72Z/8ZmoTW+cL/OxLBcNrKw6IDhJ0lA8Idcj1bD2E1at8DHQ wAKGqEGa0/mtnkOJUv/W0KE2SQhI4ufWJCMR2Tds2ycg9GP5J9JbWyEZXAvsjFnSZX rg4zKqDyNnXyCHFJTV8Bsu2REzSrCneHhtiw/KGTP0pk3jKNqE+CdBD6SmTlNyL/FU 2D77CpeWdIl7Q== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 2899A67B5E; Tue, 30 Sep 2025 17:27:18 -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 sykbUGbMT5OW; Tue, 30 Sep 2025 17:27:18 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1759274831; bh=LhdM68z6t1M9+DY6b83yWkmEnj8lVBjyEat6sDMRNpc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=r0vFCjXoGBmM38oyHolafrjny3SqlC4lQR6J/sZYsJ/yjT4xGWNglecAKzHOGr4yF 3TPumh4FHyaxhc4yzSNvfyG8ARE+E6i+jaC+JObe7mYzVchJs8XPlSGzxCYIxpd/A2 5PHPugOac8xxN1Kvd8hd9ODT0MWx7uByr5xNysoXj0klyGAIQqZAeSza8D97bKawYC +fh2suxw0/Fvg233FI0aAbb20D3bEtR8ScUybiJF9AAOx8B8RDpYC9kj76xnbl3J/Q 77F/Ls1lw7f0e8tCWEdHZilWldeRE79OJwTKCnSMhgA0n2BG9Wn/LRChTE1n0vvecE xiHfbFlUJAqeA== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 615E867EAB; Tue, 30 Sep 2025 17:27:11 -0600 (MDT) From: Simon Glass To: U-Boot Concept Date: Tue, 30 Sep 2025 17:25:52 -0600 Message-ID: <20250930232611.1564850-16-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250930232611.1564850-1-sjg@u-boot.org> References: <20250930232611.1564850-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: ZP3IZA54C7EYPPTGOZN76YSQX3K63XZK X-Message-ID-Hash: ZP3IZA54C7EYPPTGOZN76YSQX3K63XZK 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: Heinrich Schuchardt , Simon Glass X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH v2 15/15] boot: doc: Update for new global-bootmeth features 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 Provide some developer documentation on the priority feature for global bootmeths. Signed-off-by: Simon Glass --- Changes in v2: - Add a bit more detail suggested by Heinrich doc/develop/bootstd/overview.rst | 40 +++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index ca76bad7bca..208c371bb0e 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -133,7 +133,8 @@ which scans for available bootflows, optionally listing each find it finds (-l) and trying to boot it (-b). When global bootmeths are available, these are typically checked before the -above bootdev scanning. +above bootdev scanning, but it is possible provide a priority to make them +run later, by setting the glob_prio field in the driver's bind() method. Controlling ordering @@ -614,9 +615,9 @@ simply copied into the iterator. Either way, the `method_order` array it set up, along with `num_methods`. Note that global bootmeths are always put at the end of the ordering. If any are -present, `cur_method` is set to the first one, so that global bootmeths are done -first. Once all have been used, these bootmeths are dropped from the iteration. -When there are no global bootmeths, `cur_method` is set to 0. +present, `cur_method` is set to the first one, so that global bootmeths are +processed first, so long as their priority allows it. Bootstd keeps track of +which global bootmeths have been used, to make sure they are only used once. At this point the iterator is ready to use, with the first bootmeth selected. Most of the other fields are 0. This means that the current partition @@ -716,8 +717,35 @@ to the next partition, or bootdev, for example. The special values `BF_NO_MORE_PARTS` and `BF_NO_MORE_DEVICES` handle this. When `iter_incr` sees `BF_NO_MORE_PARTS` it knows that it should immediately move to the next bootdev. When it sees `BF_NO_MORE_DEVICES` it knows that there is nothing more it can do -so it should immediately return. The caller of `iter_incr()` is responsible for -updating the `err` field, based on the return value it sees. +so it should immediately run any unused global bootmeths and then return. The +caller of `iter_incr()` is responsible for updating the `err` field, based on +the return value it sees. + +Global bootmeths can have a non-zero priority, which indicates where in the +iteration sequence they should run. Each time a new bootdev is produced by a +hunter, all of the global bootmeths are first checked to see if they should run +before this new bootdev. For example, if the bootdev was produced by a hunter +with priority BOOTDEVP_6_NET_BASE, then a quick check is made for global +bootmeths with that priority or less. If there are any, they run before the new +bootdev is processed. + +Assuming they are enabled and the iteration sequence runs right to the end, all +global bootmeths will be used. This is handled by a special case at the end of +iter_incr(), where it processes amy so-far-unused global bootmeths. + +It is important to note the special nature of global bootmeths, with respect to +priority. If there are two normal bootmeths and a global one, the normal ones +are run for each bootdev, but the global one is independent of bootdevs. The +order might be: + + bootdev priority 3: normal-1, normal-3 + global-2, prio 4 + bootdev priority 5: normal-1, normal-3 + +Of course if a specific bootmeth ordering is provided, then this overrides the +default ordering. Global bootmeths must be listed at the end, reflecting their +hybrid nature (they are bootmeths but operate on the system as a whole, not on +a particular bootdev). The above describes the iteration process at a high level. It is basically a very simple increment function with a checker called `bootflow_check()` that