Skip to contentSkip to conversation

doc: Add documentation for bootmeths

PATCH Superseded Simon Glass 6 participants 49 messages Jul 15, 2024 – Jul 22, 2024

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover doc: Add documentation for bootmeths

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
Signature · 1 line
2.34.1
#1 lore raw

PATCH 1/13 MAINTAINERS: Rename BOOTDEVICE

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

---

 MAINTAINERS | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
MAINTAINERS +1 -1
index 2c6de3a1d84..9bee9284cca 100644
@@ -918,7 +918,7 @@ F:	drivers/block/blkmap.c
 F:	include/blkmap.h
 F:	test/dm/blkmap.c
 
-BOOTDEVICE
+BOOTSTD
 M:	Simon Glass <[email protected]>
 S:	Maintained
 F:	boot/bootdev*.c
Signature · 1 line
2.34.1
Reviewed-by on v1 1/13
#3 lore raw

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

In reply to Simon Glass

Hi Simon,

Thank you for the patch.

Quoted 3 lines · Simon Glass

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

Quoted 20 lines

---

 MAINTAINERS | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
MAINTAINERS +1 -1
index 2c6de3a1d84..9bee9284cca 100644
@@ -918,7 +918,7 @@ F:	drivers/block/blkmap.c
 F:	include/blkmap.h
 F:	test/dm/blkmap.c
 
-BOOTDEVICE
+BOOTSTD
 M:	Simon Glass <[email protected]>
 S:	Maintained
 F:	boot/bootdev*.c
Signature · 1 line
2.34.1
#4 lore raw

PATCH 2/13 doc: Move bootstd into its own directory

In reply to Simon Glass

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

---

 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%)
MAINTAINERS +1 -1
index 9bee9284cca..86b830aa997 100644
@@ -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
doc/board/starfive/milk-v_mars_cm.rst +1 -1
index b31de6043bb..52d4e5e9098 100644
@@ -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
doc/develop/board_best_practices.rst +1 -1
index f44401eab7d..09632c80ce7 100644
@@ -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`.
doc/develop/bootstd/index.rst new file +9 -0
new file mode 100644
index 00000000000..f4f87c7787c
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +7 -7
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644
@@ -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:
 
doc/develop/index.rst +1 -1
index f9c4bf839ee..c0107a783fc 100644
@@ -29,7 +29,7 @@ Implementation
 
    directories
    bloblist
-   bootstd
+   bootstd/index
    ci_testing
    commands
    config_binding
doc/usage/cmd/bootdev.rst +1 -1
index f759abab354..98a0f43c580 100644
@@ -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
doc/usage/cmd/bootflow.rst +1 -1
index 6519e4880a9..5d41fe37a7a 100644
@@ -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
doc/usage/cmd/bootmeth.rst +1 -1
index bac9fdf85cd..c3d2ec1574b 100644
@@ -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:
doc/usage/environment.rst +1 -1
index 7d4b448cb30..cc33d3ec0f2 100644
@@ -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
Signature · 1 line
2.34.1
#6 lore raw

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

In reply to Simon Glass
Quoted 82 lines · Simon Glass

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

---

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

MAINTAINERS +1 -1
index 9bee9284cca..86b830aa997 100644
@@ -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
doc/board/starfive/milk-v_mars_cm.rst +1 -1
index b31de6043bb..52d4e5e9098 100644
@@ -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
doc/develop/board_best_practices.rst +1 -1
index f44401eab7d..09632c80ce7 100644
@@ -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`.
doc/develop/bootstd/index.rst new file +9 -0
new file mode 100644
index 00000000000..f4f87c7787c
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +0 -0
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644

doc/develop/bootstd/overview.rst line 5

Quoted 7 lines
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +2 -2
@@ -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

Quoted 105 lines
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +5 -5
  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:
 
doc/develop/index.rst +1 -1
index f9c4bf839ee..c0107a783fc 100644
@@ -29,7 +29,7 @@ Implementation
 
     directories
     bloblist
-   bootstd
+   bootstd/index
     ci_testing
     commands
     config_binding
doc/usage/cmd/bootdev.rst +1 -1
index f759abab354..98a0f43c580 100644
@@ -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
doc/usage/cmd/bootflow.rst +1 -1
index 6519e4880a9..5d41fe37a7a 100644
@@ -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
doc/usage/cmd/bootmeth.rst +1 -1
index bac9fdf85cd..c3d2ec1574b 100644
@@ -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:
doc/usage/environment.rst +1 -1
index 7d4b448cb30..cc33d3ec0f2 100644
@@ -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
#7 lore raw

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

Hi Heinrich,

Quoted 99 lines · Heinrich Schuchardt
Quoted 82 lines · Simon Glass

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

---

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

MAINTAINERS +1 -1
index 9bee9284cca..86b830aa997 100644
@@ -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
doc/board/starfive/milk-v_mars_cm.rst +1 -1
index b31de6043bb..52d4e5e9098 100644
@@ -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
doc/develop/board_best_practices.rst +1 -1
index f44401eab7d..09632c80ce7 100644
@@ -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`.
doc/develop/bootstd/index.rst new file +9 -0
new file mode 100644
index 00000000000..f4f87c7787c
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +0 -0
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644

doc/develop/bootstd/overview.rst line 5

Quoted 7 lines
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +2 -2
@@ -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)"

Quoted 6 lines

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.

Quoted 2 lines

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

Quoted 9 lines

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] ?

Quoted 105 lines

Best regards

Heinrich

Quoted 98 lines
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +5 -5
  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:
 
doc/develop/index.rst +1 -1
index f9c4bf839ee..c0107a783fc 100644
@@ -29,7 +29,7 @@ Implementation
 
     directories
     bloblist
-   bootstd
+   bootstd/index
     ci_testing
     commands
     config_binding
doc/usage/cmd/bootdev.rst +1 -1
index f759abab354..98a0f43c580 100644
@@ -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
doc/usage/cmd/bootflow.rst +1 -1
index 6519e4880a9..5d41fe37a7a 100644
@@ -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
doc/usage/cmd/bootmeth.rst +1 -1
index bac9fdf85cd..c3d2ec1574b 100644
@@ -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:
doc/usage/environment.rst +0 -0
index 7d4b448cb30..cc33d3ec0f2 100644
@@ -100,7 +100,7 @@ to add environment variables.
 
Quoted 8 lines

doc/usage/environment.rst to add environment variables. · line 106

Quoted 7 lines
doc/usage/environment.rst +1 -1
  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

#8 lore raw

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

Quoted 105 lines · Simon Glass

Hi Heinrich,

Quoted 102 lines · Heinrich Schuchardt
Quoted 82 lines · Simon Glass

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

---

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

MAINTAINERS +1 -1
index 9bee9284cca..86b830aa997 100644
@@ -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
doc/board/starfive/milk-v_mars_cm.rst +1 -1
index b31de6043bb..52d4e5e9098 100644
@@ -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
doc/develop/board_best_practices.rst +1 -1
index f44401eab7d..09632c80ce7 100644
@@ -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`.
doc/develop/bootstd/index.rst new file +9 -0
new file mode 100644
index 00000000000..f4f87c7787c
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +0 -0
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644

doc/develop/bootstd/overview.rst line 5

Quoted 7 lines
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +2 -2
@@ -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:

Quoted 7 lines
Quoted 3 lines

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

Quoted 3 lines
Quoted 1 line

"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 :)

Signature · 1 line
Tom
#9 lore raw

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

Hi Tom,

Quoted 118 lines · Tom Rini
Quoted 105 lines · Simon Glass

Hi Heinrich,

Quoted 102 lines · Heinrich Schuchardt
Quoted 82 lines · Simon Glass

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

---

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

MAINTAINERS +1 -1
index 9bee9284cca..86b830aa997 100644
@@ -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
doc/board/starfive/milk-v_mars_cm.rst +1 -1
index b31de6043bb..52d4e5e9098 100644
@@ -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
doc/develop/board_best_practices.rst +1 -1
index f44401eab7d..09632c80ce7 100644
@@ -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`.
doc/develop/bootstd/index.rst new file +9 -0
new file mode 100644
index 00000000000..f4f87c7787c
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +0 -0
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644

doc/develop/bootstd/overview.rst line 5

Quoted 7 lines
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +2 -2
@@ -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:

Quoted 7 lines
Quoted 3 lines

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

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

"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

Reviewed-by on v1 2/13
#10 lore raw

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

In reply to Simon Glass

Hi Simon,

Thank you for the patch.

Quoted 4 lines · Simon Glass

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

Quoted 192 lines

---

 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%)
MAINTAINERS +1 -1
index 9bee9284cca..86b830aa997 100644
@@ -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
doc/board/starfive/milk-v_mars_cm.rst +1 -1
index b31de6043bb..52d4e5e9098 100644
@@ -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
doc/develop/board_best_practices.rst +1 -1
index f44401eab7d..09632c80ce7 100644
@@ -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`.
doc/develop/bootstd/index.rst new file +9 -0
new file mode 100644
index 00000000000..f4f87c7787c
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
doc/develop/bootstd/overview.rst renamed from doc/develop/bootstd.rst +7 -7
similarity index 99%
rename from doc/develop/bootstd.rst
rename to doc/develop/bootstd/overview.rst
index 34631089ae0..761f61a573b 100644
@@ -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:
 
doc/develop/index.rst +1 -1
index f9c4bf839ee..c0107a783fc 100644
@@ -29,7 +29,7 @@ Implementation
 
    directories
    bloblist
-   bootstd
+   bootstd/index
    ci_testing
    commands
    config_binding
doc/usage/cmd/bootdev.rst +1 -1
index f759abab354..98a0f43c580 100644
@@ -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
doc/usage/cmd/bootflow.rst +1 -1
index 6519e4880a9..5d41fe37a7a 100644
@@ -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
doc/usage/cmd/bootmeth.rst +1 -1
index bac9fdf85cd..c3d2ec1574b 100644
@@ -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:
doc/usage/environment.rst +1 -1
index 7d4b448cb30..cc33d3ec0f2 100644
@@ -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
Signature · 1 line
2.34.1
#11 lore raw

PATCH 3/13 doc: Add a description for bootmeth_extlinux

In reply to Simon Glass

Add documentation for the extlinux bootmeth.

---

 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
doc/develop/bootstd/extlinux.rst new file +27 -0
new file mode 100644
index 00000000000..28490f38899
@@ -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.
doc/develop/bootstd/index.rst +1 -0
index f4f87c7787c..5bbb3d633a3 100644
@@ -7,3 +7,4 @@ Standard Boot
    :maxdepth: 2
 
    overview
+   extlinux
doc/develop/bootstd/overview.rst +1 -1
index 761f61a573b..086a0b1281d 100644
@@ -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
Signature · 1 line
2.34.1
#13 lore raw

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

In reply to Simon Glass
Quoted 17 lines · Simon Glass

Add documentation for the extlinux bootmeth.

---

  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

doc/develop/bootstd/extlinux.rst new file +0 -0
new file mode 100644
index 00000000000..28490f38899

doc/develop/bootstd/extlinux.rst line 7

Quoted 7 lines
doc/develop/bootstd/extlinux.rst new file +7 -0
@@ -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/

doc/develop/bootstd/extlinux.rst line 8

Quoted 1 line
doc/develop/bootstd/extlinux.rst new file +1 -0
+Operating Systems from which the user can choose.

%s/Operating Systems/operating systems/

doc/develop/bootstd/extlinux.rst line 11

Quoted 3 lines
doc/develop/bootstd/extlinux.rst new file +3 -0
+
+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/

doc/develop/bootstd/extlinux.rst line 14

Quoted 3 lines
doc/develop/bootstd/extlinux.rst new file +3 -0
+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/

doc/develop/bootstd/extlinux.rst line 19

Quoted 5 lines
doc/develop/bootstd/extlinux.rst new file +5 -0
+
+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/

doc/develop/bootstd/extlinux.rst line 20

Quoted 1 line
doc/develop/bootstd/extlinux.rst new file +1 -0
+bootflow if found.

%s/bootflow/bootflow/

doc/develop/bootstd/extlinux.rst line 24

Quoted 4 lines
doc/develop/bootstd/extlinux.rst new file +4 -0
+
+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/

doc/develop/bootstd/extlinux.rst line 27

Quoted 3 lines
doc/develop/bootstd/extlinux.rst new file +3 -0
+
+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.

Quoted 14 lines
doc/develop/bootstd/index.rst +1 -0
index f4f87c7787c..5bbb3d633a3 100644
@@ -7,3 +7,4 @@ Standard Boot
     :maxdepth: 2
 
     overview
+   extlinux
doc/develop/bootstd/overview.rst +0 -0
index 761f61a573b..086a0b1281d 100644

doc/develop/bootstd/overview.rst Available bootmeth drivers · line 413

Quoted 2 lines
doc/develop/bootstd/overview.rst +0 -0
@@ -412,7 +412,7 @@ Available bootmeth drivers
 
  Bootmeth drivers are provided for:

%s/Bootmeth/Boot method/

doc/develop/bootstd/overview.rst Available bootmeth drivers · line 415

Quoted 3 lines
doc/develop/bootstd/overview.rst +1 -1
-   - 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

Quoted 3 lines
doc/develop/bootstd/overview.rst +0 -0
     - extlinux boot from a network (PXE)
     - U-Boot scripts from disk, network or SPI flash
     - EFI boot using bootefi from disk
#14 lore raw

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

Hi Heinrich,

Quoted 76 lines · Heinrich Schuchardt
Quoted 17 lines · Simon Glass

Add documentation for the extlinux bootmeth.

---

  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

doc/develop/bootstd/extlinux.rst new file +0 -0
new file mode 100644
index 00000000000..28490f38899

doc/develop/bootstd/extlinux.rst line 7

Quoted 7 lines
doc/develop/bootstd/extlinux.rst new file +7 -0
@@ -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/

doc/develop/bootstd/extlinux.rst line 8

Quoted 1 line
doc/develop/bootstd/extlinux.rst new file +1 -0
+Operating Systems from which the user can choose.

%s/Operating Systems/operating systems/

doc/develop/bootstd/extlinux.rst line 11

Quoted 3 lines
doc/develop/bootstd/extlinux.rst new file +3 -0
+
+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/

doc/develop/bootstd/extlinux.rst line 14

Quoted 3 lines
doc/develop/bootstd/extlinux.rst new file +3 -0
+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/

doc/develop/bootstd/extlinux.rst line 19

Quoted 5 lines
doc/develop/bootstd/extlinux.rst new file +5 -0
+
+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/

doc/develop/bootstd/extlinux.rst line 20

Quoted 1 line
doc/develop/bootstd/extlinux.rst new file +1 -0
+bootflow if found.

%s/bootflow/bootflow/

doc/develop/bootstd/extlinux.rst line 24

Quoted 4 lines
doc/develop/bootstd/extlinux.rst new file +4 -0
+
+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/

doc/develop/bootstd/extlinux.rst line 27

Quoted 3 lines
doc/develop/bootstd/extlinux.rst new file +3 -0
+
+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:

Quoted 3 lines

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.

Quoted 27 lines

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

Quoted 14 lines
doc/develop/bootstd/index.rst +1 -0
index f4f87c7787c..5bbb3d633a3 100644
@@ -7,3 +7,4 @@ Standard Boot
     :maxdepth: 2
 
     overview
+   extlinux
doc/develop/bootstd/overview.rst +0 -0
index 761f61a573b..086a0b1281d 100644

doc/develop/bootstd/overview.rst Available bootmeth drivers · line 413

Quoted 2 lines
doc/develop/bootstd/overview.rst +0 -0
@@ -412,7 +412,7 @@ Available bootmeth drivers
 
  Bootmeth drivers are provided for:

%s/Bootmeth/Boot method/

doc/develop/bootstd/overview.rst Available bootmeth drivers · line 415

Quoted 3 lines
doc/develop/bootstd/overview.rst +1 -1
-   - extlinux / syslinux boot from a disk
+   - :doc:`extlinux / syslinux <extlinux>` boot from a disk
Quoted 12 lines

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

Quoted 3 lines
doc/develop/bootstd/overview.rst +0 -0
     - extlinux boot from a network (PXE)
     - U-Boot scripts from disk, network or SPI flash
     - EFI boot using bootefi from disk

Regards,
Simon

Reviewed-by on v1 3/13
#15 lore raw

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

In reply to Simon Glass

Hi Simon,

Thank you for the patch.

Quoted 3 lines · Simon Glass

Add documentation for the extlinux bootmeth.

Minor nitpicks below, feel free to ignore or apply.

Quoted 17 lines

---

 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
doc/develop/bootstd/extlinux.rst new file +3 -0
new file mode 100644
index 00000000000..28490f38899
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Extlinux Bootmeth

doc/develop/bootstd/extlinux.rst line 13

Quoted 10 lines
doc/develop/bootstd/extlinux.rst new file +10 -0
+=================
+
+`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 ?

doc/develop/bootstd/extlinux.rst line 23

Quoted 10 lines
doc/develop/bootstd/extlinux.rst new file +10 -0
+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

Quoted 28 lines
doc/develop/bootstd/extlinux.rst new file +4 -0
+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.
doc/develop/bootstd/index.rst +1 -0
index f4f87c7787c..5bbb3d633a3 100644
@@ -7,3 +7,4 @@ Standard Boot
    :maxdepth: 2
 
    overview
+   extlinux
doc/develop/bootstd/overview.rst +1 -1
index 761f61a573b..086a0b1281d 100644
@@ -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
Signature · 1 line
2.34.1
#16 lore raw

PATCH 4/13 doc: Add a description for bootmeth_pxe

In reply to Simon Glass

Add documentation for the pxe bootmeth.

---

 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
doc/develop/bootstd/index.rst +1 -0
index 5bbb3d633a3..5052afe448f 100644
@@ -8,3 +8,4 @@ Standard Boot
 
    overview
    extlinux
+   pxelinux
doc/develop/bootstd/overview.rst +1 -1
index 086a0b1281d..fd0692daf0d 100644
@@ -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
doc/develop/bootstd/pxelinux.rst new file +27 -0
new file mode 100644
index 00000000000..08ba67e09c5
@@ -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.
Signature · 1 line
2.34.1
#18 lore raw

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

In reply to Simon Glass
Quoted 39 lines · Simon Glass

Add documentation for the pxe bootmeth.

---

  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

doc/develop/bootstd/index.rst +1 -0
index 5bbb3d633a3..5052afe448f 100644
@@ -8,3 +8,4 @@ Standard Boot
 
     overview
     extlinux
+   pxelinux
doc/develop/bootstd/overview.rst +1 -1
index 086a0b1281d..fd0692daf0d 100644
@@ -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
doc/develop/bootstd/pxelinux.rst new file +0 -0
new file mode 100644
index 00000000000..08ba67e09c5

doc/develop/bootstd/pxelinux.rst line 6

Quoted 6 lines
doc/develop/bootstd/pxelinux.rst new file +6 -0
@@ -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/

doc/develop/bootstd/pxelinux.rst line 7

Quoted 1 line
doc/develop/bootstd/pxelinux.rst new file +1 -0
+over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to

%s/bootmeth/boot method/

doc/develop/bootstd/pxelinux.rst line 8

Quoted 1 line
doc/develop/bootstd/pxelinux.rst new file +1 -0
+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?

doc/develop/bootstd/pxelinux.rst line 14

Quoted 6 lines
doc/develop/bootstd/pxelinux.rst new file +6 -0
+
+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/

doc/develop/bootstd/pxelinux.rst line 16

Quoted 2 lines
doc/develop/bootstd/pxelinux.rst new file +2 -0
+
+When invoked on a bootdev, this bootmeth searches for the file and creates a

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

doc/develop/bootstd/pxelinux.rst line 17

Quoted 1 line
doc/develop/bootstd/pxelinux.rst new file +1 -0
+bootflow if found. See

%s/bootflow/boot flow/

doc/develop/bootstd/pxelinux.rst line 27

Quoted 10 lines
doc/develop/bootstd/pxelinux.rst new file +10 -0
+`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

#19 lore raw

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

Hi Heinrich,

Quoted 50 lines · Heinrich Schuchardt
Quoted 39 lines · Simon Glass

Add documentation for the pxe bootmeth.

---

  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

doc/develop/bootstd/index.rst +1 -0
index 5bbb3d633a3..5052afe448f 100644
@@ -8,3 +8,4 @@ Standard Boot
 
     overview
     extlinux
+   pxelinux
doc/develop/bootstd/overview.rst +1 -1
index 086a0b1281d..fd0692daf0d 100644
@@ -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
doc/develop/bootstd/pxelinux.rst new file +0 -0
new file mode 100644
index 00000000000..08ba67e09c5

doc/develop/bootstd/pxelinux.rst line 6

Quoted 6 lines
doc/develop/bootstd/pxelinux.rst new file +6 -0
@@ -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/

Quoted 8 lines

doc/develop/bootstd/pxelinux.rst line 7

Quoted 1 line
doc/develop/bootstd/pxelinux.rst new file +1 -0
+over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to

%s/bootmeth/boot method/

doc/develop/bootstd/pxelinux.rst line 8

Quoted 1 line
doc/develop/bootstd/pxelinux.rst new file +1 -0
+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.

Quoted 39 lines

doc/develop/bootstd/pxelinux.rst line 14

Quoted 7 lines
doc/develop/bootstd/pxelinux.rst new file +6 -0
+
+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/

doc/develop/bootstd/pxelinux.rst line 16

Quoted 2 lines
doc/develop/bootstd/pxelinux.rst new file +2 -0
+
+When invoked on a bootdev, this bootmeth searches for the file and creates a

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

doc/develop/bootstd/pxelinux.rst line 17

Quoted 1 line
doc/develop/bootstd/pxelinux.rst new file +1 -0
+bootflow if found. See

%s/bootflow/boot flow/

doc/develop/bootstd/pxelinux.rst line 27

Quoted 10 lines
doc/develop/bootstd/pxelinux.rst new file +10 -0
+`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.

Quoted 3 lines

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

Quoted 2 lines

Please, mention the relevant configuration option.

Regards,
Simon

Reviewed-by on v1 4/13
#20 lore raw

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

In reply to Simon Glass

Hi Simon,

Thank you for the patch.

Quoted 3 lines · Simon Glass

Add documentation for the pxe bootmeth.

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

Quoted 65 lines

---

 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
doc/develop/bootstd/index.rst +1 -0
index 5bbb3d633a3..5052afe448f 100644
@@ -8,3 +8,4 @@ Standard Boot
 
    overview
    extlinux
+   pxelinux
doc/develop/bootstd/overview.rst +1 -1
index 086a0b1281d..fd0692daf0d 100644
@@ -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
doc/develop/bootstd/pxelinux.rst new file +27 -0
new file mode 100644
index 00000000000..08ba67e09c5
@@ -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.
Signature · 1 line
2.34.1
#21 lore raw

PATCH 5/13 doc: Add a description for bootmeth_qfw

In reply to 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.

---

 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
boot/bootmeth_qfw.c +1 -1
index dfaa944594e..2f8e00cf350 100644
@@ -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" },
 	{ }
 };
 
doc/develop/bootstd/index.rst +1 -0
index 5052afe448f..f8fce7207ce 100644
@@ -9,3 +9,4 @@ Standard Boot
    overview
    extlinux
    pxelinux
+   qfw
doc/develop/bootstd/overview.rst +1 -0
index fd0692daf0d..bcc2c00c775 100644
@@ -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
doc/develop/bootstd/qfw.rst new file +21 -0
new file mode 100644
index 00000000000..b0d47fd246a
@@ -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.
Signature · 1 line
2.34.1
#23 lore raw

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

In reply to Simon Glass
Quoted 2 lines · Simon Glass

Add documentation for the qfw bootmeth.

%s/bootmeth/boot method/

Quoted 54 lines

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

---

  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

boot/bootmeth_qfw.c +1 -1
index dfaa944594e..2f8e00cf350 100644
@@ -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" },
  	{ }
  };
 
doc/develop/bootstd/index.rst +1 -0
index 5052afe448f..f8fce7207ce 100644
@@ -9,3 +9,4 @@ Standard Boot
     overview
     extlinux
     pxelinux
+   qfw
doc/develop/bootstd/overview.rst +1 -0
index fd0692daf0d..bcc2c00c775 100644
@@ -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
doc/develop/bootstd/qfw.rst new file +1 -0
new file mode 100644
index 00000000000..b0d47fd246a
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0+:

doc/develop/bootstd/qfw.rst line 11

Quoted 10 lines
doc/develop/bootstd/qfw.rst new file +10 -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/

doc/develop/bootstd/qfw.rst line 15

Quoted 4 lines
doc/develop/bootstd/qfw.rst new file +4 -0
+`-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

doc/develop/bootstd/qfw.rst line 21

Quoted 6 lines
doc/develop/bootstd/qfw.rst new file +6 -0
+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

#24 lore raw

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

Hi Heinrich,

Quoted 83 lines · Heinrich Schuchardt
Quoted 2 lines · Simon Glass

Add documentation for the qfw bootmeth.

%s/bootmeth/boot method/

Quoted 54 lines

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

---

  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

boot/bootmeth_qfw.c +1 -1
index dfaa944594e..2f8e00cf350 100644
@@ -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" },
      { }
  };
 
doc/develop/bootstd/index.rst +1 -0
index 5052afe448f..f8fce7207ce 100644
@@ -9,3 +9,4 @@ Standard Boot
     overview
     extlinux
     pxelinux
+   qfw
doc/develop/bootstd/overview.rst +1 -0
index fd0692daf0d..bcc2c00c775 100644
@@ -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
doc/develop/bootstd/qfw.rst new file +1 -0
new file mode 100644
index 00000000000..b0d47fd246a
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0+:

doc/develop/bootstd/qfw.rst line 11

Quoted 10 lines
doc/develop/bootstd/qfw.rst new file +10 -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/

doc/develop/bootstd/qfw.rst line 15

Quoted 4 lines
doc/develop/bootstd/qfw.rst new file +4 -0
+`-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.

Quoted 2 lines

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.

Quoted 15 lines

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

doc/develop/bootstd/qfw.rst line 21

Quoted 6 lines
doc/develop/bootstd/qfw.rst new file +6 -0
+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.

Quoted 1 line

Please, mention the configuration requirements.

Regards,
Simon

Reviewed-by on v1 5/13
#25 lore raw

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

In reply to Simon Glass

Hi Simon,

Thank you for the patch.

Quoted 56 lines · 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.

---

 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
boot/bootmeth_qfw.c +1 -1
index dfaa944594e..2f8e00cf350 100644
@@ -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" },
 	{ }
 };
 
doc/develop/bootstd/index.rst +1 -0
index 5052afe448f..f8fce7207ce 100644
@@ -9,3 +9,4 @@ Standard Boot
    overview
    extlinux
    pxelinux
+   qfw
doc/develop/bootstd/overview.rst +1 -0
index fd0692daf0d..bcc2c00c775 100644
@@ -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
doc/develop/bootstd/qfw.rst new file +1 -0
new file mode 100644
index 00000000000..b0d47fd246a
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0+:

doc/develop/bootstd/qfw.rst line 11

Quoted 10 lines
doc/develop/bootstd/qfw.rst new file +10 -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:

Quoted 12 lines
doc/develop/bootstd/qfw.rst new file +10 -0
+`-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.
Signature · 1 line
2.34.1
#26 lore raw

PATCH 6/13 doc: Add a description for bootmeth_cros

In reply to Simon Glass

Add documentation for the cros bootmeth.

---

 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
doc/develop/bootstd/cros.rst new file +33 -0
new file mode 100644
index 00000000000..96f148837ac
@@ -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.
doc/develop/bootstd/index.rst +1 -0
index f8fce7207ce..69fd3c2d2eb 100644
@@ -10,3 +10,4 @@ Standard Boot
    extlinux
    pxelinux
    qfw
+   cros
doc/develop/bootstd/overview.rst +1 -0
index bcc2c00c775..f12e93236a7 100644
@@ -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
 
Signature · 1 line
2.34.1
#28 lore raw

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

In reply to Simon Glass
Quoted 1 line · Simon Glass

Add documentation for the cros bootmeth.

%s/bootmeth/boot method/

throughout the patch.

Quoted 21 lines

---

  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

doc/develop/bootstd/cros.rst new file +5 -0
new file mode 100644
index 00000000000..96f148837ac
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+ChromiumOS Bootmeth
+===================
+

doc/develop/bootstd/cros.rst line 15

Quoted 10 lines
doc/develop/bootstd/cros.rst new file +10 -0
+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"?

doc/develop/bootstd/cros.rst line 28

Quoted 13 lines
doc/develop/bootstd/cros.rst new file +13 -0
+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/

doc/develop/bootstd/cros.rst line 33

Quoted 5 lines
doc/develop/bootstd/cros.rst new file +5 -0
+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

Quoted 21 lines
doc/develop/bootstd/index.rst +1 -0
index f8fce7207ce..69fd3c2d2eb 100644
@@ -10,3 +10,4 @@ Standard Boot
     extlinux
     pxelinux
     qfw
+   cros
doc/develop/bootstd/overview.rst +1 -0
index bcc2c00c775..f12e93236a7 100644
@@ -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
 
#29 lore raw

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

Hi Heinrich,

Quoted 34 lines · Heinrich Schuchardt
Quoted 1 line · Simon Glass

Add documentation for the cros bootmeth.

%s/bootmeth/boot method/

throughout the patch.

Quoted 26 lines

---

  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

doc/develop/bootstd/cros.rst new file +10 -0
new file mode 100644
index 00000000000..96f148837ac
@@ -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
Quoted 8 lines

doc/develop/bootstd/cros.rst line 15

Quoted 5 lines
doc/develop/bootstd/cros.rst new file +5 -0
+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.

Quoted 25 lines
Quoted 4 lines
doc/develop/bootstd/cros.rst new file +3 -0
+the appropriate GUID (Globally Unique Identifier). When found, the information
+is loaded and a bootflow is created.
+

doc/develop/bootstd/cros.rst line 28

Quoted 10 lines
doc/develop/bootstd/cros.rst new file +10 -0
+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/

doc/develop/bootstd/cros.rst line 33

Quoted 5 lines
doc/develop/bootstd/cros.rst new file +5 -0
+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.

Quoted 3 lines

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

[..]

Regards,
Simon

Reviewed-by on v1 6/13
#30 lore raw

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

In reply to Simon Glass

Hi Simon,

Thank you for the patch.

Quoted 3 lines · Simon Glass

Add documentation for the cros bootmeth.

Quoted 70 lines

---

 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
doc/develop/bootstd/cros.rst new file +33 -0
new file mode 100644
index 00000000000..96f148837ac
@@ -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.
doc/develop/bootstd/index.rst +1 -0
index f8fce7207ce..69fd3c2d2eb 100644
@@ -10,3 +10,4 @@ Standard Boot
    extlinux
    pxelinux
    qfw
+   cros
doc/develop/bootstd/overview.rst +1 -0
index bcc2c00c775..f12e93236a7 100644
@@ -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
 
Signature · 1 line
2.34.1
#31 lore raw

PATCH 7/13 doc: Add a description for bootmeth_sandbox

In reply to 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.

---

 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
boot/bootmeth_sandbox.c +1 -1
index 0bc8f688e30..26c713bb5f3 100644
@@ -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" },
 	{ }
 };
 
doc/develop/bootstd/index.rst +1 -0
index 69fd3c2d2eb..2c5d2d3fade 100644
@@ -11,3 +11,4 @@ Standard Boot
    pxelinux
    qfw
    cros
+   sandbox
doc/develop/bootstd/overview.rst +1 -0
index f12e93236a7..58acaa4d3ce 100644
@@ -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
doc/develop/bootstd/sandbox.rst new file +18 -0
new file mode 100644
index 00000000000..508f0fd5baa
@@ -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.
Signature · 1 line
2.34.1
Reviewed-by on v1 7/13
#33 lore raw

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

In reply to Simon Glass

Hi Simon,

Thank you for the patch.

Quoted 6 lines · 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.

Quoted 69 lines

---

 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
boot/bootmeth_sandbox.c +1 -1
index 0bc8f688e30..26c713bb5f3 100644
@@ -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" },
 	{ }
 };
 
doc/develop/bootstd/index.rst +1 -0
index 69fd3c2d2eb..2c5d2d3fade 100644
@@ -11,3 +11,4 @@ Standard Boot
    pxelinux
    qfw
    cros
+   sandbox
doc/develop/bootstd/overview.rst +1 -0
index f12e93236a7..58acaa4d3ce 100644
@@ -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
doc/develop/bootstd/sandbox.rst new file +18 -0
new file mode 100644
index 00000000000..508f0fd5baa
@@ -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.
Signature · 1 line
2.34.1
#34 lore raw

PATCH 8/13 bootstd: Tidy up comments on the boothmeth drivers

In reply to Simon Glass

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

---

 boot/bootmeth_efi.c      | 1 +
 boot/bootmeth_extlinux.c | 2 +-
 boot/bootmeth_script.c   | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)
boot/bootmeth_efi.c +1 -0
index 5a4c125835a..56a6e47f5b2 100644
@@ -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,
boot/bootmeth_extlinux.c +1 -1
index 9b55686948f..fbb05ef928e 100644
@@ -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,
boot/bootmeth_script.c +1 -1
index 0e05d28d4d9..24da47c7259 100644
@@ -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,
Signature · 1 line
2.34.1
Reviewed-by on v1 8/13
#36 lore raw

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

In reply to Simon Glass
Quoted 3 lines · Simon Glass

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

Quoted 45 lines

---

  boot/bootmeth_efi.c      | 1 +
  boot/bootmeth_extlinux.c | 2 +-
  boot/bootmeth_script.c   | 2 +-
  3 files changed, 3 insertions(+), 2 deletions(-)
boot/bootmeth_efi.c +1 -0
index 5a4c125835a..56a6e47f5b2 100644
@@ -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,
boot/bootmeth_extlinux.c +1 -1
index 9b55686948f..fbb05ef928e 100644
@@ -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,
boot/bootmeth_script.c +1 -1
index 0e05d28d4d9..24da47c7259 100644
@@ -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,
#37 lore raw

PATCH 9/13 bootstd: Correct handling of script from network

In reply to 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.

---

 boot/bootmeth_script.c | 51 +++++++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 20 deletions(-)
boot/bootmeth_script.c +31 -20
index 24da47c7259..c5cbf18c2e6 100644
@@ -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);
 
Signature · 1 line
2.34.1
#38 lore raw

PATCH 10/13 doc: Add a description for bootmeth_script

In reply to Simon Glass

Add documentation for the script bootmeth.

---

 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
doc/develop/bootstd/index.rst +1 -0
index 2c5d2d3fade..9d35b567d55 100644
@@ -11,4 +11,5 @@ Standard Boot
    pxelinux
    qfw
    cros
+   script
    sandbox
doc/develop/bootstd/overview.rst +1 -1
index 58acaa4d3ce..7d31d5e6427 100644
@@ -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
doc/develop/bootstd/script.rst new file +49 -0

49 lines not on this page · raw message

Signature · 1 line
2.34.1
#40 lore raw

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

In reply to Simon Glass

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

---

 doc/develop/bootstd/overview.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/develop/bootstd/overview.rst +1 -1
index 7d31d5e6427..0d7454246f6 100644
@@ -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
Signature · 1 line
2.34.1
Reviewed-by on v1 11/13
#42 lore raw

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

In reply to Simon Glass
Quoted 13 lines · Simon Glass

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

---

  doc/develop/bootstd/overview.rst | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
doc/develop/bootstd/overview.rst +0 -0
index 7d31d5e6427..0d7454246f6 100644

doc/develop/bootstd/overview.rst Bootmeth drivers are provided for: · line 420

Quoted 6 lines
doc/develop/bootstd/overview.rst +1 -1
@@ -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/develop/bootstd/overview.rst Bootmeth drivers are provided for: · line 422

Quoted 1 line
doc/develop/bootstd/overview.rst +0 -0
     - :doc:`QFW <qfw>`: QEMU firmware interface
#43 lore raw

PATCH 12/13 boot: Correct indentation in efi bootmeth

In reply to Simon Glass

Fix a minor indentation / whitespace problem in a comment.

---

 boot/bootmeth_efi.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
boot/bootmeth_efi.c +1 -1
index 56a6e47f5b2..39232eb2e25 100644
@@ -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);
Signature · 1 line
2.34.1
Reviewed-by on v1 12/13
#45 lore raw

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

In reply to Simon Glass
Quoted 3 lines · Simon Glass

Fix a minor indentation / whitespace problem in a comment.

Quoted 18 lines

---

  boot/bootmeth_efi.c | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
boot/bootmeth_efi.c +1 -1
index 56a6e47f5b2..39232eb2e25 100644
@@ -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);
Reviewed-by on v1 12/13
#46 lore raw

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

In reply to Simon Glass
Quoted 23 lines · Simon Glass

Fix a minor indentation / whitespace problem in a comment.

---

 boot/bootmeth_efi.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
boot/bootmeth_efi.c +1 -2
index 56a6e47f5b2..39232eb2e25 100644
@@ -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);
--
Quoted 2 lines

2.34.1

#47 lore raw

PATCH 13/13 doc: Describe the bootstd settings

In reply to Simon Glass

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

---

 doc/develop/bootstd/overview.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)
doc/develop/bootstd/overview.rst +13 -0
index 0d7454246f6..f3caf8b7956 100644
@@ -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
 --------------------------
Signature · 1 line
2.34.1