[PATCH v2 00/14] doc: Add documentation for bootmeths

[PATCH v2 00/14] doc: Add documentation for bootmeths

[Simon Glass]

This series adds some documentation about most of the bootmeths and
tidies up a few minor areas.

It also fixes a bug in network-based booting of a script.

Changes in v2:
- Add new patch to mention automatic binding of bootmeths
- Adjustments from Heinrich's comments

Simon Glass (14):
  MAINTAINERS: Rename BOOTDEVICE
  doc: Move bootstd into its own directory
  doc: Mention automatic binding of bootmeths
  doc: Add a description for bootmeth_extlinux
  doc: Add a description for bootmeth_pxe
  doc: Add a description for bootmeth_qfw
  doc: Add a description for bootmeth_cros
  doc: Add a description for bootmeth_sandbox
  bootstd: Tidy up comments on the boothmeth drivers
  bootstd: Correct handling of script from network
  doc: Add a description for bootmeth_script
  doc: Add a link to VBE from the bootstd docs
  boot: Correct indentation in efi bootmeth
  doc: Describe the bootstd settings

 MAINTAINERS                                   |  4 +-
 boot/bootmeth_efi.c                           |  3 +-
 boot/bootmeth_extlinux.c                      |  2 +-
 boot/bootmeth_qfw.c                           |  2 +-
 boot/bootmeth_sandbox.c                       |  2 +-
 boot/bootmeth_script.c                        | 53 +++++++++++--------
 doc/board/starfive/milk-v_mars_cm.rst         |  2 +-
 doc/develop/board_best_practices.rst          |  2 +-
 doc/develop/bootstd/cros.rst                  | 33 ++++++++++++
 doc/develop/bootstd/extlinux.rst              | 28 ++++++++++
 doc/develop/bootstd/index.rst                 | 15 ++++++
 .../{bootstd.rst => bootstd/overview.rst}     | 43 ++++++++++-----
 doc/develop/bootstd/pxelinux.rst              | 27 ++++++++++
 doc/develop/bootstd/qfw.rst                   | 20 +++++++
 doc/develop/bootstd/sandbox.rst               | 17 ++++++
 doc/develop/bootstd/script.rst                | 52 ++++++++++++++++++
 doc/develop/index.rst                         |  2 +-
 doc/usage/cmd/bootdev.rst                     |  2 +-
 doc/usage/cmd/bootflow.rst                    |  2 +-
 doc/usage/cmd/bootmeth.rst                    |  2 +-
 doc/usage/environment.rst                     |  2 +-
 21 files changed, 269 insertions(+), 46 deletions(-)
 create mode 100644 doc/develop/bootstd/cros.rst
 create mode 100644 doc/develop/bootstd/extlinux.rst
 create mode 100644 doc/develop/bootstd/index.rst
 rename doc/develop/{bootstd.rst => bootstd/overview.rst} (95%)
 create mode 100644 doc/develop/bootstd/pxelinux.rst
 create mode 100644 doc/develop/bootstd/qfw.rst
 create mode 100644 doc/develop/bootstd/sandbox.rst
 create mode 100644 doc/develop/bootstd/script.rst

-- 
2.34.1

[PATCH v2 01/14] MAINTAINERS: Rename BOOTDEVICE

[Simon Glass]

Rename this to BOOTSTD which is the normal name for the feature.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

(no changes since v1)

 MAINTAINERS | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 2c6de3a1d84..9bee9284cca 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -918,7 +918,7 @@ F:	drivers/block/blkmap.c
 F:	include/blkmap.h
 F:	test/dm/blkmap.c
 
-BOOTDEVICE
+BOOTSTD
 M:	Simon Glass <sjg@chromium.org>
 S:	Maintained
 F:	boot/bootdev*.c
-- 
2.34.1

[PATCH v2 02/14] doc: Move bootstd into its own directory

[Simon Glass]

Before adding more files, move the bootstd docs into a new directory,
with an index.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

(no changes since v1)

 MAINTAINERS                                       |  2 +-
 doc/board/starfive/milk-v_mars_cm.rst             |  2 +-
 doc/develop/board_best_practices.rst              |  2 +-
 doc/develop/bootstd/index.rst                     |  9 +++++++++
 doc/develop/{bootstd.rst => bootstd/overview.rst} | 14 +++++++-------
 doc/develop/index.rst                             |  2 +-
 doc/usage/cmd/bootdev.rst                         |  2 +-
 doc/usage/cmd/bootflow.rst                        |  2 +-
 doc/usage/cmd/bootmeth.rst                        |  2 +-
 doc/usage/environment.rst                         |  2 +-
 10 files changed, 24 insertions(+), 15 deletions(-)
 create mode 100644 doc/develop/bootstd/index.rst
 rename doc/develop/{bootstd.rst => bootstd/overview.rst} (99%)

diff --git a/MAINTAINERS b/MAINTAINERS
index 9bee9284cca..86b830aa997 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -927,7 +927,7 @@ F:	boot/bootmeth*.c
 F:	boot/bootstd.c
 F:	cmd/bootdev.c
 F:	cmd/bootflow.c
-F:	doc/develop/bootstd.rst
+F:	doc/develop/bootstd/
 F:	doc/usage/bootdev.rst
 F:	doc/usage/bootflow.rst
 F:	doc/usage/bootmeth.rst
diff --git a/doc/board/starfive/milk-v_mars_cm.rst b/doc/board/starfive/milk-v_mars_cm.rst
index b31de6043bb..52d4e5e9098 100644
--- a/doc/board/starfive/milk-v_mars_cm.rst
+++ b/doc/board/starfive/milk-v_mars_cm.rst
@@ -89,7 +89,7 @@ provide a default value.
 
 The variable *$fdtfile* is used in the boot process to automatically load
 a device-tree provided by the operating system. For details of the boot
-process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>`
+process refer to the :doc:`/develop/bootstd/index`
 description.
 
 Boot source selection
diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst
index f44401eab7d..09632c80ce7 100644
--- a/doc/develop/board_best_practices.rst
+++ b/doc/develop/board_best_practices.rst
@@ -7,7 +7,7 @@ In addition to the regular best practices such as using :doc:`checkpatch` and
 following the :doc:`docstyle` and the :doc:`codingstyle` there are some things
 which are specific to creating a new board port.
 
-* Implement :doc:`bootstd` to ensure that most operating systems will be
+* Implement :doc:`bootstd/index` to ensure that most operating systems will be
   supported by the platform.
 
 * The platform defconfig file must be generated via `make savedefconfig`.
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
new file mode 100644
index 00000000000..f4f87c7787c
--- /dev/null
+++ b/doc/develop/bootstd/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644
--- a/doc/develop/bootstd.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0+:
 
-U-Boot Standard Boot
-====================
+Standard Boot Overview
+======================
 
 Introduction
 ------------
@@ -17,7 +17,7 @@ introduces the following concepts:
 For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible
 for creating a bootflow for each kernel combination that it wants to offer.
 These bootflows are stored on media so they can be discovered by U-Boot. This
-feature is typically called `distro boot` (see :doc:`distro`) because it is
+feature is typically called `distro boot` (see :doc:`../distro`) because it is
 a way for distributions to boot on any hardware.
 
 Traditionally U-Boot has relied on scripts to implement this feature. See
@@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to different Operating
 Systems (such as Chromium OS) and devices (beyond just block and network
 devices). It supports EFI boot and EFI bootmgr too.
 
-Finally, standard boot supports the operation of :doc:`vbe`.
+Finally, standard boot supports the operation of :doc:`../vbe`.
 
 Bootflow
 --------
@@ -427,16 +427,16 @@ Three commands are available:
 
 `bootdev`
     Allows listing of available bootdevs, selecting a particular one and
-    getting information about it. See :doc:`../usage/cmd/bootdev`
+    getting information about it. See :doc:`/usage/cmd/bootdev`
 
 `bootflow`
     Allows scanning one or more bootdevs for bootflows, listing available
     bootflows, selecting one, obtaining information about it and booting it.
-    See :doc:`../usage/cmd/bootflow`
+    See :doc:`/usage/cmd/bootflow`
 
 `bootmeth`
     Allow listing of available bootmethds and setting the order in which they
-    are tried. See :doc:`../usage/cmd/bootmeth`
+    are tried. See :doc:`/usage/cmd/bootmeth`
 
 .. _BootflowStates:
 
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index f9c4bf839ee..c0107a783fc 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -29,7 +29,7 @@ Implementation
 
    directories
    bloblist
-   bootstd
+   bootstd/index
    ci_testing
    commands
    config_binding
diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst
index f759abab354..98a0f43c580 100644
--- a/doc/usage/cmd/bootdev.rst
+++ b/doc/usage/cmd/bootdev.rst
@@ -22,7 +22,7 @@ Description
 The `bootdev` command is used to manage bootdevs. It can list available
 bootdevs, select one and obtain information about it.
 
-See :doc:`../../develop/bootstd` for more information about bootdevs in general.
+See :doc:`/develop/bootstd/index` for more information about bootdevs in general.
 
 
 bootdev list
diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst
index 6519e4880a9..5d41fe37a7a 100644
--- a/doc/usage/cmd/bootflow.rst
+++ b/doc/usage/cmd/bootflow.rst
@@ -26,7 +26,7 @@ Description
 The `bootflow` command is used to manage bootflows. It can scan bootdevs to
 locate bootflows, list them and boot them.
 
-See :doc:`../../develop/bootstd` for more information.
+See :doc:`/develop/bootstd/index` for more information.
 
 Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL) must
 be enabled to obtain full functionality with this command. Otherwise, it only
diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst
index bac9fdf85cd..c3d2ec1574b 100644
--- a/doc/usage/cmd/bootmeth.rst
+++ b/doc/usage/cmd/bootmeth.rst
@@ -21,7 +21,7 @@ Description
 The `bootmeth` command is used to manage bootmeths. It can list them and change
 the order in which they are used.
 
-See :doc:`../../develop/bootstd` for more information.
+See :doc:`/develop/bootstd/index` for more information.
 
 
 .. _bootmeth_order:
diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
index 7d4b448cb30..cc33d3ec0f2 100644
--- a/doc/usage/environment.rst
+++ b/doc/usage/environment.rst
@@ -100,7 +100,7 @@ to add environment variables.
 
 Board maintainers are encouraged to migrate to the text-based environment as it
 is easier to maintain. The distro-board script still requires the old-style
-environments, so use :doc:`../develop/bootstd` instead.
+environments, so use :doc:`/develop/bootstd/index` instead.
 
 
 List of environment variables
-- 
2.34.1

[PATCH v2 03/14] doc: Mention automatic binding of bootmeths

[Simon Glass]

Add a note about how bootmeth drivers are instantiated.

Signed-off-by: Simon Glass <sjg@chromium.org>
Suggested-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---

Changes in v2:
- Add new patch to mention automatic binding of bootmeths

 doc/develop/bootstd/overview.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index 761f61a573b..d5051e986bb 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -419,6 +419,9 @@ Bootmeth drivers are provided for:
    - VBE
    - EFI boot using boot manager
 
+Each driver is controlled by a Kconfig option. If no bootmeth driver is
+selected by a compatible string in the devicetree, all available bootmeth
+drivers are bound automatically.
 
 Command interface
 -----------------
-- 
2.34.1

[PATCH v2 04/14] doc: Add a description for bootmeth_extlinux

[Simon Glass]

Add documentation for the extlinux bootmeth.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

Changes in v2:
- Adjustments from Heinrich's comments

 doc/develop/bootstd/extlinux.rst | 28 ++++++++++++++++++++++++++++
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  4 ++--
 3 files changed, 31 insertions(+), 2 deletions(-)
 create mode 100644 doc/develop/bootstd/extlinux.rst

diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst
new file mode 100644
index 00000000000..d87730410ee
--- /dev/null
+++ b/doc/develop/bootstd/extlinux.rst
@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Extlinux Bootmeth
+=================
+
+`Extlinux <https://uapi-group.org/specifications/specs/boot_loader_specification>`_
+(sometimes called syslinux) allows U-Boot to provide a menu of available
+operating systems from which the user can choose.
+
+U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of
+a list of named operating systems along with the kernel, initial ramdisk and
+other settings. The file is stored in the `extlinux/` subdirectory, possibly
+under the `boot/` subdirectory. This list of prefixes ({"/", "/boot"} by
+default) can be selected with the `filename-prefixes` property in the bootstd
+device.
+
+Note that the PXE bootmeth 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.
+
+When the bootflow is booted, the bootmeth calls pxe_setup_ctx() to set up the
+context, then pxe_process() 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.
+
+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/index.rst b/doc/develop/bootstd/index.rst
index f4f87c7787c..5bbb3d633a3 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -7,3 +7,4 @@ Standard Boot
    :maxdepth: 2
 
    overview
+   extlinux
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index d5051e986bb..7af159b9ca8 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -410,9 +410,9 @@ a good selection of boot options is available.
 Available bootmeth drivers
 --------------------------
 
-Bootmeth drivers are provided for:
+Bootmeth drivers are provided for booting from various media:
 
-   - extlinux / syslinux boot from a disk
+   - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
    - extlinux boot from a network (PXE)
    - U-Boot scripts from disk, network or SPI flash
    - EFI boot using bootefi from disk
-- 
2.34.1

[PATCH v2 05/14] doc: Add a description for bootmeth_pxe

[Simon Glass]

Add documentation for the pxe bootmeth.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

Changes in v2:
- Adjustments from Heinrich's comments

 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  2 +-
 doc/develop/bootstd/pxelinux.rst | 27 +++++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 doc/develop/bootstd/pxelinux.rst

diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
index 5bbb3d633a3..5052afe448f 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -8,3 +8,4 @@ Standard Boot
 
    overview
    extlinux
+   pxelinux
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index 7af159b9ca8..b9b45f1e7a7 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -413,7 +413,7 @@ Available bootmeth drivers
 Bootmeth drivers are provided for booting from various media:
 
    - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
-   - extlinux boot from a network (PXE)
+   - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
    - U-Boot scripts from disk, network or SPI flash
    - EFI boot using bootefi from disk
    - VBE
diff --git a/doc/develop/bootstd/pxelinux.rst b/doc/develop/bootstd/pxelinux.rst
new file mode 100644
index 00000000000..a4e559160ca
--- /dev/null
+++ b/doc/develop/bootstd/pxelinux.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+PXE Bootmeth
+============
+
+PXE (Preboot eXecution-Environment) provides a way to boot an operating system
+over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to
+provide a menu of possible Operating Systems from which the user can choose.
+
+U-Boot includes a parser for the `extlinux.conf` file described
+`here <https://uapi-group.org/specifications/specs/boot_loader_specification>`_.
+It consists primarily of a list of named operating systems along with the
+kernel, initial ramdisk and other settings. The file is retrieved from a network
+server using the TFTP protocol.
+
+When invoked on a bootdev, this bootmeth searches for the file and creates a
+bootflow if found. See
+`PXELINUX <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX>`_ for
+a full description of the search procedure.
+
+When the bootflow is booted, the bootmeth calls pxe_setup_ctx() to set up the
+context, then pxe_process() 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.
+
+The compatible string "u-boot,extlinux-pxe" is used for the driver. It is
+present if `CONFIG_BOOTMETH_EXTLINUX_PXE` is enabled.
-- 
2.34.1

[PATCH v2 06/14] doc: Add a description for bootmeth_qfw

[Simon Glass]

Add documentation for the qfw bootmeth.

Fix up the compatible string to drop the 'extlinux' part, which is not
relevant to this bootmeth.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

Changes in v2:
- Adjustments from Heinrich's comments

 boot/bootmeth_qfw.c              |  2 +-
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  1 +
 doc/develop/bootstd/qfw.rst      | 20 ++++++++++++++++++++
 4 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 doc/develop/bootstd/qfw.rst

diff --git a/boot/bootmeth_qfw.c b/boot/bootmeth_qfw.c
index dfaa944594e..2f8e00cf350 100644
--- a/boot/bootmeth_qfw.c
+++ b/boot/bootmeth_qfw.c
@@ -88,7 +88,7 @@ static struct bootmeth_ops qfw_bootmeth_ops = {
 };
 
 static const struct udevice_id qfw_bootmeth_ids[] = {
-	{ .compatible = "u-boot,qfw-extlinux" },
+	{ .compatible = "u-boot,qfw-bootmeth" },
 	{ }
 };
 
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
index 5052afe448f..f8fce7207ce 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -9,3 +9,4 @@ Standard Boot
    overview
    extlinux
    pxelinux
+   qfw
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index b9b45f1e7a7..f23e344546d 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -418,6 +418,7 @@ Bootmeth drivers are provided for booting from various media:
    - EFI boot using bootefi from disk
    - VBE
    - EFI boot using boot manager
+   - :doc:`QFW <qfw>`: QEMU firmware interface
 
 Each driver is controlled by a Kconfig option. If no bootmeth driver is
 selected by a compatible string in the devicetree, all available bootmeth
diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
new file mode 100644
index 00000000000..b2ff1364fd8
--- /dev/null
+++ b/doc/develop/bootstd/qfw.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+QFW Bootmeth
+============
+
+`QEMU <hhttps://www.qemu.org/>`_ is a system emulator which is able to boot
+Operating Systems. QEMU provides specific support for booting an OS image
+provided on the QEMU command line.
+
+When invoked on a bootdev for UCLASS_QFW, this bootmeth reads the kernel
+provided by the QEMU `-kernel` argument, the initial ramdisk and provided by
+`-initrd` and the boot arguments (command line) provided by `-append` into
+memory ready for booting.
+
+When the bootflow is booted, the bootmeth tries the `booti` command first, then
+falls back to the `bootz` command. U-Boot's 'control' devicetree is passed
+through to the kernel.
+
+The compatible string "u-boot,qfw-bootmeth" is used for the driver. It is
+present if `CONFIG_QFW` is enabled.
-- 
2.34.1

[PATCH v2 07/14] doc: Add a description for bootmeth_cros

[Simon Glass]

Add documentation for the cros bootmeth.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

Changes in v2:
- Adjustments from Heinrich's comments

 doc/develop/bootstd/cros.rst     | 33 ++++++++++++++++++++++++++++++++
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  1 +
 3 files changed, 35 insertions(+)
 create mode 100644 doc/develop/bootstd/cros.rst

diff --git a/doc/develop/bootstd/cros.rst b/doc/develop/bootstd/cros.rst
new file mode 100644
index 00000000000..92b83729150
--- /dev/null
+++ b/doc/develop/bootstd/cros.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+ChromiumOS Bootmeth
+===================
+
+ChromiumOS provides a mechanism for booting its Operating System from a block
+device, described
+`here <https://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot/>`_.
+
+U-Boot includes support for reading the associated data structures from the
+device and identifying a bootable ChromiumOS image. This structure includes the
+kernel itself, boot arguments (kernel command line), as well as the x86 setup
+block (for x86 only).
+
+When invoked on a bootdev, this bootmeth searches for kernel partitions with
+the appropriate GUID (Globally Unique Identifier). When found, the information
+is loaded and a bootflow is created.
+
+When the bootflow is booted, the bootmeth reads the kernel and boot arguments.
+It then boots the kernel using zboot (on x86) or bootm (on ARM). The boot
+arguments are adjusted to replace %U with the UUID of the selected kernel
+partition. This results in the correct root disk being used, which is the next
+partition after the kernel partition.
+
+For ARM, a :doc:`/usage/fit/index` is used. The `CONFIG_FIT_BEST_MATCH` option
+must be enabled for U-Boot to select the correct devicetree to boot with.
+
+Note that a ChromiumOS image typically has two copies of the Operating System,
+each with its own kernel and root disk. There is no initial ramdisk (initrd).
+This means that this bootmeth typically locates two separate images.
+
+The compatible string "u-boot,cros" is used for the driver. It is present
+if `CONFIG_BOOTMETH_CROS` is enabled.
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
index f8fce7207ce..69fd3c2d2eb 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -10,3 +10,4 @@ Standard Boot
    extlinux
    pxelinux
    qfw
+   cros
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index f23e344546d..9b50b5593c4 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -417,6 +417,7 @@ Bootmeth drivers are provided for booting from various media:
    - U-Boot scripts from disk, network or SPI flash
    - EFI boot using bootefi from disk
    - VBE
+   - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
    - EFI boot using boot manager
    - :doc:`QFW <qfw>`: QEMU firmware interface
 
-- 
2.34.1

[PATCH v2 08/14] doc: Add a description for bootmeth_sandbox

[Simon Glass]

Add documentation for the sandbox bootmeth.

Fix up the compatible string to drop the 'extlinux' part, which is not
relevant to this bootmeth.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

Changes in v2:
- Adjustments from Heinrich's comments

 boot/bootmeth_sandbox.c          |  2 +-
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  1 +
 doc/develop/bootstd/sandbox.rst  | 17 +++++++++++++++++
 4 files changed, 20 insertions(+), 1 deletion(-)
 create mode 100644 doc/develop/bootstd/sandbox.rst

diff --git a/boot/bootmeth_sandbox.c b/boot/bootmeth_sandbox.c
index 0bc8f688e30..26c713bb5f3 100644
--- a/boot/bootmeth_sandbox.c
+++ b/boot/bootmeth_sandbox.c
@@ -55,7 +55,7 @@ static struct bootmeth_ops sandbox_bootmeth_ops = {
 };
 
 static const struct udevice_id sandbox_bootmeth_ids[] = {
-	{ .compatible = "u-boot,sandbox-extlinux" },
+	{ .compatible = "u-boot,sandbox-bootmeth" },
 	{ }
 };
 
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
index 69fd3c2d2eb..2c5d2d3fade 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -11,3 +11,4 @@ Standard Boot
    pxelinux
    qfw
    cros
+   sandbox
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index 9b50b5593c4..add054f3088 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -420,6 +420,7 @@ Bootmeth drivers are provided for booting from various media:
    - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
    - EFI boot using boot manager
    - :doc:`QFW <qfw>`: QEMU firmware interface
+   - :doc:`sandbox <sandbox>` used only for testing
 
 Each driver is controlled by a Kconfig option. If no bootmeth driver is
 selected by a compatible string in the devicetree, all available bootmeth
diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst
new file mode 100644
index 00000000000..a90c1accc84
--- /dev/null
+++ b/doc/develop/bootstd/sandbox.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Sandbox Bootmeth
+================
+
+The sandbox bootmeth is only used for testing. It does not provide any facility
+for booting an OS. While sandbox can do all the processing before the actual
+boot, it is not connected in this bootmeth.
+
+When invoked on a bootdev, this bootmeth pretends to find a bootflow and creates
+the associated structure.
+
+When the bootflow is booted, the bootmeth returns -EENOTSUPP indicating that it
+is not supported.
+
+The compatible string "u-boot,sandbox-bootmeth" is used for the driver. It is present
+if `CONFIG_BOOTMETH_SANDBOX` is enabled.
-- 
2.34.1

[PATCH v2 09/14] bootstd: Tidy up comments on the boothmeth drivers

[Simon Glass]

Fix a typo in the comment and add one to the EFI driver too.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

(no changes since v1)

 boot/bootmeth_efi.c      | 1 +
 boot/bootmeth_extlinux.c | 2 +-
 boot/bootmeth_script.c   | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/boot/bootmeth_efi.c b/boot/bootmeth_efi.c
index 5a4c125835a..56a6e47f5b2 100644
--- a/boot/bootmeth_efi.c
+++ b/boot/bootmeth_efi.c
@@ -394,6 +394,7 @@ static const struct udevice_id distro_efi_bootmeth_ids[] = {
 	{ }
 };
 
+/* Put a number before 'efi' to provide a default ordering */
 U_BOOT_DRIVER(bootmeth_4efi) = {
 	.name		= "bootmeth_efi",
 	.id		= UCLASS_BOOTMETH,
diff --git a/boot/bootmeth_extlinux.c b/boot/bootmeth_extlinux.c
index 9b55686948f..fbb05ef928e 100644
--- a/boot/bootmeth_extlinux.c
+++ b/boot/bootmeth_extlinux.c
@@ -183,7 +183,7 @@ static const struct udevice_id extlinux_bootmeth_ids[] = {
 	{ }
 };
 
-/* Put an number before 'extlinux' to provide a default ordering */
+/* Put a number before 'extlinux' to provide a default ordering */
 U_BOOT_DRIVER(bootmeth_1extlinux) = {
 	.name		= "bootmeth_extlinux",
 	.id		= UCLASS_BOOTMETH,
diff --git a/boot/bootmeth_script.c b/boot/bootmeth_script.c
index 0e05d28d4d9..24da47c7259 100644
--- a/boot/bootmeth_script.c
+++ b/boot/bootmeth_script.c
@@ -250,7 +250,7 @@ static const struct udevice_id script_bootmeth_ids[] = {
 	{ }
 };
 
-/* Put an number before 'script' to provide a default ordering */
+/* Put a number before 'script' to provide a default ordering */
 U_BOOT_DRIVER(bootmeth_2script) = {
 	.name		= "bootmeth_script",
 	.id		= UCLASS_BOOTMETH,
-- 
2.34.1

[PATCH v2 10/14] bootstd: Correct handling of script from network

[Simon Glass]

When reading a script from a network, no block device is available.
Update the implementation to support this correctly, avoiding setting
environment variables which relate only to block devices.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

(no changes since v1)

 boot/bootmeth_script.c | 51 +++++++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 20 deletions(-)

diff --git a/boot/bootmeth_script.c b/boot/bootmeth_script.c
index 24da47c7259..c5cbf18c2e6 100644
--- a/boot/bootmeth_script.c
+++ b/boot/bootmeth_script.c
@@ -185,31 +185,42 @@ static int script_set_bootflow(struct udevice *dev, struct bootflow *bflow,
 
 static int script_boot(struct udevice *dev, struct bootflow *bflow)
 {
-	struct blk_desc *desc = dev_get_uclass_plat(bflow->blk);
+	struct blk_desc *desc;
 	ulong addr;
 	int ret = 0;
 
-	if (desc->uclass_id == UCLASS_USB) {
-		ret = env_set("devtype", "usb");
+	if (bflow->blk) {
+		desc = dev_get_uclass_plat(bflow->blk);
+		if (desc->uclass_id == UCLASS_USB) {
+			ret = env_set("devtype", "usb");
+		} else {
+			/*
+			 * If the uclass is AHCI, but the driver is ATA
+			 * (not scsi), set devtype to sata
+			 */
+			if (IS_ENABLED(CONFIG_SATA) &&
+			    desc->uclass_id == UCLASS_AHCI)
+				ret = env_set("devtype", "sata");
+			else
+				ret = env_set("devtype", blk_get_devtype(bflow->blk));
+		}
+		if (!ret)
+			ret = env_set_hex("devnum", desc->devnum);
+		if (!ret)
+			ret = env_set_hex("distro_bootpart", bflow->part);
+		if (!ret)
+			ret = env_set("prefix", bflow->subdir);
+		if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) &&
+		    !strcmp("mmc", blk_get_devtype(bflow->blk)))
+			ret = env_set_hex("mmc_bootdev", desc->devnum);
 	} else {
-		/* If the uclass is AHCI, but the driver is ATA
-		 * (not scsi), set devtype to sata
-		 */
-		if (IS_ENABLED(CONFIG_SATA) &&
-		    desc->uclass_id == UCLASS_AHCI)
-			ret = env_set("devtype", "sata");
-		else
-			ret = env_set("devtype", blk_get_devtype(bflow->blk));
+		const struct udevice *media = dev_get_parent(bflow->dev);
+
+		ret = env_set("devtype",
+			      uclass_get_name(device_get_uclass_id(media)));
+		if (!ret)
+			ret = env_set_hex("devnum", dev_seq(media));
 	}
-	if (!ret)
-		ret = env_set_hex("devnum", desc->devnum);
-	if (!ret)
-		ret = env_set_hex("distro_bootpart", bflow->part);
-	if (!ret)
-		ret = env_set("prefix", bflow->subdir);
-	if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) &&
-	    !strcmp("mmc", blk_get_devtype(bflow->blk)))
-		ret = env_set_hex("mmc_bootdev", desc->devnum);
 	if (ret)
 		return log_msg_ret("env", ret);
 
-- 
2.34.1

[PATCH v2 11/14] doc: Add a description for bootmeth_script

[Simon Glass]

Add documentation for the script bootmeth.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

Changes in v2:
- Adjustments from Heinrich's comments

 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  2 +-
 doc/develop/bootstd/script.rst   | 52 ++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 doc/develop/bootstd/script.rst

diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
index 2c5d2d3fade..9d35b567d55 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -11,4 +11,5 @@ Standard Boot
    pxelinux
    qfw
    cros
+   script
    sandbox
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index add054f3088..e4924b55ae7 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -414,7 +414,7 @@ Bootmeth drivers are provided for booting from various media:
 
    - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
    - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
-   - U-Boot scripts from disk, network or SPI flash
+   - :doc:`U-Boot scripts <script>` from disk, network or SPI flash
    - EFI boot using bootefi from disk
    - VBE
    - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
diff --git a/doc/develop/bootstd/script.rst b/doc/develop/bootstd/script.rst
new file mode 100644
index 00000000000..58ddc1cae1d
--- /dev/null
+++ b/doc/develop/bootstd/script.rst
@@ -0,0 +1,52 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Script Bootmeth
+===============
+
+This bootmeth provides a way to locate and run a script on a block or network
+device. It can also support SPI flash.
+
+For a block device the file is read from the selected partition, which must use
+a supported filesystem. The subdirectory to search in is defined by the bootstd
+list of prefixes ({"/", "/boot"} by default) and can be adjust with the
+`filename-prefixes` property in the bootstd device.
+
+For a network device, the filename is obtained from the `boot_script_dhcp`
+environment variable and the file is read using tftp. It must be in the
+top-level directory of the tftp server.
+
+In either case (file or network), the bootmeth searches for the file and creates
+a bootflow if found. The bootmeth searches for "boot.scr.uimg" first, then
+"boot.scr" if not found.
+
+For SPI flash, a script is read from flash using the offset provided by the
+"script_offset_f" environment variable.
+
+Some attempt is made to identify the Operating System: so far this only detects
+an `Armbian <https://www.armbian.com>`_
+distro. For block devices, if a file called "boot.bmp" exists in the same
+directory then it is used as the bootflow logo.
+
+When the bootflow is booted, the bootmeth sets these environment variables:
+
+    devtype
+        device type (e.g. "usb", "mmc", "ethernet" or "spi_flash")
+
+    devnum
+        device number, corresponding to the device 'sequence' number
+        `dev_seq(dev)`
+
+    distro_bootpart
+        (block devices only) partition number on the device (numbered from 1)
+
+    prefix
+        prefix used to find the file
+
+    mmc_bootdev
+        device number (same as `devnum`), set for sunxi mmc devices only
+
+The script file must be a FIT or a legacy uImage. It is loaded into memory and
+executed.
+
+The compatible string "u-boot,script" is used for the driver. It is present
+if `CONFIG_BOOTMETH_SCRIPT` is enabled.
-- 
2.34.1

[PATCH v2 12/14] doc: Add a link to VBE from the bootstd docs

[Simon Glass]

Link to this page to make it easier to find the VBE docs.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

(no changes since v1)

 doc/develop/bootstd/overview.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index e4924b55ae7..4a55b7da00a 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -416,7 +416,7 @@ Bootmeth drivers are provided for booting from various media:
    - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
    - :doc:`U-Boot scripts <script>` from disk, network or SPI flash
    - EFI boot using bootefi from disk
-   - VBE
+   - :doc:`VBE </develop/vbe>`: Verified Boot for Embedded
    - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
    - EFI boot using boot manager
    - :doc:`QFW <qfw>`: QEMU firmware interface
-- 
2.34.1

[PATCH v2 13/14] boot: Correct indentation in efi bootmeth

[Simon Glass]

Fix a minor indentation / whitespace problem in a comment.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Heinrich Schuchardt <xypron.glkp@gmx.de>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

(no changes since v1)

 boot/bootmeth_efi.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/boot/bootmeth_efi.c b/boot/bootmeth_efi.c
index 56a6e47f5b2..39232eb2e25 100644
--- a/boot/bootmeth_efi.c
+++ b/boot/bootmeth_efi.c
@@ -265,7 +265,7 @@ static int distro_efi_read_bootflow_net(struct bootflow *bflow)
 		return log_msg_ret("sz", -EINVAL);
 	bflow->size = size;
 
-    /* bootfile should be setup by dhcp*/
+	/* bootfile should be setup by dhcp */
 	bootfile_name = env_get("bootfile");
 	if (!bootfile_name)
 		return log_msg_ret("bootfile_name", ret);
-- 
2.34.1

[PATCH v2 14/14] doc: Describe the bootstd settings

[Simon Glass]

The bootstd node provides some configuration properties. Add these to
the documentation.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
---

(no changes since v1)

 doc/develop/bootstd/overview.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index 4a55b7da00a..d92a649beb0 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -406,6 +406,19 @@ You should probably also enable `CONFIG_BOOTSTD_DEFAULTS`, which provides
 several filesystem and network features (if `CONFIG_NET` is enabled) so that
 a good selection of boot options is available.
 
+Some devicetree properties are supported in the bootstd node when
+`CONFIG_BOOTSTD_FULL` is enabled:
+
+    filename-prefixes
+        List of prefixes to use when searching for files on block devices. This
+        defaults to {"/", "/boot/"} if not provided.
+
+    bootdev-order
+        Lists the bootdev ordering to use. Note that the deprecated
+        `boot_targets` environment variable overrides this, if present.
+
+    theme (subnode)
+        Sets the theme to use for menus. See :doc:`/develop/expo`.
 
 Available bootmeth drivers
 --------------------------
-- 
2.34.1

Re: [PATCH v2 01/14] MAINTAINERS: Rename BOOTDEVICE

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Rename this to BOOTSTD which is the normal name for the feature.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> (no changes since v1)
>
>  MAINTAINERS | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 2c6de3a1d84..9bee9284cca 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -918,7 +918,7 @@ F:	drivers/block/blkmap.c
>  F:	include/blkmap.h
>  F:	test/dm/blkmap.c
>  
> -BOOTDEVICE
> +BOOTSTD
>  M:	Simon Glass <sjg@chromium.org>
>  S:	Maintained
>  F:	boot/bootdev*.c
> -- 
> 2.34.1

Re: [PATCH v2 02/14] doc: Move bootstd into its own directory

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Before adding more files, move the bootstd docs into a new directory,
> with an index.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> (no changes since v1)
>
>  MAINTAINERS                                       |  2 +-
>  doc/board/starfive/milk-v_mars_cm.rst             |  2 +-
>  doc/develop/board_best_practices.rst              |  2 +-
>  doc/develop/bootstd/index.rst                     |  9 +++++++++
>  doc/develop/{bootstd.rst => bootstd/overview.rst} | 14 +++++++-------
>  doc/develop/index.rst                             |  2 +-
>  doc/usage/cmd/bootdev.rst                         |  2 +-
>  doc/usage/cmd/bootflow.rst                        |  2 +-
>  doc/usage/cmd/bootmeth.rst                        |  2 +-
>  doc/usage/environment.rst                         |  2 +-
>  10 files changed, 24 insertions(+), 15 deletions(-)
>  create mode 100644 doc/develop/bootstd/index.rst
>  rename doc/develop/{bootstd.rst => bootstd/overview.rst} (99%)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9bee9284cca..86b830aa997 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -927,7 +927,7 @@ F:	boot/bootmeth*.c
>  F:	boot/bootstd.c
>  F:	cmd/bootdev.c
>  F:	cmd/bootflow.c
> -F:	doc/develop/bootstd.rst
> +F:	doc/develop/bootstd/
>  F:	doc/usage/bootdev.rst
>  F:	doc/usage/bootflow.rst
>  F:	doc/usage/bootmeth.rst
> diff --git a/doc/board/starfive/milk-v_mars_cm.rst b/doc/board/starfive/milk-v_mars_cm.rst
> index b31de6043bb..52d4e5e9098 100644
> --- a/doc/board/starfive/milk-v_mars_cm.rst
> +++ b/doc/board/starfive/milk-v_mars_cm.rst
> @@ -89,7 +89,7 @@ provide a default value.
>  
>  The variable *$fdtfile* is used in the boot process to automatically load
>  a device-tree provided by the operating system. For details of the boot
> -process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>`
> +process refer to the :doc:`/develop/bootstd/index`
>  description.
>  
>  Boot source selection
> diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst
> index f44401eab7d..09632c80ce7 100644
> --- a/doc/develop/board_best_practices.rst
> +++ b/doc/develop/board_best_practices.rst
> @@ -7,7 +7,7 @@ In addition to the regular best practices such as using :doc:`checkpatch` and
>  following the :doc:`docstyle` and the :doc:`codingstyle` there are some things
>  which are specific to creating a new board port.
>  
> -* Implement :doc:`bootstd` to ensure that most operating systems will be
> +* Implement :doc:`bootstd/index` to ensure that most operating systems will be
>    supported by the platform.
>  
>  * The platform defconfig file must be generated via `make savedefconfig`.
> diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> new file mode 100644
> index 00000000000..f4f87c7787c
> --- /dev/null
> +++ b/doc/develop/bootstd/index.rst
> @@ -0,0 +1,9 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +Standard Boot
> +=============
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   overview
> diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst
> similarity index 99%
> rename from doc/develop/bootstd.rst
> rename to doc/develop/bootstd/overview.rst
> index 34631089ae0..761f61a573b 100644
> --- a/doc/develop/bootstd.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -1,7 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0+:
>  
> -U-Boot Standard Boot
> -====================
> +Standard Boot Overview
> +======================
>  
>  Introduction
>  ------------
> @@ -17,7 +17,7 @@ introduces the following concepts:
>  For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible
>  for creating a bootflow for each kernel combination that it wants to offer.
>  These bootflows are stored on media so they can be discovered by U-Boot. This
> -feature is typically called `distro boot` (see :doc:`distro`) because it is
> +feature is typically called `distro boot` (see :doc:`../distro`) because it is
>  a way for distributions to boot on any hardware.
>  
>  Traditionally U-Boot has relied on scripts to implement this feature. See
> @@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to different Operating
>  Systems (such as Chromium OS) and devices (beyond just block and network
>  devices). It supports EFI boot and EFI bootmgr too.
>  
> -Finally, standard boot supports the operation of :doc:`vbe`.
> +Finally, standard boot supports the operation of :doc:`../vbe`.
>  
>  Bootflow
>  --------
> @@ -427,16 +427,16 @@ Three commands are available:
>  
>  `bootdev`
>      Allows listing of available bootdevs, selecting a particular one and
> -    getting information about it. See :doc:`../usage/cmd/bootdev`
> +    getting information about it. See :doc:`/usage/cmd/bootdev`
>  
>  `bootflow`
>      Allows scanning one or more bootdevs for bootflows, listing available
>      bootflows, selecting one, obtaining information about it and booting it.
> -    See :doc:`../usage/cmd/bootflow`
> +    See :doc:`/usage/cmd/bootflow`
>  
>  `bootmeth`
>      Allow listing of available bootmethds and setting the order in which they
> -    are tried. See :doc:`../usage/cmd/bootmeth`
> +    are tried. See :doc:`/usage/cmd/bootmeth`
>  
>  .. _BootflowStates:
>  
> diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> index f9c4bf839ee..c0107a783fc 100644
> --- a/doc/develop/index.rst
> +++ b/doc/develop/index.rst
> @@ -29,7 +29,7 @@ Implementation
>  
>     directories
>     bloblist
> -   bootstd
> +   bootstd/index
>     ci_testing
>     commands
>     config_binding
> diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst
> index f759abab354..98a0f43c580 100644
> --- a/doc/usage/cmd/bootdev.rst
> +++ b/doc/usage/cmd/bootdev.rst
> @@ -22,7 +22,7 @@ Description
>  The `bootdev` command is used to manage bootdevs. It can list available
>  bootdevs, select one and obtain information about it.
>  
> -See :doc:`../../develop/bootstd` for more information about bootdevs in general.
> +See :doc:`/develop/bootstd/index` for more information about bootdevs in general.
>  
>  
>  bootdev list
> diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst
> index 6519e4880a9..5d41fe37a7a 100644
> --- a/doc/usage/cmd/bootflow.rst
> +++ b/doc/usage/cmd/bootflow.rst
> @@ -26,7 +26,7 @@ Description
>  The `bootflow` command is used to manage bootflows. It can scan bootdevs to
>  locate bootflows, list them and boot them.
>  
> -See :doc:`../../develop/bootstd` for more information.
> +See :doc:`/develop/bootstd/index` for more information.
>  
>  Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL) must
>  be enabled to obtain full functionality with this command. Otherwise, it only
> diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst
> index bac9fdf85cd..c3d2ec1574b 100644
> --- a/doc/usage/cmd/bootmeth.rst
> +++ b/doc/usage/cmd/bootmeth.rst
> @@ -21,7 +21,7 @@ Description
>  The `bootmeth` command is used to manage bootmeths. It can list them and change
>  the order in which they are used.
>  
> -See :doc:`../../develop/bootstd` for more information.
> +See :doc:`/develop/bootstd/index` for more information.
>  
>  
>  .. _bootmeth_order:
> diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
> index 7d4b448cb30..cc33d3ec0f2 100644
> --- a/doc/usage/environment.rst
> +++ b/doc/usage/environment.rst
> @@ -100,7 +100,7 @@ to add environment variables.
>  
>  Board maintainers are encouraged to migrate to the text-based environment as it
>  is easier to maintain. The distro-board script still requires the old-style
> -environments, so use :doc:`../develop/bootstd` instead.
> +environments, so use :doc:`/develop/bootstd/index` instead.
>  
>  
>  List of environment variables
> -- 
> 2.34.1

Re: [PATCH v2 03/14] doc: Mention automatic binding of bootmeths

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Add a note about how bootmeth drivers are instantiated.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Suggested-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> Changes in v2:
> - Add new patch to mention automatic binding of bootmeths
>
>  doc/develop/bootstd/overview.rst | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index 761f61a573b..d5051e986bb 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -419,6 +419,9 @@ Bootmeth drivers are provided for:
>     - VBE
>     - EFI boot using boot manager
>  
> +Each driver is controlled by a Kconfig option. If no bootmeth driver is
> +selected by a compatible string in the devicetree, all available bootmeth
> +drivers are bound automatically.
>  
>  Command interface
>  -----------------
> -- 
> 2.34.1

Re: [PATCH v2 04/14] doc: Add a description for bootmeth_extlinux

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the extlinux bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

Minor nitpicks below, feel free to ignore or apply.

> ---
>
> Changes in v2:
> - Adjustments from Heinrich's comments
>
>  doc/develop/bootstd/extlinux.rst | 28 ++++++++++++++++++++++++++++
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  4 ++--
>  3 files changed, 31 insertions(+), 2 deletions(-)
>  create mode 100644 doc/develop/bootstd/extlinux.rst
>
> diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst
> new file mode 100644
> index 00000000000..d87730410ee
> --- /dev/null
> +++ b/doc/develop/bootstd/extlinux.rst
> @@ -0,0 +1,28 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +Extlinux Bootmeth
> +=================
> +
> +`Extlinux <https://uapi-group.org/specifications/specs/boot_loader_specification>`_
> +(sometimes called syslinux) allows U-Boot to provide a menu of available
> +operating systems from which the user can choose.
> +
> +U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of
> +a list of named operating systems along with the kernel, initial ramdisk and
> +other settings. The file is stored in the `extlinux/` subdirectory, possibly
> +under the `boot/` subdirectory. This list of prefixes ({"/", "/boot"} by

Can the prefixes also be surrounded by `` (`{"/", "boot"`} to insist
that this is "code listing" as well ?

> +default) can be selected with the `filename-prefixes` property in the bootstd
> +device.
> +
> +Note that the PXE bootmeth 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.
> +
> +When the bootflow is booted, the bootmeth calls pxe_setup_ctx() to set up the
> +context, then pxe_process() to process the file. Depending on the contents, this

same for pxe_setup_ctx and pxe_process

> +may boot an operating system or provide a list of options to the user, perhaps
> +with a timeout.
> +
> +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/index.rst b/doc/develop/bootstd/index.rst
> index f4f87c7787c..5bbb3d633a3 100644
> --- a/doc/develop/bootstd/index.rst
> +++ b/doc/develop/bootstd/index.rst
> @@ -7,3 +7,4 @@ Standard Boot
>     :maxdepth: 2
>  
>     overview
> +   extlinux
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index d5051e986bb..7af159b9ca8 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -410,9 +410,9 @@ a good selection of boot options is available.
>  Available bootmeth drivers
>  --------------------------
>  
> -Bootmeth drivers are provided for:
> +Bootmeth drivers are provided for booting from various media:
>  
> -   - extlinux / syslinux boot from a disk
> +   - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
>     - extlinux boot from a network (PXE)
>     - U-Boot scripts from disk, network or SPI flash
>     - EFI boot using bootefi from disk
> -- 
> 2.34.1

Re: [PATCH v2 05/14] doc: Add a description for bootmeth_pxe

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the pxe bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

Nitpick: now that pxelinux.rst exist, can we link to this file in
extlinux.rst ?

> ---
>
> Changes in v2:
> - Adjustments from Heinrich's comments
>
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  2 +-
>  doc/develop/bootstd/pxelinux.rst | 27 +++++++++++++++++++++++++++
>  3 files changed, 29 insertions(+), 1 deletion(-)
>  create mode 100644 doc/develop/bootstd/pxelinux.rst
>
> diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> index 5bbb3d633a3..5052afe448f 100644
> --- a/doc/develop/bootstd/index.rst
> +++ b/doc/develop/bootstd/index.rst
> @@ -8,3 +8,4 @@ Standard Boot
>  
>     overview
>     extlinux
> +   pxelinux
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index 7af159b9ca8..b9b45f1e7a7 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -413,7 +413,7 @@ Available bootmeth drivers
>  Bootmeth drivers are provided for booting from various media:
>  
>     - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
> -   - extlinux boot from a network (PXE)
> +   - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
>     - U-Boot scripts from disk, network or SPI flash
>     - EFI boot using bootefi from disk
>     - VBE
> diff --git a/doc/develop/bootstd/pxelinux.rst b/doc/develop/bootstd/pxelinux.rst
> new file mode 100644
> index 00000000000..a4e559160ca
> --- /dev/null
> +++ b/doc/develop/bootstd/pxelinux.rst
> @@ -0,0 +1,27 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +PXE Bootmeth
> +============
> +
> +PXE (Preboot eXecution-Environment) provides a way to boot an operating system
> +over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to
> +provide a menu of possible Operating Systems from which the user can choose.
> +
> +U-Boot includes a parser for the `extlinux.conf` file described
> +`here <https://uapi-group.org/specifications/specs/boot_loader_specification>`_.
> +It consists primarily of a list of named operating systems along with the
> +kernel, initial ramdisk and other settings. The file is retrieved from a network
> +server using the TFTP protocol.
> +
> +When invoked on a bootdev, this bootmeth searches for the file and creates a
> +bootflow if found. See
> +`PXELINUX <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX>`_ for
> +a full description of the search procedure.
> +
> +When the bootflow is booted, the bootmeth calls pxe_setup_ctx() to set up the
> +context, then pxe_process() 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.
> +
> +The compatible string "u-boot,extlinux-pxe" is used for the driver. It is
> +present if `CONFIG_BOOTMETH_EXTLINUX_PXE` is enabled.
> -- 
> 2.34.1

Re: [PATCH v2 06/14] doc: Add a description for bootmeth_qfw

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the qfw bootmeth.
>
> Fix up the compatible string to drop the 'extlinux' part, which is not
> relevant to this bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
>
> Changes in v2:
> - Adjustments from Heinrich's comments
>
>  boot/bootmeth_qfw.c              |  2 +-
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  1 +
>  doc/develop/bootstd/qfw.rst      | 20 ++++++++++++++++++++
>  4 files changed, 23 insertions(+), 1 deletion(-)
>  create mode 100644 doc/develop/bootstd/qfw.rst
>
> diff --git a/boot/bootmeth_qfw.c b/boot/bootmeth_qfw.c
> index dfaa944594e..2f8e00cf350 100644
> --- a/boot/bootmeth_qfw.c
> +++ b/boot/bootmeth_qfw.c
> @@ -88,7 +88,7 @@ static struct bootmeth_ops qfw_bootmeth_ops = {
>  };
>  
>  static const struct udevice_id qfw_bootmeth_ids[] = {
> -	{ .compatible = "u-boot,qfw-extlinux" },
> +	{ .compatible = "u-boot,qfw-bootmeth" },
>  	{ }
>  };
>  
> diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> index 5052afe448f..f8fce7207ce 100644
> --- a/doc/develop/bootstd/index.rst
> +++ b/doc/develop/bootstd/index.rst
> @@ -9,3 +9,4 @@ Standard Boot
>     overview
>     extlinux
>     pxelinux
> +   qfw
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index b9b45f1e7a7..f23e344546d 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -418,6 +418,7 @@ Bootmeth drivers are provided for booting from various media:
>     - EFI boot using bootefi from disk
>     - VBE
>     - EFI boot using boot manager
> +   - :doc:`QFW <qfw>`: QEMU firmware interface
>  
>  Each driver is controlled by a Kconfig option. If no bootmeth driver is
>  selected by a compatible string in the devicetree, all available bootmeth
> diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
> new file mode 100644
> index 00000000000..b2ff1364fd8
> --- /dev/null
> +++ b/doc/develop/bootstd/qfw.rst
> @@ -0,0 +1,20 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +QFW Bootmeth
> +============
> +
> +`QEMU <hhttps://www.qemu.org/>`_ is a system emulator which is able to boot
> +Operating Systems. QEMU provides specific support for booting an OS image
> +provided on the QEMU command line.
> +
> +When invoked on a bootdev for UCLASS_QFW, this bootmeth reads the kernel
> +provided by the QEMU `-kernel` argument, the initial ramdisk and provided by

There is a "and" which should be removed here:
ramdisk and provided by -> ramdisk provided by

With that fixed:

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>


> +`-initrd` and the boot arguments (command line) provided by `-append` into
> +memory ready for booting.
> +
> +When the bootflow is booted, the bootmeth tries the `booti` command first, then
> +falls back to the `bootz` command. U-Boot's 'control' devicetree is passed
> +through to the kernel.
> +
> +The compatible string "u-boot,qfw-bootmeth" is used for the driver. It is
> +present if `CONFIG_QFW` is enabled.
> -- 
> 2.34.1

Re: [PATCH v2 07/14] doc: Add a description for bootmeth_cros

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the cros bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> Changes in v2:
> - Adjustments from Heinrich's comments
>
>  doc/develop/bootstd/cros.rst     | 33 ++++++++++++++++++++++++++++++++
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  1 +
>  3 files changed, 35 insertions(+)
>  create mode 100644 doc/develop/bootstd/cros.rst
>
> diff --git a/doc/develop/bootstd/cros.rst b/doc/develop/bootstd/cros.rst
> new file mode 100644
> index 00000000000..92b83729150
> --- /dev/null
> +++ b/doc/develop/bootstd/cros.rst
> @@ -0,0 +1,33 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +ChromiumOS Bootmeth
> +===================
> +
> +ChromiumOS provides a mechanism for booting its Operating System from a block
> +device, described
> +`here <https://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot/>`_.
> +
> +U-Boot includes support for reading the associated data structures from the
> +device and identifying a bootable ChromiumOS image. This structure includes the
> +kernel itself, boot arguments (kernel command line), as well as the x86 setup
> +block (for x86 only).
> +
> +When invoked on a bootdev, this bootmeth searches for kernel partitions with
> +the appropriate GUID (Globally Unique Identifier). When found, the information
> +is loaded and a bootflow is created.
> +
> +When the bootflow is booted, the bootmeth reads the kernel and boot arguments.
> +It then boots the kernel using zboot (on x86) or bootm (on ARM). The boot
> +arguments are adjusted to replace %U with the UUID of the selected kernel
> +partition. This results in the correct root disk being used, which is the next
> +partition after the kernel partition.
> +
> +For ARM, a :doc:`/usage/fit/index` is used. The `CONFIG_FIT_BEST_MATCH` option
> +must be enabled for U-Boot to select the correct devicetree to boot with.
> +
> +Note that a ChromiumOS image typically has two copies of the Operating System,
> +each with its own kernel and root disk. There is no initial ramdisk (initrd).
> +This means that this bootmeth typically locates two separate images.
> +
> +The compatible string "u-boot,cros" is used for the driver. It is present
> +if `CONFIG_BOOTMETH_CROS` is enabled.
> diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> index f8fce7207ce..69fd3c2d2eb 100644
> --- a/doc/develop/bootstd/index.rst
> +++ b/doc/develop/bootstd/index.rst
> @@ -10,3 +10,4 @@ Standard Boot
>     extlinux
>     pxelinux
>     qfw
> +   cros
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index f23e344546d..9b50b5593c4 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -417,6 +417,7 @@ Bootmeth drivers are provided for booting from various media:
>     - U-Boot scripts from disk, network or SPI flash
>     - EFI boot using bootefi from disk
>     - VBE
> +   - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
>     - EFI boot using boot manager
>     - :doc:`QFW <qfw>`: QEMU firmware interface
>  
> -- 
> 2.34.1

Re: [PATCH v2 08/14] doc: Add a description for bootmeth_sandbox

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the sandbox bootmeth.
>
> Fix up the compatible string to drop the 'extlinux' part, which is not
> relevant to this bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> Changes in v2:
> - Adjustments from Heinrich's comments
>
>  boot/bootmeth_sandbox.c          |  2 +-
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  1 +
>  doc/develop/bootstd/sandbox.rst  | 17 +++++++++++++++++
>  4 files changed, 20 insertions(+), 1 deletion(-)
>  create mode 100644 doc/develop/bootstd/sandbox.rst
>
> diff --git a/boot/bootmeth_sandbox.c b/boot/bootmeth_sandbox.c
> index 0bc8f688e30..26c713bb5f3 100644
> --- a/boot/bootmeth_sandbox.c
> +++ b/boot/bootmeth_sandbox.c
> @@ -55,7 +55,7 @@ static struct bootmeth_ops sandbox_bootmeth_ops = {
>  };
>  
>  static const struct udevice_id sandbox_bootmeth_ids[] = {
> -	{ .compatible = "u-boot,sandbox-extlinux" },
> +	{ .compatible = "u-boot,sandbox-bootmeth" },
>  	{ }
>  };
>  
> diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> index 69fd3c2d2eb..2c5d2d3fade 100644
> --- a/doc/develop/bootstd/index.rst
> +++ b/doc/develop/bootstd/index.rst
> @@ -11,3 +11,4 @@ Standard Boot
>     pxelinux
>     qfw
>     cros
> +   sandbox
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index 9b50b5593c4..add054f3088 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -420,6 +420,7 @@ Bootmeth drivers are provided for booting from various media:
>     - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
>     - EFI boot using boot manager
>     - :doc:`QFW <qfw>`: QEMU firmware interface
> +   - :doc:`sandbox <sandbox>` used only for testing
>  
>  Each driver is controlled by a Kconfig option. If no bootmeth driver is
>  selected by a compatible string in the devicetree, all available bootmeth
> diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst
> new file mode 100644
> index 00000000000..a90c1accc84
> --- /dev/null
> +++ b/doc/develop/bootstd/sandbox.rst
> @@ -0,0 +1,17 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +Sandbox Bootmeth
> +================
> +
> +The sandbox bootmeth is only used for testing. It does not provide any facility
> +for booting an OS. While sandbox can do all the processing before the actual
> +boot, it is not connected in this bootmeth.
> +
> +When invoked on a bootdev, this bootmeth pretends to find a bootflow and creates
> +the associated structure.
> +
> +When the bootflow is booted, the bootmeth returns -EENOTSUPP indicating that it
> +is not supported.
> +
> +The compatible string "u-boot,sandbox-bootmeth" is used for the driver. It is present
> +if `CONFIG_BOOTMETH_SANDBOX` is enabled.
> -- 
> 2.34.1

Re: [PATCH v2 09/14] bootstd: Tidy up comments on the boothmeth drivers

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Fix a typo in the comment and add one to the EFI driver too.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> (no changes since v1)
>
>  boot/bootmeth_efi.c      | 1 +
>  boot/bootmeth_extlinux.c | 2 +-
>  boot/bootmeth_script.c   | 2 +-
>  3 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/boot/bootmeth_efi.c b/boot/bootmeth_efi.c
> index 5a4c125835a..56a6e47f5b2 100644
> --- a/boot/bootmeth_efi.c
> +++ b/boot/bootmeth_efi.c
> @@ -394,6 +394,7 @@ static const struct udevice_id distro_efi_bootmeth_ids[] = {
>  	{ }
>  };
>  
> +/* Put a number before 'efi' to provide a default ordering */
>  U_BOOT_DRIVER(bootmeth_4efi) = {
>  	.name		= "bootmeth_efi",
>  	.id		= UCLASS_BOOTMETH,
> diff --git a/boot/bootmeth_extlinux.c b/boot/bootmeth_extlinux.c
> index 9b55686948f..fbb05ef928e 100644
> --- a/boot/bootmeth_extlinux.c
> +++ b/boot/bootmeth_extlinux.c
> @@ -183,7 +183,7 @@ static const struct udevice_id extlinux_bootmeth_ids[] = {
>  	{ }
>  };
>  
> -/* Put an number before 'extlinux' to provide a default ordering */
> +/* Put a number before 'extlinux' to provide a default ordering */
>  U_BOOT_DRIVER(bootmeth_1extlinux) = {
>  	.name		= "bootmeth_extlinux",
>  	.id		= UCLASS_BOOTMETH,
> diff --git a/boot/bootmeth_script.c b/boot/bootmeth_script.c
> index 0e05d28d4d9..24da47c7259 100644
> --- a/boot/bootmeth_script.c
> +++ b/boot/bootmeth_script.c
> @@ -250,7 +250,7 @@ static const struct udevice_id script_bootmeth_ids[] = {
>  	{ }
>  };
>  
> -/* Put an number before 'script' to provide a default ordering */
> +/* Put a number before 'script' to provide a default ordering */
>  U_BOOT_DRIVER(bootmeth_2script) = {
>  	.name		= "bootmeth_script",
>  	.id		= UCLASS_BOOTMETH,
> -- 
> 2.34.1

Re: [PATCH v2 10/14] bootstd: Correct handling of script from network

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> When reading a script from a network, no block device is available.
> Update the implementation to support this correctly, avoiding setting
> environment variables which relate only to block devices.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> (no changes since v1)
>
>  boot/bootmeth_script.c | 51 +++++++++++++++++++++++++-----------------
>  1 file changed, 31 insertions(+), 20 deletions(-)
>
> diff --git a/boot/bootmeth_script.c b/boot/bootmeth_script.c
> index 24da47c7259..c5cbf18c2e6 100644
> --- a/boot/bootmeth_script.c
> +++ b/boot/bootmeth_script.c
> @@ -185,31 +185,42 @@ static int script_set_bootflow(struct udevice *dev, struct bootflow *bflow,
>  
>  static int script_boot(struct udevice *dev, struct bootflow *bflow)
>  {
> -	struct blk_desc *desc = dev_get_uclass_plat(bflow->blk);
> +	struct blk_desc *desc;
>  	ulong addr;
>  	int ret = 0;
>  
> -	if (desc->uclass_id == UCLASS_USB) {
> -		ret = env_set("devtype", "usb");
> +	if (bflow->blk) {
> +		desc = dev_get_uclass_plat(bflow->blk);
> +		if (desc->uclass_id == UCLASS_USB) {
> +			ret = env_set("devtype", "usb");
> +		} else {
> +			/*
> +			 * If the uclass is AHCI, but the driver is ATA
> +			 * (not scsi), set devtype to sata
> +			 */
> +			if (IS_ENABLED(CONFIG_SATA) &&
> +			    desc->uclass_id == UCLASS_AHCI)
> +				ret = env_set("devtype", "sata");
> +			else
> +				ret = env_set("devtype", blk_get_devtype(bflow->blk));
> +		}
> +		if (!ret)
> +			ret = env_set_hex("devnum", desc->devnum);
> +		if (!ret)
> +			ret = env_set_hex("distro_bootpart", bflow->part);
> +		if (!ret)
> +			ret = env_set("prefix", bflow->subdir);
> +		if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) &&
> +		    !strcmp("mmc", blk_get_devtype(bflow->blk)))
> +			ret = env_set_hex("mmc_bootdev", desc->devnum);
>  	} else {
> -		/* If the uclass is AHCI, but the driver is ATA
> -		 * (not scsi), set devtype to sata
> -		 */
> -		if (IS_ENABLED(CONFIG_SATA) &&
> -		    desc->uclass_id == UCLASS_AHCI)
> -			ret = env_set("devtype", "sata");
> -		else
> -			ret = env_set("devtype", blk_get_devtype(bflow->blk));
> +		const struct udevice *media = dev_get_parent(bflow->dev);
> +
> +		ret = env_set("devtype",
> +			      uclass_get_name(device_get_uclass_id(media)));
> +		if (!ret)
> +			ret = env_set_hex("devnum", dev_seq(media));
>  	}
> -	if (!ret)
> -		ret = env_set_hex("devnum", desc->devnum);
> -	if (!ret)
> -		ret = env_set_hex("distro_bootpart", bflow->part);
> -	if (!ret)
> -		ret = env_set("prefix", bflow->subdir);
> -	if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) &&
> -	    !strcmp("mmc", blk_get_devtype(bflow->blk)))
> -		ret = env_set_hex("mmc_bootdev", desc->devnum);
>  	if (ret)
>  		return log_msg_ret("env", ret);
>  
> -- 
> 2.34.1

Re: [PATCH v2 11/14] doc: Add a description for bootmeth_script

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the script bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> Changes in v2:
> - Adjustments from Heinrich's comments
>
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  2 +-
>  doc/develop/bootstd/script.rst   | 52 ++++++++++++++++++++++++++++++++
>  3 files changed, 54 insertions(+), 1 deletion(-)
>  create mode 100644 doc/develop/bootstd/script.rst
>
> diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> index 2c5d2d3fade..9d35b567d55 100644
> --- a/doc/develop/bootstd/index.rst
> +++ b/doc/develop/bootstd/index.rst
> @@ -11,4 +11,5 @@ Standard Boot
>     pxelinux
>     qfw
>     cros
> +   script
>     sandbox
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index add054f3088..e4924b55ae7 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -414,7 +414,7 @@ Bootmeth drivers are provided for booting from various media:
>  
>     - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
>     - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
> -   - U-Boot scripts from disk, network or SPI flash
> +   - :doc:`U-Boot scripts <script>` from disk, network or SPI flash
>     - EFI boot using bootefi from disk
>     - VBE
>     - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
> diff --git a/doc/develop/bootstd/script.rst b/doc/develop/bootstd/script.rst
> new file mode 100644
> index 00000000000..58ddc1cae1d
> --- /dev/null
> +++ b/doc/develop/bootstd/script.rst
> @@ -0,0 +1,52 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +Script Bootmeth
> +===============
> +
> +This bootmeth provides a way to locate and run a script on a block or network
> +device. It can also support SPI flash.
> +
> +For a block device the file is read from the selected partition, which must use
> +a supported filesystem. The subdirectory to search in is defined by the bootstd
> +list of prefixes ({"/", "/boot"} by default) and can be adjust with the
> +`filename-prefixes` property in the bootstd device.
> +
> +For a network device, the filename is obtained from the `boot_script_dhcp`
> +environment variable and the file is read using tftp. It must be in the
> +top-level directory of the tftp server.
> +
> +In either case (file or network), the bootmeth searches for the file and creates
> +a bootflow if found. The bootmeth searches for "boot.scr.uimg" first, then
> +"boot.scr" if not found.
> +
> +For SPI flash, a script is read from flash using the offset provided by the
> +"script_offset_f" environment variable.
> +
> +Some attempt is made to identify the Operating System: so far this only detects
> +an `Armbian <https://www.armbian.com>`_
> +distro. For block devices, if a file called "boot.bmp" exists in the same
> +directory then it is used as the bootflow logo.
> +
> +When the bootflow is booted, the bootmeth sets these environment variables:
> +
> +    devtype
> +        device type (e.g. "usb", "mmc", "ethernet" or "spi_flash")
> +
> +    devnum
> +        device number, corresponding to the device 'sequence' number
> +        `dev_seq(dev)`
> +
> +    distro_bootpart
> +        (block devices only) partition number on the device (numbered from 1)
> +
> +    prefix
> +        prefix used to find the file
> +
> +    mmc_bootdev
> +        device number (same as `devnum`), set for sunxi mmc devices only
> +
> +The script file must be a FIT or a legacy uImage. It is loaded into memory and
> +executed.
> +
> +The compatible string "u-boot,script" is used for the driver. It is present
> +if `CONFIG_BOOTMETH_SCRIPT` is enabled.
> -- 
> 2.34.1

Re: [PATCH v2 12/14] doc: Add a link to VBE from the bootstd docs

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Link to this page to make it easier to find the VBE docs.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> (no changes since v1)
>
>  doc/develop/bootstd/overview.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index e4924b55ae7..4a55b7da00a 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -416,7 +416,7 @@ Bootmeth drivers are provided for booting from various media:
>     - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
>     - :doc:`U-Boot scripts <script>` from disk, network or SPI flash
>     - EFI boot using bootefi from disk
> -   - VBE
> +   - :doc:`VBE </develop/vbe>`: Verified Boot for Embedded
>     - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
>     - EFI boot using boot manager
>     - :doc:`QFW <qfw>`: QEMU firmware interface
> -- 
> 2.34.1

Re: [PATCH v2 13/14] boot: Correct indentation in efi bootmeth

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> Fix a minor indentation / whitespace problem in a comment.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Heinrich Schuchardt <xypron.glkp@gmx.de>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> (no changes since v1)
>
>  boot/bootmeth_efi.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/boot/bootmeth_efi.c b/boot/bootmeth_efi.c
> index 56a6e47f5b2..39232eb2e25 100644
> --- a/boot/bootmeth_efi.c
> +++ b/boot/bootmeth_efi.c
> @@ -265,7 +265,7 @@ static int distro_efi_read_bootflow_net(struct bootflow *bflow)
>  		return log_msg_ret("sz", -EINVAL);
>  	bflow->size = size;
>  
> -    /* bootfile should be setup by dhcp*/
> +	/* bootfile should be setup by dhcp */
>  	bootfile_name = env_get("bootfile");
>  	if (!bootfile_name)
>  		return log_msg_ret("bootfile_name", ret);
> -- 
> 2.34.1

Re: [PATCH v2 14/14] doc: Describe the bootstd settings

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On mar., juil. 16, 2024 at 08:04, Simon Glass <sjg@chromium.org> wrote:

> The bootstd node provides some configuration properties. Add these to
> the documentation.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
> (no changes since v1)
>
>  doc/develop/bootstd/overview.rst | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
>
> diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> index 4a55b7da00a..d92a649beb0 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -406,6 +406,19 @@ You should probably also enable `CONFIG_BOOTSTD_DEFAULTS`, which provides
>  several filesystem and network features (if `CONFIG_NET` is enabled) so that
>  a good selection of boot options is available.
>  
> +Some devicetree properties are supported in the bootstd node when
> +`CONFIG_BOOTSTD_FULL` is enabled:
> +
> +    filename-prefixes
> +        List of prefixes to use when searching for files on block devices. This
> +        defaults to {"/", "/boot/"} if not provided.
> +
> +    bootdev-order
> +        Lists the bootdev ordering to use. Note that the deprecated
> +        `boot_targets` environment variable overrides this, if present.
> +
> +    theme (subnode)
> +        Sets the theme to use for menus. See :doc:`/develop/expo`.
>  
>  Available bootmeth drivers
>  --------------------------
> -- 
> 2.34.1