[PATCH 0/2] allow control DTB to double as "FIT image"

[PATCH 0/2] allow control DTB to double as "FIT image"

[Rasmus Villemoes]

The commit message for patch 1 explains what it is I'd like to be able
to do, but here's some more background:

For a long time, we've embedded the boot script in the U-Boot binary
by building a bootscript.itb, and using a .dtsi like

  / {
          config {
                 bootscript = /incbin/("/path/to/bootscript.itb");
          };
  };

which in turn is mentioned in CONFIG_DEVICE_TREE_INCLUDES, that
bootscript.itb FIT image has been embedded in U-Boot's control
dtb. Running that was then a matter of doing

  fdt addr ${fdtcontroladdr} && fdt get addr bsaddr /config bootscript && source ${bsaddr}

There are a couple of advantage of having the bootscript (and other
script logic) embedded in the U-Boot binary. First, there's no need to
figure out some separate partition to store the script in, and making
sure that gets updated whenever the bootloader itself does. Second,
one doesn't need to worry about verifying the script; whatever steps
one needs to take to implement secure boot for U-Boot itself will by
necessity also cover the control dtb (if nothing else then because
that's where the public key for the kernel verification lives).

Now with the stricter requirements of libfdt starting from v2026.04,
the above command no longer worked, or only half the time, because the
embedded FIT image may not land on an 8-byte aligned address. So that
line had to be changed a little (line breaks added)

  fdt addr ${fdtcontroladdr}
    && fdt get addr bsaddr /config bootscript
    && fdt get size bssize /config bootscript
    && cp.b ${bsaddr} ${loadaddr} ${bssize}
    && source ${loadaddr}

which is getting quite unwieldy.

Then it struck me that one could perhaps simplify all of this quite a
lot: Cut out the intermediate bootscript.itb, just create a .dtsi
which directly puts a /images node inside the control dtb

/ {
  	images {
		default = "bootscript";
		bootscript {
			description = "Boot script";
			data = /incbin/("/path/to/bootscript.sh");
			type = "script";
			compression = "none";
		};
	};
};

and treat the control dtb itself as a FIT image; so the command to put
in $bootcmd becomes simply

  source ${fdtcontroladdr}:bootscript

and embedding other pieces of callable scripts is quite trivial.

And that almost works out-of-the-box, except for the fit_check_format() sanity check.

I realize this is a bit of a hack, but I do think it's somewhat
elegant, and avoids inventing a whole lot of extra infrastructure for
allowing one to embed larger scripts and invoke them from the shell. I
am of course happy to put this exemption for gd->fdt_blob under a
CONFIG_ knob if that is deemed necessary.

CI is half-way through (and past the sandbox testing that would
exercise this) and seems happy:
https://github.com/u-boot/u-boot/pull/969

Rasmus Villemoes (2):
  image-board.c: exempt gd->fdt_blob from fit_check_format() check
  test: hook up test of allowing control DTB to act as FIT image

 arch/sandbox/dts/sandbox-test1.sh     |  4 ++++
 arch/sandbox/dts/sandbox-test2.sh     |  4 ++++
 arch/sandbox/dts/sandbox_scripts.dtsi | 18 ++++++++++++++++++
 boot/image-board.c                    |  2 +-
 configs/sandbox_defconfig             |  1 +
 test/py/tests/test_source.py          | 12 ++++++++++++
 6 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 arch/sandbox/dts/sandbox-test1.sh
 create mode 100644 arch/sandbox/dts/sandbox-test2.sh
 create mode 100644 arch/sandbox/dts/sandbox_scripts.dtsi

-- 
2.54.0

[PATCH 1/2] image-board.c: exempt gd->fdt_blob from fit_check_format() check

[Rasmus Villemoes]

Having scripts embedded one way or the other in the U-Boot binary
means they are automatically verified/trusted by whatever mechanism
verifies U-Boot.

Writing those scripts in the built-in environment leads to
backslatitis and missing or wrong quoting and is generally not very
readable or maintainable.

Maintaining scripts in external files allows one
to have both syntax highlighting and to some extent apply shellcheck
on it (though U-Boot's shell is of course not quite POSIX sh, so some
'#shellcheck disable' directives are needed). Getting those into the
U-Boot binary is then a matter of having a suitable .dtsi file such as

/ {
	images {
		default = "boot";
		boot {
			description = "Bootscript";
			data = /incbin/("boot.sh");
			type = "script";
			compression = "none";
		};
		factory-reset {
			description = "Script for performing factory reset";
			data = /incbin/("factory-reset.sh");
			type = "script";
			compression = "none";
		};
	};
};

and making that part of CONFIG_DEVICE_TREE_INCLUDES, so that U-Boot's
control DTB effectively doubles as a FIT image containing a few
"script" entries. At run-time, one's default bootcommand can then
simply be

  source ${fdtcontroladdr}:boot

Except of course that the control DTB is in fact not quite a FIT
image. The lack of timestamp and description properties could
potentially be worked around, but the no-@ check is not possible to
get around. But since the control dtb is by definition trusted, we can
just excempt that particular address from the strict check.

One can of course build an ordinary FIT image with those
scripts. However, that requires extra steps in the boot command for
loading that script from storage, requires one to use "configurations"
for pointing at a single script to run, and signing the FIT image
using the same key used for verifying the kernel. Moreover, in certain
situations, such as bootstrapping/production, there is no place to
load that FIT image from, and it is much simpler to just have the
necessary scripts be part of the U-Boot image itself.

Signed-off-by: Rasmus Villemoes <ravi@prevas.dk>
---
 boot/image-board.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/boot/image-board.c b/boot/image-board.c
index 005d60caf5c..6cbc489be01 100644
--- a/boot/image-board.c
+++ b/boot/image-board.c
@@ -1037,7 +1037,7 @@ int image_locate_script(void *buf, int size, const char *fit_uname,
 			goto exit_image_format;
 		} else {
 			fit_hdr = buf;
-			if (fit_check_format(fit_hdr, IMAGE_SIZE_INVAL)) {
+			if (fit_hdr != gd->fdt_blob && fit_check_format(fit_hdr, IMAGE_SIZE_INVAL)) {
 				puts("Bad FIT image format\n");
 				return 1;
 			}
-- 
2.54.0

[PATCH 2/2] test: hook up test of allowing control DTB to act as FIT image

[Rasmus Villemoes]

Add a test demonstrating how one can embed various scripts in the
control DTB and verifying that the source command can be used with
${fdtcontroladdr}.

Signed-off-by: Rasmus Villemoes <ravi@prevas.dk>
---
 arch/sandbox/dts/sandbox-test1.sh     |  4 ++++
 arch/sandbox/dts/sandbox-test2.sh     |  4 ++++
 arch/sandbox/dts/sandbox_scripts.dtsi | 18 ++++++++++++++++++
 configs/sandbox_defconfig             |  1 +
 test/py/tests/test_source.py          | 12 ++++++++++++
 5 files changed, 39 insertions(+)
 create mode 100644 arch/sandbox/dts/sandbox-test1.sh
 create mode 100644 arch/sandbox/dts/sandbox-test2.sh
 create mode 100644 arch/sandbox/dts/sandbox_scripts.dtsi

diff --git a/arch/sandbox/dts/sandbox-test1.sh b/arch/sandbox/dts/sandbox-test1.sh
new file mode 100644
index 00000000000..9d65a71bd7b
--- /dev/null
+++ b/arch/sandbox/dts/sandbox-test1.sh
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+echo "aaa"
+source ${fdtcontroladdr}:test2
+echo "ccc"
diff --git a/arch/sandbox/dts/sandbox-test2.sh b/arch/sandbox/dts/sandbox-test2.sh
new file mode 100644
index 00000000000..c84a0a3b97d
--- /dev/null
+++ b/arch/sandbox/dts/sandbox-test2.sh
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+
+# Some comment.
+echo "bbb"
diff --git a/arch/sandbox/dts/sandbox_scripts.dtsi b/arch/sandbox/dts/sandbox_scripts.dtsi
new file mode 100644
index 00000000000..f54c95b72b3
--- /dev/null
+++ b/arch/sandbox/dts/sandbox_scripts.dtsi
@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+/ {
+	images {
+		default = "test";
+		test1 {
+			description = "Testscript";
+			data = /incbin/("sandbox-test1.sh");
+			type = "script";
+			compression = "none";
+		};
+		test2 {
+			description = "Another testscript";
+			data = /incbin/("sandbox-test2.sh");
+			type = "script";
+			compression = "none";
+		};
+	};
+};
diff --git a/configs/sandbox_defconfig b/configs/sandbox_defconfig
index 55dc7845544..083383eea2b 100644
--- a/configs/sandbox_defconfig
+++ b/configs/sandbox_defconfig
@@ -154,6 +154,7 @@ CONFIG_CMD_SPAWN=y
 CONFIG_MAC_PARTITION=y
 CONFIG_OF_CONTROL=y
 CONFIG_OF_LIVE=y
+CONFIG_DEVICE_TREE_INCLUDES="sandbox_scripts.dtsi"
 CONFIG_ENV_IS_NOWHERE=y
 CONFIG_ENV_IS_IN_FAT=y
 CONFIG_ENV_IS_IN_EXT4=y
diff --git a/test/py/tests/test_source.py b/test/py/tests/test_source.py
index 970d8c79869..315aaee3fd6 100644
--- a/test/py/tests/test_source.py
+++ b/test/py/tests/test_source.py
@@ -34,3 +34,15 @@ def test_source(ubman):
     ubman.run_command('fdt rm /images default')
     assert 'Fail' in ubman.run_command('source || echo Fail')
     assert 'Fail' in ubman.run_command('source \\# || echo Fail')
+
+    output = ubman.run_command('source ${fdtcontroladdr}:test1')
+    assert 'aaa' in output
+    assert 'bbb' in output
+    assert 'ccc' in output
+
+    output = ubman.run_command('source ${fdtcontroladdr}:test2')
+    assert 'aaa' not in output
+    assert 'bbb' in output
+    assert 'ccc' not in output
+
+    assert 'Fail' in ubman.run_command('source ${fdtcontroladdr}:no-such-script || echo Fail')
-- 
2.54.0

Re: [PATCH 0/2] allow control DTB to double as "FIT image"

[Quentin Schulz]

Hi Rasmus,

On 5/12/26 6:16 PM, Rasmus Villemoes wrote:
> The commit message for patch 1 explains what it is I'd like to be able
> to do, but here's some more background:
> 

For reference:

"""
Writing those scripts in the built-in environment leads to
backslatitis and missing or wrong quoting and is generally not very
readable or maintainable.
"""

> For a long time, we've embedded the boot script in the U-Boot binary
> by building a bootscript.itb, and using a .dtsi like
> 
>    / {
>            config {
>                   bootscript = /incbin/("/path/to/bootscript.itb");
>            };
>    };
> 
> which in turn is mentioned in CONFIG_DEVICE_TREE_INCLUDES, that
> bootscript.itb FIT image has been embedded in U-Boot's control
> dtb. Running that was then a matter of doing
> 
>    fdt addr ${fdtcontroladdr} && fdt get addr bsaddr /config bootscript && source ${bsaddr}
> 
> There are a couple of advantage of having the bootscript (and other
> script logic) embedded in the U-Boot binary. First, there's no need to
> figure out some separate partition to store the script in, and making
> sure that gets updated whenever the bootloader itself does. Second,
> one doesn't need to worry about verifying the script; whatever steps
> one needs to take to implement secure boot for U-Boot itself will by
> necessity also cover the control dtb (if nothing else then because
> that's where the public key for the kernel verification lives).
> 
> Now with the stricter requirements of libfdt starting from v2026.04,
> the above command no longer worked, or only half the time, because the
> embedded FIT image may not land on an 8-byte aligned address. So that
> line had to be changed a little (line breaks added)
> 
>    fdt addr ${fdtcontroladdr}
>      && fdt get addr bsaddr /config bootscript
>      && fdt get size bssize /config bootscript
>      && cp.b ${bsaddr} ${loadaddr} ${bssize}
>      && source ${loadaddr}
> 
> which is getting quite unwieldy.
> 
> Then it struck me that one could perhaps simplify all of this quite a
> lot: Cut out the intermediate bootscript.itb, just create a .dtsi
> which directly puts a /images node inside the control dtb
> 
> / {
>    	images {
> 		default = "bootscript";
> 		bootscript {
> 			description = "Boot script";
> 			data = /incbin/("/path/to/bootscript.sh");
> 			type = "script";
> 			compression = "none";
> 		};
> 	};
> };
> 
> and treat the control dtb itself as a FIT image; so the command to put
> in $bootcmd becomes simply
> 
>    source ${fdtcontroladdr}:bootscript
> 
> and embedding other pieces of callable scripts is quite trivial.
> 
> And that almost works out-of-the-box, except for the fit_check_format() sanity check.
> 
> I realize this is a bit of a hack, but I do think it's somewhat
> elegant, and avoids inventing a whole lot of extra infrastructure for
> allowing one to embed larger scripts and invoke them from the shell. I
> am of course happy to put this exemption for gd->fdt_blob under a
> CONFIG_ knob if that is deemed necessary.
> 

Have you tried to use the text-based environment mechanism as described 
in 
https://docs.u-boot.org/en/latest/usage/environment.html#text-based-environment? 
(I've learned about this only very recently with the Apple devices being 
migrated to it)

Cheers,
Quentin

Re: [PATCH 0/2] allow control DTB to double as "FIT image"

[Rasmus Villemoes]

On Tue, May 12 2026, Quentin Schulz <quentin.schulz@cherry.de> wrote:

> Hi Rasmus,
>
> On 5/12/26 6:16 PM, Rasmus Villemoes wrote:
>> The commit message for patch 1 explains what it is I'd like to be able
>> to do, but here's some more background:
>> 
>
> For reference:
>
> """
> Writing those scripts in the built-in environment leads to
> backslatitis and missing or wrong quoting and is generally not very
> readable or maintainable.
> """
>
>
> Have you tried to use the text-based environment mechanism as
> described in
> https://docs.u-boot.org/en/latest/usage/environment.html#text-based-environment?
> (I've learned about this only very recently with the Apple devices
> being migrated to it)
>

Hi Quentin

Thanks for the suggestion. However, not only do I know about that
concept, I'm the author of f3d8f7dd73a ("Allow providing default
environment from file") which is a slightly different mechanism from the
one you refer to (and predates it by a few years), and which we've been
using ever since.

While both represent a definite improvement in the handling of the
_environment variables_ over definining it as a giant C string, it is
still not a very good way of writing whole scripts.

So the "text-based environment" method does allow you to (and
encouarages) indentation, but you don't get your editor's help to do the
if/while/... nesting properly because it's not a real script, and you
can't run shellcheck on those embedded snippets.

Moreover, while it _looks_ like a normal, commands-terminate-at-newline,
script, the stuff you put in those env variables must have all
individual commands terminated by a semicolon. Which to some extent
makes it even worse, because that is extremely easy to forget or
overlook. Imagine something like

   if something something ; then
      echo "yay";
      go_on_to_other_stuff;
   else
      echo "uh oh, something failed"                         <----
      handle_that_error;
   fi

Writing "scripts" in an env variable that can be called with "run foo"
is a bit like having to write normal shell scripts in a one-liner one
can pass to "sh -c '...'".

So no, I don't that's really a useful substitute for having a way to
properly embed real scripts in U-Boot.

Rasmus

Re: [PATCH 1/2] image-board.c: exempt gd->fdt_blob from fit_check_format() check

[Simon Glass]

Hi Rasmus,

On 2026-05-12T16:16:29, Rasmus Villemoes <ravi@prevas.dk> wrote:
> image-board.c: exempt gd->fdt_blob from fit_check_format() check
>
> Having scripts embedded one way or the other in the U-Boot binary
> means they are automatically verified/trusted by whatever mechanism
> verifies U-Boot.
>
> Writing those scripts in the built-in environment leads to
> backslatitis and missing or wrong quoting and is generally not very
> readable or maintainable.
>
> Maintaining scripts in external files allows one
> to have both syntax highlighting and to some extent apply shellcheck
> on it (though U-Boot's shell is of course not quite POSIX sh, so some
> '#shellcheck disable' directives are needed). Getting those into the
> U-Boot binary is then a matter of having a suitable .dtsi file such as
>
> / {
>         images {
>                 default = 'boot';
>                 boot {
> [...]
>
> boot/image-board.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Makes sense, and a nice feature.

> diff --git a/boot/image-board.c b/boot/image-board.c
> @@ -1037,7 +1037,7 @@ int image_locate_script(void *buf, int size, const char *fit_uname,
>                       goto exit_image_format;
>               } else {
>                       fit_hdr = buf;
> -                     if (fit_check_format(fit_hdr, IMAGE_SIZE_INVAL)) {
> +                     if (fit_hdr != gd->fdt_blob && fit_check_format(fit_hdr, IMAGE_SIZE_INVAL)) {
>                               puts("Bad FIT image format\n");
>                               return 1;
>                       }

Please add a code comment explaining why the control DTB is exempt - a
future reader running git blame will be puzzled by the pointer
comparison. Something like 'gd->fdt_blob has already been validated by
the bootloader and is by definition trusted, so we skip the strict FIT
format checks (no description/timestamp, presence of unit-addresses,
...) for that buffer'.

This also skips fdt_check_header() and fdt_check_full(). Fine for the
control DTB, but please note in the commit message that more than the
no-@ check is bypassed - the message currently singles out no-@ as
'not possible to get around', implying description/timestamp could be
worked around in the .dtsi, when in fact those are skipped too.

> Except of course that the control DTB is in fact not quite a FIT
> image. The lack of timestamp and description properties could
> potentially be worked around, but the no-@ check is not possible to
> get around. But since the control dtb is by definition trusted, we can
> just excempt that particular address from the strict check.

Typo: excempt -> exempt

> diff --git a/boot/image-board.c b/boot/image-board.c
> @@ -1037,7 +1037,7 @@ int image_locate_script(void *buf, int size, const char *fit_uname,
> +                     if (fit_hdr != gd->fdt_blob && fit_check_format(fit_hdr, IMAGE_SIZE_INVAL)) {

Would it be cleaner to push the trusted-FIT notion into
fit_check_format() itself (e.g. a sibling fit_check_format_trusted()
that skips the strict-format / no-@ pieces)? The pointer-equality test
works but feels out of place in image_locate_script(), and the same
need will likely show up the next time someone wants to
source-from-DTB elsewhere, such as an FPGA image. What do you think?

Regards,
Simon

Re: [PATCH 2/2] test: hook up test of allowing control DTB to act as FIT image

[Simon Glass]

Hi Rasmus,

On 2026-05-12T16:16:29, Rasmus Villemoes <ravi@prevas.dk> wrote:
> test: hook up test of allowing control DTB to act as FIT image
>
> Add a test demonstrating how one can embed various scripts in the
> control DTB and verifying that the source command can be used with
> ${fdtcontroladdr}.
>
> Signed-off-by: Rasmus Villemoes <ravi@prevas.dk>
>
> arch/sandbox/dts/sandbox-test1.sh     |  4 ++++
>  arch/sandbox/dts/sandbox-test2.sh     |  4 ++++
>  arch/sandbox/dts/sandbox_scripts.dtsi | 18 ++++++++++++++++++
>  configs/sandbox_defconfig             |  1 +
>  test/py/tests/test_source.py          | 12 ++++++++++++
>  5 files changed, 39 insertions(+)

> diff --git a/arch/sandbox/dts/sandbox_scripts.dtsi b/arch/sandbox/dts/sandbox_scripts.dtsi
> @@ -0,0 +1,18 @@
> +// SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> +/ {
> +     images {
> +             default = 'test';
> +             test1 {
> +                     description = 'Testscript';
> +                     data = /incbin/('sandbox-test1.sh');
> +                     type = 'script';
> +                     compression = 'none';
> +             };
> +             test2 {
> +                     description = "Another testscript";
> +                     data = /incbin/('sandbox-test2.sh');
> +                     type = 'script';
> +                     compression = 'none';
> +             };
> +     };
> +};

There is no image called 'test', so default = 'test' points at
nothing. Did you mean test1? Fixing it would also let you exercise the
no-uname case (see below).

> diff --git a/test/py/tests/test_source.py b/test/py/tests/test_source.py
> @@ -34,3 +34,15 @@ def test_source(ubman):
> +    output = ubman.run_command('source ${fdtcontroladdr}:test1')
> +    assert 'aaa' in output
> +    assert 'bbb' in output
> +    assert 'ccc' in output
> +
> +    output = ubman.run_command('source ${fdtcontroladdr}:test2')
> +    assert 'aaa' not in output
> +    assert 'bbb' in output
> +    assert 'ccc' not in output
> +
> +    assert 'Fail' in ubman.run_command('source ${fdtcontroladdr}:no-such-script || echo Fail')

The cover letter calls out 'source ${fdtcontroladdr}' (no name,
falling through to /images/default) as the headline use case, but
nothing here exercises it. Please add a case for that once default
points at a real image.

> diff --git a/arch/sandbox/dts/sandbox-test1.sh b/arch/sandbox/dts/sandbox-test1.sh
> @@ -0,0 +1,4 @@
> +# SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> +echo 'aaa'
> +source ${fdtcontroladdr}:test2
> +echo 'ccc'

The commit message is very terse for three new files plus a defconfig
change. Please mention that the test also verifies recursive sourcing
from the control DTB (test1 invoking test2), since that is a
non-trivial property worth flagging.

Also, could you add to doc/ ?

Regards,
Simon

Re: [0/2] allow control DTB to double as "FIT image"

[Simon Glass]

Hi Rasmus,

On 2026-05-12T16:16:29, Rasmus Villemoes <ravi@prevas.dk> wrote:

> RFC: allow the control DTB to act as a FIT image

Thanks for the write-up. Makes sense to me.

A couple of series-level concerns beyond the per-patch comments.

First, this needs documentation. The control DTB doubling as a FIT
image, and 'source ${fdtcontroladdr}:foo' becoming a supported idiom,
deserves a short page under doc/usage/ covering how to set up
CONFIG_DEVICE_TREE_INCLUDES with an 'images' node, the constraints
(script type, compression none, etc.) and the security argument from
the cover letter.

> I am of course happy to put this exemption for gd->fdt_blob under a
> CONFIG_ knob if that is deemed necessary.

Please decide this now rather than leaving it open. My preference is a
Kconfig option (default n) so boards keep the strict
fit_check_format() behaviour unless they opt in. That also gives a
natural home for the doc/usage/ page and makes it discoverable via
menuconfig. What do you think?

Regards,
Simon