diff options
Diffstat (limited to 'doc/develop')
| -rw-r--r-- | doc/develop/board_best_practices.rst | 2 | ||||
| -rw-r--r-- | doc/develop/bootstd/cros.rst | 33 | ||||
| -rw-r--r-- | doc/develop/bootstd/extlinux.rst | 29 | ||||
| -rw-r--r-- | doc/develop/bootstd/index.rst | 15 | ||||
| -rw-r--r-- | doc/develop/bootstd/overview.rst (renamed from doc/develop/bootstd.rst) | 45 | ||||
| -rw-r--r-- | doc/develop/bootstd/pxelinux.rst | 27 | ||||
| -rw-r--r-- | doc/develop/bootstd/qfw.rst | 20 | ||||
| -rw-r--r-- | doc/develop/bootstd/sandbox.rst | 17 | ||||
| -rw-r--r-- | doc/develop/bootstd/script.rst | 52 | ||||
| -rw-r--r-- | doc/develop/index.rst | 2 |
10 files changed, 227 insertions, 15 deletions
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/cros.rst b/doc/develop/bootstd/cros.rst new file mode 100644 index 00000000000..85af10588c1 --- /dev/null +++ b/doc/develop/bootstd/cros.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +ChromiumOS Bootmeth +=================== + +ChromiumOS provides a mechanism for booting its Operating System from a block +device, described +`here <https://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot/>`_. + +U-Boot includes support for reading the associated data structures from the +device and identifying a bootable ChromiumOS image. This structure includes the +kernel itself, boot arguments (kernel command line), as well as the x86 setup +block (for x86 only). + +When invoked on a bootdev, this bootmeth searches for kernel partitions with +the appropriate GUID (Globally Unique Identifier). When found, the information +is loaded and a bootflow is created. + +When the bootflow is booted, the bootmeth reads the kernel and boot arguments. +It then boots the kernel using zboot (on x86) or bootm (on ARM). The boot +arguments are adjusted to replace `%U` with the UUID of the selected kernel +partition. This results in the correct root disk being used, which is the next +partition after the kernel partition. + +For ARM, a :doc:`/usage/fit/index` is used. The `CONFIG_FIT_BEST_MATCH` option +must be enabled for U-Boot to select the correct devicetree to boot with. + +Note that a ChromiumOS image typically has two copies of the Operating System, +each with its own kernel and root disk. There is no initial ramdisk (initrd). +This means that this bootmeth typically locates two separate images. + +The compatible string "u-boot,cros" is used for the driver. It is present +if `CONFIG_BOOTMETH_CROS` is enabled. diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst new file mode 100644 index 00000000000..bf27dc57aaa --- /dev/null +++ b/doc/develop/bootstd/extlinux.rst @@ -0,0 +1,29 @@ +.. 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 :doc:`pxelinux` 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 new file mode 100644 index 00000000000..9d35b567d55 --- /dev/null +++ b/doc/develop/bootstd/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Standard Boot +============= + +.. toctree:: + :maxdepth: 2 + + overview + extlinux + pxelinux + qfw + cros + script + sandbox diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst index bdda90fae3f..ff3cc48eb64 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 -------- @@ -410,20 +410,39 @@ 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 -------------------------- -Bootmeth drivers are provided for: +Bootmeth drivers are provided for booting from various media: - - extlinux / syslinux boot from a disk - - extlinux boot from a network (PXE) - - U-Boot scripts from disk, network or SPI flash + - Android bootflow (boot image v4) + - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk - EFI boot using bootefi from disk - - VBE - EFI boot using boot manager - - Android bootflow (boot image v4) + - :doc:`extlinux / syslinux <extlinux>` boot from a storage device + - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE) + - :doc:`sandbox <sandbox>` used only for testing + - :doc:`U-Boot scripts <script>` from disk, network or SPI flash + - :doc:`QFW <qfw>`: QEMU firmware interface + - :doc:`VBE </develop/vbe>`: Verified Boot for Embedded +Each driver is controlled by a Kconfig option. If no bootmeth driver is +selected by a compatible string in the devicetree, all available bootmeth +drivers are bound automatically. Command interface ----------------- @@ -432,16 +451,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/bootstd/pxelinux.rst b/doc/develop/bootstd/pxelinux.rst new file mode 100644 index 00000000000..c4b7fbb4c9c --- /dev/null +++ b/doc/develop/bootstd/pxelinux.rst @@ -0,0 +1,27 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +PXE Bootmeth +============ + +PXE (Preboot eXecution-Environment) provides a way to boot an operating system +over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to +provide a menu of possible Operating Systems from which the user can choose. + +U-Boot includes a parser for the `extlinux.conf` file described +`here <https://uapi-group.org/specifications/specs/boot_loader_specification>`_. +It consists primarily of a list of named operating systems along with the +kernel, initial ramdisk and other settings. The file is retrieved from a network +server using the TFTP protocol. + +When invoked on a bootdev, this bootmeth searches for the file and creates a +bootflow if found. See +`PXELINUX <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX>`_ for +a full description of the search procedure. + +When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up +the context, then ``pxe_process()`` to process the file. Depending on the +contents, this may boot an Operating System or provide a list of options to the +user, perhaps with a timeout. + +The compatible string "u-boot,extlinux-pxe" is used for the driver. It is +present if `CONFIG_BOOTMETH_EXTLINUX_PXE` is enabled. 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. 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. diff --git a/doc/develop/bootstd/script.rst b/doc/develop/bootstd/script.rst new file mode 100644 index 00000000000..47f3684b86b --- /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. 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 |