[PATCH v2] Add 'bootsource' /chosen property

[PATCH v2] Add 'bootsource' /chosen property

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@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@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@cherry.de>

Re: [PATCH v2] Add 'bootsource' /chosen property

[Simon Glass]

On Mon, 5 May 2025 at 09:34, Quentin Schulz <foss+dt@0leil.net> wrote:
>
> From: Quentin Schulz <quentin.schulz@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@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(+)
>

Reviewed-by: Simon Glass <sjg@chromium.org>

Does this need to go into the schema as well?

- Simon

> 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@cherry.de>
>

Re: [PATCH v2] Add 'bootsource' /chosen property

[Quentin Schulz]

Hi Simon,

On 6/10/25 4:26 PM, Simon Glass wrote:
> On Mon, 5 May 2025 at 09:34, Quentin Schulz <foss+dt@0leil.net> wrote:
>>
>> From: Quentin Schulz <quentin.schulz@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@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(+)
>>
> 
> Reviewed-by: Simon Glass <sjg@chromium.org>
> 
> Does this need to go into the schema as well?
> 

Considering this should ever only be programmatically set at runtime, 
I'm not sure this is necessary?

But taking into account that u-boot,version is part of the schema, I 
guess this could too :)

Cheers,
Quentin

Re: [PATCH v2] Add 'bootsource' /chosen property

[Rob Herring]

On Tue, Jun 10, 2025 at 9:52 AM Quentin Schulz <quentin.schulz@cherry.de> wrote:
>
> Hi Simon,
>
> On 6/10/25 4:26 PM, Simon Glass wrote:
> > On Mon, 5 May 2025 at 09:34, Quentin Schulz <foss+dt@0leil.net> wrote:
> >>
> >> From: Quentin Schulz <quentin.schulz@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@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(+)
> >>
> >
> > Reviewed-by: Simon Glass <sjg@chromium.org>
> >
> > Does this need to go into the schema as well?
> >
>
> Considering this should ever only be programmatically set at runtime,
> I'm not sure this is necessary?
>
> But taking into account that u-boot,version is part of the schema, I
> guess this could too :)

Validation can and does run on booted systems, so yes.

There's also a (unresourced) goal to generate the spec from the
schemas. No one seems to care enough to make that happen any time soon
though.

Rob

Re: [PATCH v2] Add 'bootsource' /chosen property

[Quentin Schulz]

Hi all,

On 6/10/25 5:29 PM, Rob Herring wrote:
> On Tue, Jun 10, 2025 at 9:52 AM Quentin Schulz <quentin.schulz@cherry.de> wrote:
>>
>> Hi Simon,
>>
>> On 6/10/25 4:26 PM, Simon Glass wrote:
>>> On Mon, 5 May 2025 at 09:34, Quentin Schulz <foss+dt@0leil.net> wrote:
>>>>
>>>> From: Quentin Schulz <quentin.schulz@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@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(+)
>>>>
>>>
>>> Reviewed-by: Simon Glass <sjg@chromium.org>
>>>
>>> Does this need to go into the schema as well?
>>>
>>
>> Considering this should ever only be programmatically set at runtime,
>> I'm not sure this is necessary?
>>
>> But taking into account that u-boot,version is part of the schema, I
>> guess this could too :)
> 
> Validation can and does run on booted systems, so yes.
> 

See https://github.com/devicetree-org/dt-schema/pull/169

Cheers,
Quentin