Add 'bootsource' /chosen property

Bootloaders typically can be loaded from different storage media, such
as eMMC, SD card, SPI flash, EEPROM, but also from non-persistent media
such as USB (via proprietary protocols loading directly into SRAM, or
fastboot, DFU, etc..), JTAG, ...

This information is usually reported by the SoC-ROM via some proprietary
mechanism (some specific address in registers/DRAM for example).

It would be useful to know which medium was used to load the first stage
of the bootloader. SoC-ROM shall be ignored and not reported in this
property.

This can allow client programs to detect which medium to write to when
updating the boot program, or detect if fallback mechanisms to
unexpected medium were used to reach the client program's execution.

In cases where a boot program is split into multiple stages (like
U-Boot), it only represents the device that was used to load the very
first stage (in case of U-Boot, VPL/TPL/SPL whichever is executed first)
and not any of the later stages (in case of U-Boot, TPL/SPL/proper) or
any client program. They may match, but they may not and this property
is meant to only represent the device used for loading the very first
stage.

I have a board running U-Boot which currently has 9 boot scenarios
(eMMC/SD/SPI-NOR for the first stage, eMMC/SD/SPI-NOR for the next
stages; not counting USB loading yet, which would make it a few more). I
cannot force the BootROM of this board to select a specific device aside
from erasing the other media.
The only way to identify which device was used for the first stage is to
parse U-Boot first stage console output or add some custom logic for my
board. To validate that a new version of the bootloader works, including
the fallback mechanisms, I need to make sure the BootROM loads the first
stage from the expected device otherwise I may have false positives.
This would be useful for automated testing.

I could also very well see this being used to identify where the first
stage of the boot program is stored (which may differ from where the
later stages are! that's the case for U-Boot proper for example!) to be
able to update it from a client program.

Note that Barebox has been using this property for a while already, with
this very content[1].

This is chosen as a string so that it matches other properties in
/chosen (e.g. stdout-path) as well as allows for extending it, in case
one needs to provide additional information (e.g. HW boot partition for
eMMC, a specific disk on an AHCI controller, a specific USB device on
a USB bus, etc.).

[1] https://lore.kernel.org/u-boot/[email protected]/

Signed-off-by: Quentin Schulz <[email protected]>
Reviewed-by: Simon Glass <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Rob Herring (Arm) <[email protected]>

Author: QSchulz

source/chapter3-devicenodes.rst

@@ -457,6 +457,23 @@ time. It shall be a child of the root node.
                                                        the client program. The value could
                                                        potentially be a null string if no boot
                                                        arguments are required.
+   ``bootsource``          O     ``<string>``          A string that specifies the full path to the
+                                                       node representing the device the BootROM used
+                                                       to load the initial boot program.
+                                                       If the initial boot program is split into
+                                                       multiple stages, this represents the storage
+                                                       medium or device (e.g. used by fastboot) from
+                                                       which the very first stage was loaded by the
+                                                       BootROM.
+                                                       It may differ from the device from which later
+                                                       stages of the boot program or client program
+                                                       are loaded from, as this property isn't meant
+                                                       to represent those devices.
+                                                       A later stage of the boot program, or the
+                                                       client program, may use this information to
+                                                       favor the device in this property over others
+                                                       for loading later stages, or know the storage
+                                                       medium to flash an update to.
    ``stdout-path``         O     ``<string>``          A string that specifies the full path to the
                                                        node representing the device to be used for
                                                        boot console output. If the character ":" is