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

Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Quentin Schulz quentin.schulz@cherry.de Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com ---

(no changes since v1)

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

diff --git a/MAINTAINERS b/MAINTAINERS index 9bee9284cca..86b830aa997 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -927,7 +927,7 @@ F: boot/bootmeth*.c F: boot/bootstd.c F: cmd/bootdev.c F: cmd/bootflow.c -F: doc/develop/bootstd.rst +F: doc/develop/bootstd/ F: doc/usage/bootdev.rst F: doc/usage/bootflow.rst F: doc/usage/bootmeth.rst diff --git a/doc/board/starfive/milk-v_mars_cm.rst b/doc/board/starfive/milk-v_mars_cm.rst index b31de6043bb..52d4e5e9098 100644 --- a/doc/board/starfive/milk-v_mars_cm.rst +++ b/doc/board/starfive/milk-v_mars_cm.rst @@ -89,7 +89,7 @@ provide a default value.

The variable *$fdtfile* is used in the boot process to automatically load a device-tree provided by the operating system. For details of the boot -process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>` +process refer to the :doc:`/develop/bootstd/index` description.

Boot source selection diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst index f44401eab7d..09632c80ce7 100644 --- a/doc/develop/board_best_practices.rst +++ b/doc/develop/board_best_practices.rst @@ -7,7 +7,7 @@ In addition to the regular best practices such as using :doc:`checkpatch` and following the :doc:`docstyle` and the :doc:`codingstyle` there are some things which are specific to creating a new board port.

-* Implement :doc:`bootstd` to ensure that most operating systems will be +* Implement :doc:`bootstd/index` to ensure that most operating systems will be supported by the platform.

* The platform defconfig file must be generated via `make savedefconfig`. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst new file mode 100644 index 00000000000..f4f87c7787c --- /dev/null +++ b/doc/develop/bootstd/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Standard Boot +============= + +.. toctree:: + :maxdepth: 2 + + overview diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst similarity index 99% rename from doc/develop/bootstd.rst rename to doc/develop/bootstd/overview.rst index 34631089ae0..761f61a573b 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd/overview.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0+:

-U-Boot Standard Boot -==================== +Standard Boot Overview +======================

Introduction ------------ @@ -17,7 +17,7 @@ introduces the following concepts: For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible for creating a bootflow for each kernel combination that it wants to offer. These bootflows are stored on media so they can be discovered by U-Boot. This -feature is typically called `distro boot` (see :doc:`distro`) because it is +feature is typically called `distro boot` (see :doc:`../distro`) because it is a way for distributions to boot on any hardware.

Traditionally U-Boot has relied on scripts to implement this feature. See @@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to different Operating Systems (such as Chromium OS) and devices (beyond just block and network devices). It supports EFI boot and EFI bootmgr too.

-Finally, standard boot supports the operation of :doc:`vbe`. +Finally, standard boot supports the operation of :doc:`../vbe`.

Bootflow -------- @@ -427,16 +427,16 @@ Three commands are available:

`bootdev` Allows listing of available bootdevs, selecting a particular one and - getting information about it. See :doc:`../usage/cmd/bootdev` + getting information about it. See :doc:`/usage/cmd/bootdev`

`bootflow` Allows scanning one or more bootdevs for bootflows, listing available bootflows, selecting one, obtaining information about it and booting it. - See :doc:`../usage/cmd/bootflow` + See :doc:`/usage/cmd/bootflow`

`bootmeth` Allow listing of available bootmethds and setting the order in which they - are tried. See :doc:`../usage/cmd/bootmeth` + are tried. See :doc:`/usage/cmd/bootmeth`

.. _BootflowStates:

diff --git a/doc/develop/index.rst b/doc/develop/index.rst index f9c4bf839ee..c0107a783fc 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -29,7 +29,7 @@ Implementation

directories bloblist - bootstd + bootstd/index ci_testing commands config_binding diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst index f759abab354..98a0f43c580 100644 --- a/doc/usage/cmd/bootdev.rst +++ b/doc/usage/cmd/bootdev.rst @@ -22,7 +22,7 @@ Description The `bootdev` command is used to manage bootdevs. It can list available bootdevs, select one and obtain information about it.

-See :doc:`../../develop/bootstd` for more information about bootdevs in general. +See :doc:`/develop/bootstd/index` for more information about bootdevs in general.

bootdev list diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst index 6519e4880a9..5d41fe37a7a 100644 --- a/doc/usage/cmd/bootflow.rst +++ b/doc/usage/cmd/bootflow.rst @@ -26,7 +26,7 @@ Description The `bootflow` command is used to manage bootflows. It can scan bootdevs to locate bootflows, list them and boot them.

-See :doc:`../../develop/bootstd` for more information. +See :doc:`/develop/bootstd/index` for more information.

Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL) must be enabled to obtain full functionality with this command. Otherwise, it only diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst index bac9fdf85cd..c3d2ec1574b 100644 --- a/doc/usage/cmd/bootmeth.rst +++ b/doc/usage/cmd/bootmeth.rst @@ -21,7 +21,7 @@ Description The `bootmeth` command is used to manage bootmeths. It can list them and change the order in which they are used.

-See :doc:`../../develop/bootstd` for more information. +See :doc:`/develop/bootstd/index` for more information.

.. _bootmeth_order: diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 7d4b448cb30..cc33d3ec0f2 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -100,7 +100,7 @@ to add environment variables.

Board maintainers are encouraged to migrate to the text-based environment as it is easier to maintain. The distro-board script still requires the old-style -environments, so use :doc:`../develop/bootstd` instead. +environments, so use :doc:`/develop/bootstd/index` instead.

List of environment variables

Add documentation for the extlinux bootmeth.

Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Quentin Schulz quentin.schulz@cherry.de Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com ---

Changes in v3: - Use quoting on list and function names

Changes in v2: - Adjustments from Heinrich's comments

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

diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst new file mode 100644 index 00000000000..46e9ad9eea1 --- /dev/null +++ b/doc/develop/bootstd/extlinux.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Extlinux Bootmeth +================= + +`Extlinux https://uapi-group.org/specifications/specs/boot_loader_specification`_ +(sometimes called syslinux) allows U-Boot to provide a menu of available +operating systems from which the user can choose. + +U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of +a list of named operating systems along with the kernel, initial ramdisk and +other settings. The file is stored in the `extlinux/` subdirectory, possibly +under the `boot/` subdirectory. This list of prefixes (``{"/", "/boot"}`` by +default) can be selected with the `filename-prefixes` property in the bootstd +device. + +Note that the PXE bootmeth uses the same file format, but in a network context. + +When invoked on a bootdev, this bootmeth searches for the file and creates a +bootflow if found. + +When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up +the context, then ``pxe_process()`` to process the file. Depending on the +contents, this may boot an operating system or provide a list of options to +the user, perhaps with a timeout. + +The compatible string "u-boot,extlinux" is used for the driver. It is present +if `CONFIG_BOOTMETH_EXTLINUX` is enabled. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index f4f87c7787c..5bbb3d633a3 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -7,3 +7,4 @@ Standard Boot :maxdepth: 2

overview + extlinux diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index d5051e986bb..7af159b9ca8 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -410,9 +410,9 @@ a good selection of boot options is available. Available bootmeth drivers --------------------------

-Bootmeth drivers are provided for: +Bootmeth drivers are provided for booting from various media:

- - extlinux / syslinux boot from a disk + - :doc:`extlinux / syslinux <extlinux>` boot from a storage device - extlinux boot from a network (PXE) - U-Boot scripts from disk, network or SPI flash - EFI boot using bootefi from disk

Add documentation for the qfw bootmeth.

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

Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Quentin Schulz quentin.schulz@cherry.de Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com ---

Changes in v3: - Drop extra 'and'

Changes in v2: - Adjustments from Heinrich's comments

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

diff --git a/boot/bootmeth_qfw.c b/boot/bootmeth_qfw.c index dfaa944594e..2f8e00cf350 100644 --- a/boot/bootmeth_qfw.c +++ b/boot/bootmeth_qfw.c @@ -88,7 +88,7 @@ static struct bootmeth_ops qfw_bootmeth_ops = { };

static const struct udevice_id qfw_bootmeth_ids[] = { - { .compatible = "u-boot,qfw-extlinux" }, + { .compatible = "u-boot,qfw-bootmeth" }, { } };

diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 5052afe448f..f8fce7207ce 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -9,3 +9,4 @@ Standard Boot overview extlinux pxelinux + qfw diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index b9b45f1e7a7..f23e344546d 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -418,6 +418,7 @@ Bootmeth drivers are provided for booting from various media: - EFI boot using bootefi from disk - VBE - EFI boot using boot manager + - :doc:`QFW <qfw>`: QEMU firmware interface

Each driver is controlled by a Kconfig option. If no bootmeth driver is selected by a compatible string in the devicetree, all available bootmeth diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst new file mode 100644 index 00000000000..70086ad1817 --- /dev/null +++ b/doc/develop/bootstd/qfw.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +QFW Bootmeth +============ + +`QEMU hhttps://www.qemu.org/`_ is a system emulator which is able to boot +Operating Systems. QEMU provides specific support for booting an OS image +provided on the QEMU command line. + +When invoked on a bootdev for UCLASS_QFW, this bootmeth reads the kernel +provided by the QEMU `-kernel` argument, the initial ramdisk provided by +`-initrd` and the boot arguments (command line) provided by `-append` into +memory ready for booting. + +When the bootflow is booted, the bootmeth tries the `booti` command first, then +falls back to the `bootz` command. U-Boot's 'control' devicetree is passed +through to the kernel. + +The compatible string "u-boot,qfw-bootmeth" is used for the driver. It is +present if `CONFIG_QFW` is enabled.

Add documentation for the sandbox bootmeth.

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

Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Quentin Schulz quentin.schulz@cherry.de Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com ---

Changes in v3: - Fix EENOTSUPP typo and add quotes

Changes in v2: - Adjustments from Heinrich's comments

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

diff --git a/boot/bootmeth_sandbox.c b/boot/bootmeth_sandbox.c index 0bc8f688e30..26c713bb5f3 100644 --- a/boot/bootmeth_sandbox.c +++ b/boot/bootmeth_sandbox.c @@ -55,7 +55,7 @@ static struct bootmeth_ops sandbox_bootmeth_ops = { };

static const struct udevice_id sandbox_bootmeth_ids[] = { - { .compatible = "u-boot,sandbox-extlinux" }, + { .compatible = "u-boot,sandbox-bootmeth" }, { } };

diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 69fd3c2d2eb..2c5d2d3fade 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -11,3 +11,4 @@ Standard Boot pxelinux qfw cros + sandbox diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 9b50b5593c4..add054f3088 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -420,6 +420,7 @@ Bootmeth drivers are provided for booting from various media: - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk - EFI boot using boot manager - :doc:`QFW <qfw>`: QEMU firmware interface + - :doc:`sandbox <sandbox>` used only for testing

Each driver is controlled by a Kconfig option. If no bootmeth driver is selected by a compatible string in the devicetree, all available bootmeth diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst new file mode 100644 index 00000000000..d501518c39a --- /dev/null +++ b/doc/develop/bootstd/sandbox.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Sandbox Bootmeth +================ + +The sandbox bootmeth is only used for testing. It does not provide any facility +for booting an OS. While sandbox can do all the processing before the actual +boot, it is not connected in this bootmeth. + +When invoked on a bootdev, this bootmeth pretends to find a bootflow and creates +the associated structure. + +When the bootflow is booted, the bootmeth returns `-ENOTSUPP` indicating that it +is not supported. + +The compatible string "u-boot,sandbox-bootmeth" is used for the driver. It is present +if `CONFIG_BOOTMETH_SANDBOX` is enabled.

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

Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com ---

(no changes since v1)

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

diff --git a/boot/bootmeth_script.c b/boot/bootmeth_script.c index 24da47c7259..c5cbf18c2e6 100644 --- a/boot/bootmeth_script.c +++ b/boot/bootmeth_script.c @@ -185,31 +185,42 @@ static int script_set_bootflow(struct udevice *dev, struct bootflow *bflow,

static int script_boot(struct udevice *dev, struct bootflow *bflow) { - struct blk_desc *desc = dev_get_uclass_plat(bflow->blk); + struct blk_desc *desc; ulong addr; int ret = 0;

- if (desc->uclass_id == UCLASS_USB) { - ret = env_set("devtype", "usb"); + if (bflow->blk) { + desc = dev_get_uclass_plat(bflow->blk); + if (desc->uclass_id == UCLASS_USB) { + ret = env_set("devtype", "usb"); + } else { + /* + * If the uclass is AHCI, but the driver is ATA + * (not scsi), set devtype to sata + */ + if (IS_ENABLED(CONFIG_SATA) && + desc->uclass_id == UCLASS_AHCI) + ret = env_set("devtype", "sata"); + else + ret = env_set("devtype", blk_get_devtype(bflow->blk)); + } + if (!ret) + ret = env_set_hex("devnum", desc->devnum); + if (!ret) + ret = env_set_hex("distro_bootpart", bflow->part); + if (!ret) + ret = env_set("prefix", bflow->subdir); + if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) && + !strcmp("mmc", blk_get_devtype(bflow->blk))) + ret = env_set_hex("mmc_bootdev", desc->devnum); } else { - /* If the uclass is AHCI, but the driver is ATA - * (not scsi), set devtype to sata - */ - if (IS_ENABLED(CONFIG_SATA) && - desc->uclass_id == UCLASS_AHCI) - ret = env_set("devtype", "sata"); - else - ret = env_set("devtype", blk_get_devtype(bflow->blk)); + const struct udevice *media = dev_get_parent(bflow->dev); + + ret = env_set("devtype", + uclass_get_name(device_get_uclass_id(media))); + if (!ret) + ret = env_set_hex("devnum", dev_seq(media)); } - if (!ret) - ret = env_set_hex("devnum", desc->devnum); - if (!ret) - ret = env_set_hex("distro_bootpart", bflow->part); - if (!ret) - ret = env_set("prefix", bflow->subdir); - if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) && - !strcmp("mmc", blk_get_devtype(bflow->blk))) - ret = env_set_hex("mmc_bootdev", desc->devnum); if (ret) return log_msg_ret("env", ret);

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

Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Heinrich Schuchardt xypron.glpk@gmx.de Reviewed-by: Quentin Schulz quentin.schulz@cherry.de Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com ---

(no changes since v1)

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

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

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

Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Quentin Schulz quentin.schulz@cherry.de Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com ---

(no changes since v1)

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

diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 4a55b7da00a..d92a649beb0 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -406,6 +406,19 @@ You should probably also enable `CONFIG_BOOTSTD_DEFAULTS`, which provides several filesystem and network features (if `CONFIG_NET` is enabled) so that a good selection of boot options is available.

+Some devicetree properties are supported in the bootstd node when +`CONFIG_BOOTSTD_FULL` is enabled: + + filename-prefixes + List of prefixes to use when searching for files on block devices. This + defaults to {"/", "/boot/"} if not provided. + + bootdev-order + Lists the bootdev ordering to use. Note that the deprecated + `boot_targets` environment variable overrides this, if present. + + theme (subnode) + Sets the theme to use for menus. See :doc:`/develop/expo`.

Available bootmeth drivers --------------------------