From: Quentin Schulz <quentin.sch...@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-00ea7e255...@pengutronix.de/ Signed-off-by: Quentin Schulz <quentin.sch...@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-95f4ba69a...@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.sch...@cherry.de>
