[PATCH 00/13] doc: Add documentation for bootmeths

[PATCH 00/13] 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.


Simon Glass (13):
  MAINTAINERS: Rename BOOTDEVICE
  doc: Move bootstd into its own directory
  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              | 27 ++++++++++
 doc/develop/bootstd/index.rst                 | 15 ++++++
 .../{bootstd.rst => bootstd/overview.rst}     | 38 +++++++++----
 doc/develop/bootstd/pxelinux.rst              | 27 ++++++++++
 doc/develop/bootstd/qfw.rst                   | 21 ++++++++
 doc/develop/bootstd/sandbox.rst               | 18 +++++++
 doc/develop/bootstd/script.rst                | 49 +++++++++++++++++
 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, 263 insertions(+), 45 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} (96%)
 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 01/13] 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>
---

 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 02/13] 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>
---

 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 03/13] doc: Add a description for bootmeth_extlinux

[Simon Glass]

Add documentation for the extlinux bootmeth.

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

 doc/develop/bootstd/extlinux.rst | 27 +++++++++++++++++++++++++++
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  2 +-
 3 files changed, 29 insertions(+), 1 deletion(-)
 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..28490f38899
--- /dev/null
+++ b/doc/develop/bootstd/extlinux.rst
@@ -0,0 +1,27 @@
+.. 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 possible
+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 OSes 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 PXE (Preboot eXecution-Environment) 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 OS or provide a list of options to the user, perhaps with a timeout.
+
+The compatible string "u-boot,extlinux" is used for the driver. The driver is
+automatically instantiated if there are no bootmeth drivers in the devicetree.
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 761f61a573b..086a0b1281d 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -412,7 +412,7 @@ Available bootmeth drivers
 
 Bootmeth drivers are provided for:
 
-   - extlinux / syslinux boot from a disk
+   - :doc:`extlinux / syslinux <extlinux>` boot from a disk
    - 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 04/13] doc: Add a description for bootmeth_pxe

[Simon Glass]

Add documentation for the pxe bootmeth.

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

 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 086a0b1281d..fd0692daf0d 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:
 
    - :doc:`extlinux / syslinux <extlinux>` boot from a disk
-   - 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..08ba67e09c5
--- /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 OSes along with the kernel, initial
+ramdisk and other settings. The file is retrieved from a network server using
+tftpboot.
+
+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 OS 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. The driver
+is automatically instantiated if there are no bootmeth drivers in the
+devicetree.
-- 
2.34.1

[PATCH 05/13] 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>
---

 boot/bootmeth_qfw.c              |  2 +-
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  1 +
 doc/develop/bootstd/qfw.rst      | 21 +++++++++++++++++++++
 4 files changed, 24 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 fd0692daf0d..bcc2c00c775 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -418,6 +418,7 @@ Bootmeth drivers are provided for:
    - EFI boot using bootefi from disk
    - VBE
    - EFI boot using boot manager
+   - :doc:`QFW <qfw>`: QEMU firmware interface
 
 
 Command interface
diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
new file mode 100644
index 00000000000..b0d47fd246a
--- /dev/null
+++ b/doc/develop/bootstd/qfw.rst
@@ -0,0 +1,21 @@
+.. 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 iniital 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. The driver
+is automatically instantiated if there are no bootmeth drivers in the
+devicetree.
-- 
2.34.1

[PATCH 06/13] doc: Add a description for bootmeth_cros

[Simon Glass]

Add documentation for the cros bootmeth.

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

 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..96f148837ac
--- /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 OS, 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. The driver is
+automatically instantiated if there are no bootmeth drivers in the devicetree.
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 bcc2c00c775..f12e93236a7 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -417,6 +417,7 @@ Bootmeth drivers are provided for:
    - 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 07/13] 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>
---

 boot/bootmeth_sandbox.c          |  2 +-
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  1 +
 doc/develop/bootstd/sandbox.rst  | 18 ++++++++++++++++++
 4 files changed, 21 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 f12e93236a7..58acaa4d3ce 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -420,6 +420,7 @@ Bootmeth drivers are provided for:
    - :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
 
 
 Command interface
diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst
new file mode 100644
index 00000000000..508f0fd5baa
--- /dev/null
+++ b/doc/develop/bootstd/sandbox.rst
@@ -0,0 +1,18 @@
+.. 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. The
+driver is automatically instantiated if there are no bootmeth drivers in the
+devicetree.
-- 
2.34.1

[PATCH 08/13] 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>
---

 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 09/13] 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>
---

 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 10/13] doc: Add a description for bootmeth_script

[Simon Glass]

Add documentation for the script bootmeth.

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

 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  2 +-
 doc/develop/bootstd/script.rst   | 49 ++++++++++++++++++++++++++++++++
 3 files changed, 51 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 58acaa4d3ce..7d31d5e6427 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -414,7 +414,7 @@ Bootmeth drivers are provided for:
 
    - :doc:`extlinux / syslinux <extlinux>` boot from a disk
    - :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..8127e21ec1d
--- /dev/null
+++ b/doc/develop/bootstd/script.rst
@@ -0,0 +1,49 @@
+.. 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 OS: 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.
-- 
2.34.1

[PATCH 11/13] 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>
---

 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 7d31d5e6427..0d7454246f6 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -416,7 +416,7 @@ Bootmeth drivers are provided for:
    - :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 12/13] 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>
---

 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 13/13] 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>
---

 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 0d7454246f6..f3caf8b7956 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 01/13] MAINTAINERS: Rename BOOTDEVICE

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass 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>

Thanks!
Quentin

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

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass 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>

Thanks!
Quentin

Re: [PATCH 03/13] doc: Add a description for bootmeth_extlinux

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass wrote:
> Add documentation for the extlinux bootmeth.
> 
> Signed-off-by: Simon Glass <sjg@chromium.org>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 04/13] doc: Add a description for bootmeth_pxe

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass wrote:
> Add documentation for the pxe bootmeth.
> 
> Signed-off-by: Simon Glass <sjg@chromium.org>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 05/13] doc: Add a description for bootmeth_qfw

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass 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>

Thanks!
Quentin

Re: [PATCH 06/13] doc: Add a description for bootmeth_cros

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass wrote:
> Add documentation for the cros bootmeth.
> 
> Signed-off-by: Simon Glass <sjg@chromium.org>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 07/13] doc: Add a description for bootmeth_sandbox

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass 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>

Thanks!
Quentin

Re: [PATCH 08/13] bootstd: Tidy up comments on the boothmeth drivers

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass 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: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 10/13] doc: Add a description for bootmeth_script

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass wrote:
> Add documentation for the script bootmeth.
> 
> Signed-off-by: Simon Glass <sjg@chromium.org>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 11/13] doc: Add a link to VBE from the bootstd docs

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass wrote:
> Link to this page to make it easier to find the VBE docs.
> 
> Signed-off-by: Simon Glass <sjg@chromium.org>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

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

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass wrote:
> Fix a minor indentation / whitespace problem in a comment.
> 
> Signed-off-by: Simon Glass <sjg@chromium.org>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 13/13] doc: Describe the bootstd settings

[Quentin Schulz]

Hi Simon,

On 7/15/24 12:13 PM, Simon Glass 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>

Thanks!
Quentin

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

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass wrote:
> Before adding more files, move the bootstd docs into a new directory,
> with an index.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
>   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
> +======================
>



The text is not optimized for readability, e.g.

"- bootdev  - a device which can hold or access a distro (e.g. MMC,
Ethernet)"

Please, consistently replace the non-words in the boot standard
documentation:

%s/bootdev/boot device/
%s/bootmeth/boot method/
%s/bootflow/boot flow/

"distro" isn't a dictionary word either. Do you mean operating system?
That term would still not catch what a boot device is:

The boot device is the device that holds the next boot stage.

This could for instance be GRUB which in turn will offer a menu allowing
to select one of multiple operating systems.

Or that next boot stage could be an operating system kernel together
with its initial ram disk and a device-tree.

Best regards

Heinrich



>   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

Re: [PATCH 03/13] doc: Add a description for bootmeth_extlinux

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass wrote:
> Add documentation for the extlinux bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
>   doc/develop/bootstd/extlinux.rst | 27 +++++++++++++++++++++++++++
>   doc/develop/bootstd/index.rst    |  1 +
>   doc/develop/bootstd/overview.rst |  2 +-
>   3 files changed, 29 insertions(+), 1 deletion(-)
>   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..28490f38899
> --- /dev/null
> +++ b/doc/develop/bootstd/extlinux.rst
> @@ -0,0 +1,27 @@
> +.. 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 possible

%s/possible/available/

> +Operating Systems from which the user can choose.

%s/Operating Systems/operating systems/

> +
> +U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of
> +a list of named OSes along with the kernel, initial ramdisk and other settings.

Please, avoid abbreviations.

%s/OSes/operating systems/

> +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.

%s/bootstd/boot standard/

> +
> +Note that PXE (Preboot eXecution-Environment) uses the same file format, but in
> +a network context.
> +
> +When invoked on a bootdev, this bootmeth searches for the file and creates a

Please, replace throughout the text:

%s/bootdev/boot device/
%s/bootmeth/boot method/


> +bootflow if found.

%s/bootflow/bootflow/

> +
> +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 OS or provide a list of options to the user, perhaps with a timeout.

%/OS/operating system/

> +
> +The compatible string "u-boot,extlinux" is used for the driver. The driver is
> +automatically instantiated if there are no bootmeth drivers in the devicetree.

Device-tree never contain boot method drivers. Do you mean:

If no boot method driver is selected by a compatible string in the
device-tree and CONFIG_BOOTMETH_EXTLINUX=y, the extlinux boot method
driver is enabled by default.

Please, mention that the driver is only available if
CONFIG_BOOTMETH_EXTLINUX=y.

> 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 761f61a573b..086a0b1281d 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -412,7 +412,7 @@ Available bootmeth drivers
>
>   Bootmeth drivers are provided for:

%s/Bootmeth/Boot method/

>
> -   - extlinux / syslinux boot from a disk
 > +   - :doc:`extlinux / syslinux <extlinux>` boot from a disk

After "provided for:" I would expect "booting from a storage device".

You can't use the infinitive here. The days of disks are counted.

Best regards

Heinrich

>      - extlinux boot from a network (PXE)
>      - U-Boot scripts from disk, network or SPI flash
>      - EFI boot using bootefi from disk

Re: [PATCH 04/13] doc: Add a description for bootmeth_pxe

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass wrote:
> Add documentation for the pxe bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
>   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 086a0b1281d..fd0692daf0d 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:
>
>      - :doc:`extlinux / syslinux <extlinux>` boot from a disk
> -   - 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..08ba67e09c5
> --- /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

%s/Operating System/operating system/

> +over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to

%s/bootmeth/boot method/

> +provide a menu of possible Operating Systems from which the user can choose.

PXELINUX is a binary. Does U-Boot really provide a menu when the
PXELINUX binary is downloaded and executed?

> +
> +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 OSes along with the kernel, initial
> +ramdisk and other settings. The file is retrieved from a network server using
> +tftpboot.

Does this paragraph relate to PXELINUX?

tftpboot is a command and not a protocol. Shouldn't boot methods work
when the command line interface is disabled? I guess you want to replace

%s/tftpboot/the TFTP protocol/

> +
> +When invoked on a bootdev, this bootmeth searches for the file and creates a

%s/bootdev/boot device/
%s/bootmeth/boot method/

> +bootflow if found. See

%s/bootflow/boot flow/

> +`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 OS 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. The driver
> +is automatically instantiated if there are no bootmeth drivers in the
> +devicetree.

Device-trees contain compatible strings for drivers, not the drivers
themselves.

If every configured boot method is enabled if there is no compatible
string for boot methods in the device-tree, why don't we mention this in
the overview instead of repeating ourselves?

Please, mention the relevant configuration option.

Best regards

Heinrich

Re: [PATCH 05/13] doc: Add a description for bootmeth_qfw

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass wrote:
> Add documentation for the qfw bootmeth.
>

%s/bootmeth/boot method/


> 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>
> ---
>
>   boot/bootmeth_qfw.c              |  2 +-
>   doc/develop/bootstd/index.rst    |  1 +
>   doc/develop/bootstd/overview.rst |  1 +
>   doc/develop/bootstd/qfw.rst      | 21 +++++++++++++++++++++
>   4 files changed, 24 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 fd0692daf0d..bcc2c00c775 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -418,6 +418,7 @@ Bootmeth drivers are provided for:
>      - EFI boot using bootefi from disk
>      - VBE
>      - EFI boot using boot manager
> +   - :doc:`QFW <qfw>`: QEMU firmware interface
>
>
>   Command interface
> diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
> new file mode 100644
> index 00000000000..b0d47fd246a
> --- /dev/null
> +++ b/doc/develop/bootstd/qfw.rst
> @@ -0,0 +1,21 @@
> +.. 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 iniital ramdisk and provided by

%s/iniital/initial/

> +`-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

Boot methods should work if the command line is deactivated. We should
not use run_command() but extract the functionality into library code.

Why would you first try to run booti and then bootz irrespective of the
availability of the commands? Function qfw_boot() needs rework.

There should be a configuration symbol to disable the boot method when
CONFIG_QFW is enabled.

The bootmethod should no be built if booti and bootz are not available

> +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. The driver
> +is automatically instantiated if there are no bootmeth drivers in the
> +devicetree.

This paragraph should be moved to the overview.

Please, mention the configuration requirements.

Best regards

Heinrich

Re: [PATCH 06/13] doc: Add a description for bootmeth_cros

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass wrote:
> Add documentation for the cros bootmeth.

%s/bootmeth/boot method/

throughout the patch.

>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
>   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..96f148837ac
> --- /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

What does 'invoked on a boot device' mean? Do you mean "if ChromimumOS
selects a boot device"?

> +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 OS, each with its

%s/OS/operating system/

> +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. The driver is
> +automatically instantiated if there are no bootmeth drivers in the devicetree.

The last sentence should be moved to the overview.

Please, mention the relevant configuration option for the boot method
driver.

Best regards

Heinrich


> 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 bcc2c00c775..f12e93236a7 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -417,6 +417,7 @@ Bootmeth drivers are provided for:
>      - 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
>

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

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass 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>

> ---
>
>   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);

Re: [PATCH 11/13] doc: Add a link to VBE from the bootstd docs

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass wrote:
> Link to this page to make it easier to find the VBE docs.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
>   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 7d31d5e6427..0d7454246f6 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -416,7 +416,7 @@ Bootmeth drivers are provided for:
>      - :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

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Re: [PATCH 08/13] bootstd: Tidy up comments on the boothmeth drivers

[Heinrich Schuchardt]

On 7/15/24 12:13, Simon Glass 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>

> ---
>
>   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,

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

[Simon Glass]

Hi Heinrich,

On Mon, 15 Jul 2024 at 22:58, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> On 7/15/24 12:13, Simon Glass wrote:
> > Before adding more files, move the bootstd docs into a new directory,
> > with an index.
> >
> > Signed-off-by: Simon Glass <sjg@chromium.org>
> > ---
> >
> >   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
> > +======================
> >
>
>
>
> The text is not optimized for readability, e.g.
>
> "- bootdev  - a device which can hold or access a distro (e.g. MMC,
> Ethernet)"
>
> Please, consistently replace the non-words in the boot standard
> documentation:
>
> %s/bootdev/boot device/
> %s/bootmeth/boot method/
> %s/bootflow/boot flow/

I do want to keep the terms, It is easy to search for bootdev or
bootmeth in the code and docs. Once people learn what they mean it is
pretty simple.

>
> "distro" isn't a dictionary word either. Do you mean operating system?

I mean a linux distro, in the sense that 'distro boot' uses it.

> That term would still not catch what a boot device is:
>
> The boot device is the device that holds the next boot stage.
>
> This could for instance be GRUB which in turn will offer a menu allowing
> to select one of multiple operating systems.
>
> Or that next boot stage could be an operating system kernel together
> with its initial ram disk and a device-tree.

This is covered to some extent at [1].  But what you are talking about
here is not covered - e.g. using GRUB. You could perhaps sent a patch
to [1] ?

>
> Best regards
>
> Heinrich
>
>
>
> >   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
>

[1] https://docs.u-boot.org/en/latest/develop/bootstd.html#bootdev

Re: [PATCH 03/13] doc: Add a description for bootmeth_extlinux

[Simon Glass]

Hi Heinrich,

On Mon, 15 Jul 2024 at 23:30, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> On 7/15/24 12:13, Simon Glass wrote:
> > Add documentation for the extlinux bootmeth.
> >
> > Signed-off-by: Simon Glass <sjg@chromium.org>
> > ---
> >
> >   doc/develop/bootstd/extlinux.rst | 27 +++++++++++++++++++++++++++
> >   doc/develop/bootstd/index.rst    |  1 +
> >   doc/develop/bootstd/overview.rst |  2 +-
> >   3 files changed, 29 insertions(+), 1 deletion(-)
> >   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..28490f38899
> > --- /dev/null
> > +++ b/doc/develop/bootstd/extlinux.rst
> > @@ -0,0 +1,27 @@
> > +.. 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 possible
>
> %s/possible/available/
>
> > +Operating Systems from which the user can choose.
>
> %s/Operating Systems/operating systems/
>
> > +
> > +U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of
> > +a list of named OSes along with the kernel, initial ramdisk and other settings.
>
> Please, avoid abbreviations.
>
> %s/OSes/operating systems/
>
> > +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.
>
> %s/bootstd/boot standard/
>
> > +
> > +Note that PXE (Preboot eXecution-Environment) uses the same file format, but in
> > +a network context.
> > +
> > +When invoked on a bootdev, this bootmeth searches for the file and creates a
>
> Please, replace throughout the text:
>
> %s/bootdev/boot device/
> %s/bootmeth/boot method/
>
>
> > +bootflow if found.
>
> %s/bootflow/bootflow/
>
> > +
> > +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 OS or provide a list of options to the user, perhaps with a timeout.
>
> %/OS/operating system/
>
> > +
> > +The compatible string "u-boot,extlinux" is used for the driver. The driver is
> > +automatically instantiated if there are no bootmeth drivers in the devicetree.
>
> Device-tree never contain boot method drivers. Do you mean:
>
> If no boot method driver is selected by a compatible string in the
> device-tree and CONFIG_BOOTMETH_EXTLINUX=y, the extlinux boot method
> driver is enabled by default.

Not quite. The devicetree can specify the bootmeth devices, iwc the
automatic binding is not enabled. I'll add a note to the main docs and
drop this.

>
> Please, mention that the driver is only available if
> CONFIG_BOOTMETH_EXTLINUX=y.
>
> > 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 761f61a573b..086a0b1281d 100644
> > --- a/doc/develop/bootstd/overview.rst
> > +++ b/doc/develop/bootstd/overview.rst
> > @@ -412,7 +412,7 @@ Available bootmeth drivers
> >
> >   Bootmeth drivers are provided for:
>
> %s/Bootmeth/Boot method/
>
> >
> > -   - extlinux / syslinux boot from a disk
>  > +   - :doc:`extlinux / syslinux <extlinux>` boot from a disk
>
> After "provided for:" I would expect "booting from a storage device".
>
> You can't use the infinitive here. The days of disks are counted.
>
> Best regards
>
> Heinrich
>
> >      - extlinux boot from a network (PXE)
> >      - U-Boot scripts from disk, network or SPI flash
> >      - EFI boot using bootefi from disk
>

Regards,
Simon

Re: [PATCH 04/13] doc: Add a description for bootmeth_pxe

[Simon Glass]

Hi Heinrich,

On Mon, 15 Jul 2024 at 23:47, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> On 7/15/24 12:13, Simon Glass wrote:
> > Add documentation for the pxe bootmeth.
> >
> > Signed-off-by: Simon Glass <sjg@chromium.org>
> > ---
> >
> >   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 086a0b1281d..fd0692daf0d 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:
> >
> >      - :doc:`extlinux / syslinux <extlinux>` boot from a disk
> > -   - 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..08ba67e09c5
> > --- /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
>
> %s/Operating System/operating system/
>
> > +over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to
>
> %s/bootmeth/boot method/
>
> > +provide a menu of possible Operating Systems from which the user can choose.
>
> PXELINUX is a binary. Does U-Boot really provide a menu when the
> PXELINUX binary is downloaded and executed?

It downloads a config file which is what includes information about
the menu. I think I was a bit unclear about this when I wrote this
doc.

>
> > +
> > +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 OSes along with the kernel, initial
> > +ramdisk and other settings. The file is retrieved from a network server using
> > +tftpboot.
>
> Does this paragraph relate to PXELINUX?
>
> tftpboot is a command and not a protocol. Shouldn't boot methods work
> when the command line interface is disabled? I guess you want to replace
>
> %s/tftpboot/the TFTP protocol/
>
> > +
> > +When invoked on a bootdev, this bootmeth searches for the file and creates a
>
> %s/bootdev/boot device/
> %s/bootmeth/boot method/
>
> > +bootflow if found. See
>
> %s/bootflow/boot flow/
>
> > +`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 OS 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. The driver
> > +is automatically instantiated if there are no bootmeth drivers in the
> > +devicetree.
>
> Device-trees contain compatible strings for drivers, not the drivers
> themselves.
>
> If every configured boot method is enabled if there is no compatible
> string for boot methods in the device-tree, why don't we mention this in
> the overview instead of repeating ourselves?

OK done

>
> Please, mention the relevant configuration option.

Regards,
Simon

Re: [PATCH 01/13] MAINTAINERS: Rename BOOTDEVICE

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On lun., juil. 15, 2024 at 11:13, 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: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
>  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 05/13] doc: Add a description for bootmeth_qfw

[Simon Glass]

Hi Heinrich,

On Mon, 15 Jul 2024 at 23:56, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> On 7/15/24 12:13, Simon Glass wrote:
> > Add documentation for the qfw bootmeth.
> >
>
> %s/bootmeth/boot method/
>
>
> > 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>
> > ---
> >
> >   boot/bootmeth_qfw.c              |  2 +-
> >   doc/develop/bootstd/index.rst    |  1 +
> >   doc/develop/bootstd/overview.rst |  1 +
> >   doc/develop/bootstd/qfw.rst      | 21 +++++++++++++++++++++
> >   4 files changed, 24 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 fd0692daf0d..bcc2c00c775 100644
> > --- a/doc/develop/bootstd/overview.rst
> > +++ b/doc/develop/bootstd/overview.rst
> > @@ -418,6 +418,7 @@ Bootmeth drivers are provided for:
> >      - EFI boot using bootefi from disk
> >      - VBE
> >      - EFI boot using boot manager
> > +   - :doc:`QFW <qfw>`: QEMU firmware interface
> >
> >
> >   Command interface
> > diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
> > new file mode 100644
> > index 00000000000..b0d47fd246a
> > --- /dev/null
> > +++ b/doc/develop/bootstd/qfw.rst
> > @@ -0,0 +1,21 @@
> > +.. 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 iniital ramdisk and provided by
>
> %s/iniital/initial/
>
> > +`-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
>
> Boot methods should work if the command line is deactivated. We should
> not use run_command() but extract the functionality into library code.
>
> Why would you first try to run booti and then bootz irrespective of the
> availability of the commands? Function qfw_boot() needs rework.

Yes, this is just the existing code ported into a bootmeth. I have not
tried to rework it, but it would be a good idea now that I have done
all the work of separating out booting from cmdline.

>
> There should be a configuration symbol to disable the boot method when
> CONFIG_QFW is enabled.
>
> The bootmethod should no be built if booti and bootz are not available
>
> > +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. The driver
> > +is automatically instantiated if there are no bootmeth drivers in the
> > +devicetree.
>
> This paragraph should be moved to the overview.
>
> Please, mention the configuration requirements.
Regards,
Simon

Re: [PATCH 06/13] doc: Add a description for bootmeth_cros

[Simon Glass]

Hi Heinrich,

On Tue, 16 Jul 2024 at 00:07, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> On 7/15/24 12:13, Simon Glass wrote:
> > Add documentation for the cros bootmeth.
>
> %s/bootmeth/boot method/
>
> throughout the patch.
>
> >
> > Signed-off-by: Simon Glass <sjg@chromium.org>
> > ---
> >
> >   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..96f148837ac
> > --- /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
>
> What does 'invoked on a boot device' mean? Do you mean "if ChromimumOS
> selects a boot device"?

No, this how bootstd works. It scans through the bootdevs one at a
time and invokes the bootmeths on each.

>
> > +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 OS, each with its
>
> %s/OS/operating system/
>
> > +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. The driver is
> > +automatically instantiated if there are no bootmeth drivers in the devicetree.
>
> The last sentence should be moved to the overview.
>
> Please, mention the relevant configuration option for the boot method
> driver.
>
[..]

Regards,
Simon

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

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On lun., juil. 15, 2024 at 11:13, 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: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
>  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 03/13] doc: Add a description for bootmeth_extlinux

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On lun., juil. 15, 2024 at 11:13, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the extlinux bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>

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

Minor nitpicks below, feel free to ignore or apply.

> ---
>
>  doc/develop/bootstd/extlinux.rst | 27 +++++++++++++++++++++++++++
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  2 +-
>  3 files changed, 29 insertions(+), 1 deletion(-)
>  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..28490f38899
> --- /dev/null
> +++ b/doc/develop/bootstd/extlinux.rst
> @@ -0,0 +1,27 @@
> +.. 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 possible
> +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 OSes 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

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

> +with the `filename-prefixes` property in the bootstd device.
> +
> +Note that PXE (Preboot eXecution-Environment) 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 OS or provide a list of options to the user, perhaps with a timeout.
> +
> +The compatible string "u-boot,extlinux" is used for the driver. The driver is
> +automatically instantiated if there are no bootmeth drivers in the devicetree.
> 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 761f61a573b..086a0b1281d 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -412,7 +412,7 @@ Available bootmeth drivers
>  
>  Bootmeth drivers are provided for:
>  
> -   - extlinux / syslinux boot from a disk
> +   - :doc:`extlinux / syslinux <extlinux>` boot from a disk
>     - 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 04/13] doc: Add a description for bootmeth_pxe

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On lun., juil. 15, 2024 at 11:13, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the pxe bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>

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

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

> ---
>
>  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 086a0b1281d..fd0692daf0d 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:
>  
>     - :doc:`extlinux / syslinux <extlinux>` boot from a disk
> -   - 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..08ba67e09c5
> --- /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 OSes along with the kernel, initial
> +ramdisk and other settings. The file is retrieved from a network server using
> +tftpboot.
> +
> +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 OS 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. The driver
> +is automatically instantiated if there are no bootmeth drivers in the
> +devicetree.
> -- 
> 2.34.1

Re: [PATCH 05/13] doc: Add a description for bootmeth_qfw

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On lun., juil. 15, 2024 at 11:13, 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>
> ---
>
>  boot/bootmeth_qfw.c              |  2 +-
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  1 +
>  doc/develop/bootstd/qfw.rst      | 21 +++++++++++++++++++++
>  4 files changed, 24 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 fd0692daf0d..bcc2c00c775 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -418,6 +418,7 @@ Bootmeth drivers are provided for:
>     - EFI boot using bootefi from disk
>     - VBE
>     - EFI boot using boot manager
> +   - :doc:`QFW <qfw>`: QEMU firmware interface
>  
>  
>  Command interface
> diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
> new file mode 100644
> index 00000000000..b0d47fd246a
> --- /dev/null
> +++ b/doc/develop/bootstd/qfw.rst
> @@ -0,0 +1,21 @@
> +.. 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 iniital ramdisk and provided by

iniital -> initial

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. The driver
> +is automatically instantiated if there are no bootmeth drivers in the
> +devicetree.
> -- 
> 2.34.1

Re: [PATCH 06/13] doc: Add a description for bootmeth_cros

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On lun., juil. 15, 2024 at 11:13, Simon Glass <sjg@chromium.org> wrote:

> Add documentation for the cros bootmeth.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>

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

> ---
>
>  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..96f148837ac
> --- /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 OS, 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. The driver is
> +automatically instantiated if there are no bootmeth drivers in the devicetree.
> 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 bcc2c00c775..f12e93236a7 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -417,6 +417,7 @@ Bootmeth drivers are provided for:
>     - 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 07/13] doc: Add a description for bootmeth_sandbox

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

On lun., juil. 15, 2024 at 11:13, 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: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>
>  boot/bootmeth_sandbox.c          |  2 +-
>  doc/develop/bootstd/index.rst    |  1 +
>  doc/develop/bootstd/overview.rst |  1 +
>  doc/develop/bootstd/sandbox.rst  | 18 ++++++++++++++++++
>  4 files changed, 21 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 f12e93236a7..58acaa4d3ce 100644
> --- a/doc/develop/bootstd/overview.rst
> +++ b/doc/develop/bootstd/overview.rst
> @@ -420,6 +420,7 @@ Bootmeth drivers are provided for:
>     - :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
>  
>  
>  Command interface
> diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst
> new file mode 100644
> index 00000000000..508f0fd5baa
> --- /dev/null
> +++ b/doc/develop/bootstd/sandbox.rst
> @@ -0,0 +1,18 @@
> +.. 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. The
> +driver is automatically instantiated if there are no bootmeth drivers in the
> +devicetree.
> -- 
> 2.34.1

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

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 5119 bytes --]

On Tue, Jul 16, 2024 at 08:04:38AM +0100, Simon Glass wrote:
> Hi Heinrich,
> 
> On Mon, 15 Jul 2024 at 22:58, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
> >
> > On 7/15/24 12:13, Simon Glass wrote:
> > > Before adding more files, move the bootstd docs into a new directory,
> > > with an index.
> > >
> > > Signed-off-by: Simon Glass <sjg@chromium.org>
> > > ---
> > >
> > >   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
> > > +======================
> > >
> >
> >
> >
> > The text is not optimized for readability, e.g.
> >
> > "- bootdev  - a device which can hold or access a distro (e.g. MMC,
> > Ethernet)"
> >
> > Please, consistently replace the non-words in the boot standard
> > documentation:
> >
> > %s/bootdev/boot device/
> > %s/bootmeth/boot method/
> > %s/bootflow/boot flow/
> 
> I do want to keep the terms, It is easy to search for bootdev or
> bootmeth in the code and docs. Once people learn what they mean it is
> pretty simple.

I agree, this is the documentation for "bootdev" and "bootmeth" and
"bootflow" not for "boot device" and so forth.

> > "distro" isn't a dictionary word either. Do you mean operating system?
> 
> I mean a linux distro, in the sense that 'distro boot' uses it.

Maybe an initial statement early about starting your operating system
distribution (distro), and then it's OK to say distro later on? This
does also work on non-Linux distributions :)

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

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

[Simon Glass]

Hi Tom,

On Tue, 16 Jul 2024 at 17:18, Tom Rini <trini@konsulko.com> wrote:
>
> On Tue, Jul 16, 2024 at 08:04:38AM +0100, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Mon, 15 Jul 2024 at 22:58, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
> > >
> > > On 7/15/24 12:13, Simon Glass wrote:
> > > > Before adding more files, move the bootstd docs into a new directory,
> > > > with an index.
> > > >
> > > > Signed-off-by: Simon Glass <sjg@chromium.org>
> > > > ---
> > > >
> > > >   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
> > > > +======================
> > > >
> > >
> > >
> > >
> > > The text is not optimized for readability, e.g.
> > >
> > > "- bootdev  - a device which can hold or access a distro (e.g. MMC,
> > > Ethernet)"
> > >
> > > Please, consistently replace the non-words in the boot standard
> > > documentation:
> > >
> > > %s/bootdev/boot device/
> > > %s/bootmeth/boot method/
> > > %s/bootflow/boot flow/
> >
> > I do want to keep the terms, It is easy to search for bootdev or
> > bootmeth in the code and docs. Once people learn what they mean it is
> > pretty simple.
>
> I agree, this is the documentation for "bootdev" and "bootmeth" and
> "bootflow" not for "boot device" and so forth.
>
> > > "distro" isn't a dictionary word either. Do you mean operating system?
> >
> > I mean a linux distro, in the sense that 'distro boot' uses it.
>
> Maybe an initial statement early about starting your operating system
> distribution (distro), and then it's OK to say distro later on? This
> does also work on non-Linux distributions :)

I missed this comment...

There is this in the introduction: "For Linux, the distro (Linux
distribution, e.g. Debian, Fedora) is responsible"

In other places I call it an Operating System. I like the word
'distro' since it is widely used. It is also the name of the
script-based distro-boot feature. However it refers to Linux, which is
a bit limiting.

I'm open to any changes here to make things better / clearer.

Regards,
SImon

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

[Ilias Apalodimas]

On Mon, 15 Jul 2024 at 13:14, Simon Glass <sjg@chromium.org> wrote:
>
> Fix a minor indentation / whitespace problem in a comment.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
>  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
>
Reviewed-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>