diff --git a/MAINTAINERS b/MAINTAINERS index 19ca57d200b..a6e47e8a217 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -918,7 +918,7 @@ F: drivers/block/blkmap.c F: include/blkmap.h F: test/dm/blkmap.c -BOOTDEVICE +BOOTSTD M: Simon Glass S: Maintained F: boot/bootdev*.c @@ -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/README b/README index b89768f1791..b76449b70a8 100644 --- a/README +++ b/README @@ -1684,26 +1684,6 @@ images ready for download to / installation on your system: - "u-boot" is an image in ELF binary format - "u-boot.srec" is in Motorola S-Record format -By default the build is performed locally and the objects are saved -in the source directory. One of the two methods can be used to change -this behavior and build U-Boot to some external directory: - -1. Add O= to the make command line invocations: - - make O=/tmp/build distclean - make O=/tmp/build NAME_defconfig - make O=/tmp/build all - -2. Set environment variable KBUILD_OUTPUT to point to the desired location: - - export KBUILD_OUTPUT=/tmp/build - make distclean - make NAME_defconfig - make all - -Note that the command line "O=" setting overrides the KBUILD_OUTPUT environment -variable. - User specific CPPFLAGS, AFLAGS and CFLAGS can be passed to the compiler by setting the according environment variables KCPPFLAGS, KAFLAGS and KCFLAGS. For example to treat all compiler warnings as errors: diff --git a/boot/bootmeth_efi.c b/boot/bootmeth_efi.c index 5a4c125835a..39232eb2e25 100644 --- a/boot/bootmeth_efi.c +++ b/boot/bootmeth_efi.c @@ -265,7 +265,7 @@ static int distro_efi_read_bootflow_net(struct bootflow *bflow) return log_msg_ret("sz", -EINVAL); bflow->size = size; - /* bootfile should be setup by dhcp*/ + /* bootfile should be setup by dhcp */ bootfile_name = env_get("bootfile"); if (!bootfile_name) return log_msg_ret("bootfile_name", ret); @@ -394,6 +394,7 @@ static const struct udevice_id distro_efi_bootmeth_ids[] = { { } }; +/* Put a number before 'efi' to provide a default ordering */ U_BOOT_DRIVER(bootmeth_4efi) = { .name = "bootmeth_efi", .id = UCLASS_BOOTMETH, diff --git a/boot/bootmeth_extlinux.c b/boot/bootmeth_extlinux.c index 9b55686948f..fbb05ef928e 100644 --- a/boot/bootmeth_extlinux.c +++ b/boot/bootmeth_extlinux.c @@ -183,7 +183,7 @@ static const struct udevice_id extlinux_bootmeth_ids[] = { { } }; -/* Put an number before 'extlinux' to provide a default ordering */ +/* Put a number before 'extlinux' to provide a default ordering */ U_BOOT_DRIVER(bootmeth_1extlinux) = { .name = "bootmeth_extlinux", .id = UCLASS_BOOTMETH, diff --git a/boot/bootmeth_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/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/boot/bootmeth_script.c b/boot/bootmeth_script.c index 0e05d28d4d9..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); @@ -250,7 +261,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, 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/build/gcc.rst b/doc/build/gcc.rst index 3c646577272..d8fcfdc4bf2 100644 --- a/doc/build/gcc.rst +++ b/doc/build/gcc.rst @@ -118,6 +118,34 @@ Assuming cross compiling on Debian for ARMv8 this would be CROSS_COMPILE=aarch64-linux-gnu- make +Out-of-tree building +~~~~~~~~~~~~~~~~~~~~ + +By default building is performed locally and the objects are saved in the source +directory. To build out-out-tree use one of the two methods below: + +Add O= parameter to the make command line: + +.. code-block:: bash + + make O=/tmp/build distclean + make O=/tmp/build NAME_defconfig + make O=/tmp/build + +Use environment variable KBUILD_OUTPUT: + +.. code-block:: bash + + export KBUILD_OUTPUT=/tmp/build + make distclean + make NAME_defconfig + make + +.. note:: + + The command line "O=" parameter overrides the KBUILD_OUTPUT environment + variable. + Build parameters ~~~~~~~~~~~~~~~~ diff --git a/doc/conf.py b/doc/conf.py index c9138a5a5d4..e79134cc3d7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -21,6 +21,12 @@ from subprocess import check_output # Get Sphinx version major, minor, patch = sphinx.version_info[:3] +# Set canonical URL from the Read the Docs Domain +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "") + +# Tell Jinja2 templates the build is running on Read the Docs +if os.environ.get("READTHEDOCS", "") == "True": + html_context["READTHEDOCS"] = True # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the 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 `_. + +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 `_ +(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 similarity index 95% rename from doc/develop/bootstd.rst rename to 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 - - EFI boot using bootefi from disk - - VBE - - EFI boot using boot manager - Android bootflow (boot image v4) + - :doc:`ChromiumOS ` ChromiumOS boot from a disk + - EFI boot using bootefi from disk + - EFI boot using boot manager + - :doc:`extlinux / syslinux ` boot from a storage device + - :doc:`extlinux / syslinux ` boot from a network (PXE) + - :doc:`sandbox ` used only for testing + - :doc:`U-Boot scripts