[PATCH v2] Add 'bootsource' /chosen property

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz at cherry.de>

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/0066fcc2-3431-48be-8dc2-00ea7e2550c2@pengutronix.de/

Signed-off-by: Quentin Schulz <quentin.schulz at cherry.de>
---
Note that this property is already set by Barebox and I'm planning on
adding it to U-Boot as well, specifically for Rockchip SoCs.

I have some doubts about the wording, especially in the case of
hypervisors or chained boot programs. I'm not entirely sure what would
make the most sense to put in the property for those scenario.
---
Changes in v2:
- added usecases, non-usecases and increased verbosity of the definition
  of the property name as requested by Simon,
- Link to v1: https://lore.kernel.org/r/20250205-bootsource-v1-1-95f4ba69ac27@cherry.de
---
 source/chapter3-devicenodes.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
index 8080321d6e60d6b1e86c81af86c6850246a0223b..98cab42c105d9a390f74a6f80fb2bba61d5bb919 100644
--- a/source/chapter3-devicenodes.rst
+++ b/source/chapter3-devicenodes.rst
@@ -456,6 +456,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

---
base-commit: 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f
change-id: 20250205-bootsource-84df255e9e6c

Best regards,
-- 
Quentin Schulz <quentin.schulz at cherry.de>