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

[Mattijs Korpershoek]

Hi Simon,

Thank you for the patch.

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

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

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

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