bootutil: Add manifest-based loader for Direct XIP #2511

tomchy · 2025-10-21T13:00:31Z

Add a loader variant that is capable of booting images, based on a simple manifest.

Ideas:

The 1st Image (slot pair) is the main/lead image - it describes firmware bundle for the device. This image is manifest Image.
The firmware bundle description is provided in the protected TLV of the manifest image. Images relations are expressed as their hashes. Obviously hash of the manifest image is not in the TLV as it covers it as well.

boot/zephyr/Kconfig

boot/bootutil/src/loader_manifest_xip_ram.c

JarmouniA

Can we have some documentation for this feature? Thanks!

boot/bootutil/include/bootutil/mcuboot_manifest.h

boot/bootutil/src/loader_manifest_xip.c

de-nordic · 2025-10-31T15:04:00Z

boot/bootutil/include/bootutil/mcuboot_manifest.h

+static inline const uint8_t *bootutil_get_image_hash(const struct mcuboot_manifest *manifest,
+                                                     uint32_t image_index)
+{
+    if (!bootutil_verify_manifest(manifest)) {
+        return NULL;
+    }
+
+    if (image_index >= BOOT_IMAGE_NUMBER) {
+        return NULL;
+    }
+
+    if (image_index < MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+        return manifest->image_hash[image_index];
+    } else if (image_index > MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+        return manifest->image_hash[image_index - 1];
+    }
+
+    return NULL;
+}


I am not sure this should be able to return NULL in any case.
This should panic on any parameter that is not expected.
Since the function is always called before boot_fih_memequal I think that both functions should be merged and the bootutil_get_image_hash should be changed to FIH return function that will be given enough parameter to compare a hash without pulling it out of the manifest object.
This should also reduce code size, since the boot_fih_memequal and will be combined here and no need for external null checks.

I agree that there is no need to expose the manifest hash, however since this function is likely to be shared between the application and bootloader, I will remove the FIH part from the logic, so it does not rely on additional external modules.

de-nordic · 2025-10-31T15:09:10Z

boot/bootutil/src/bootutil_priv.h

+
+#if defined(MCUBOOT_MANIFEST_UPDATES)
+    struct mcuboot_manifest manifest[BOOT_NUM_SLOTS];
+    bool manifest_valid[BOOT_NUM_SLOTS];


Can we move that into the mcuboot_manifest? We can have different structs for TLV and internal usage.

That'd need a struct within a struct, as the struct mcuboot_manifest is directly loaded from the TLV and the manifest_valid is not part of the incoming data, but an internal flag, indicating that the structure was loaded.

If you find the "valid" sate flag to be non-universal, I may move everything inside (including manifest_valid as well as matching_manifest), but I am hesitant to do so as those are not variables that holds information from the manifest, but a state variables for a loader logic and are not needed outside of the bootloader scope.

de-nordic · 2025-10-31T15:11:50Z

boot/bootutil/src/image_validate.c

+            if (image_index == MCUBOOT_MANIFEST_IMAGE_NUMBER) {
+                if (!state->manifest_valid[slot]) {
+                    /* Manifest TLV must be processed before any of the image's hash TLV. */
+                    BOOT_LOG_INF("bootutil_img_validate: image rejected, manifest not found before image %d hash",


Isn't that at least warning? It ends up in rc = -1, so basically fails the function.

I'm OK with increasing the log level. Generally speaking - this function is not too verbose (most errors logged as debug information), but I do not fully understand the reason behind it (code size?).

boot/bootutil/src/image_validate.c

boot/bootutil/src/loader_manifest_xip.c

boot/bootutil/src/image_validate.c

tomchy · 2025-11-04T13:35:29Z

Can we have some documentation for this feature? Thanks!

This feature definitely deserves a few words in the docs. Just keep in mind that:

This is marked as experimental, since this feature is not yet fully implemented.
This is 1/3 or even 1/4 of a solution - only Direct XIP mode is supported.
The review or further implementation process may introduce changes, that will make any early attempts to write documentation obsolete.

Add a possibility to attach a basic manifest with expected digests to an image. Alter the image verification logic, so only digests specified by the manifest are allowed on the device. Signed-off-by: Tomasz Chyrowicz <[email protected]>

Add a simple logic that allows to attach a manifest TLV to an image. Signed-off-by: Tomasz Chyrowicz <[email protected]>

Add a loader variant that is capable of booting images, based on a simple manifest. Signed-off-by: Tomasz Chyrowicz <[email protected]>

Add a short description about motivation behind manifest-based updates and the Direct XIP mode of operation if the manifests are enabled. Signed-off-by: Tomasz Chyrowicz <[email protected]>

JarmouniA · 2025-11-07T13:49:26Z

This feature definitely deserves a few words in the docs. Just keep in mind that:

This is marked as experimental, since this feature is not yet fully implemented.

This is 1/3 or even 1/4 of a solution - only Direct XIP mode is supported.

The review or further implementation process may introduce changes, that will make any early attempts to write documentation obsolete.

Alternatively, you could expand the PR's description.

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch 3 times, most recently from 6ebfcaf to aaf2a5a Compare October 21, 2025 14:10

tomchy commented Oct 22, 2025

View reviewed changes

boot/zephyr/Kconfig Show resolved Hide resolved

tomchy commented Oct 22, 2025

View reviewed changes

boot/bootutil/src/loader_manifest_xip_ram.c Outdated Show resolved Hide resolved

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch from aaf2a5a to d8e62ff Compare October 22, 2025 09:00

tomchy marked this pull request as ready for review October 22, 2025 15:13

tomchy requested review from almir-okato, d3zd3z, davidvincze, de-nordic and nordicjm as code owners October 22, 2025 15:13

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch from d8e62ff to 3688d72 Compare October 23, 2025 12:07

JarmouniA reviewed Oct 23, 2025

View reviewed changes

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch from 3688d72 to 8eca34c Compare October 24, 2025 09:02

michalek-no approved these changes Oct 24, 2025

View reviewed changes

de-nordic reviewed Oct 28, 2025

View reviewed changes

boot/bootutil/include/bootutil/mcuboot_manifest.h Outdated Show resolved Hide resolved

tomchy commented Oct 31, 2025

View reviewed changes

boot/bootutil/src/loader_manifest_xip.c Show resolved Hide resolved

de-nordic requested changes Oct 31, 2025

View reviewed changes

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch from 8eca34c to 34d235b Compare November 4, 2025 12:52

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch from 34d235b to faed92a Compare November 4, 2025 14:26

tomchy requested review from JarmouniA and de-nordic November 4, 2025 15:01

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch 4 times, most recently from f5b0fdc to fbb5565 Compare November 4, 2025 16:25

tomchy added 2 commits November 7, 2025 12:33

boot: Add MCUboot manifest TLV

c9b33c7

Add a possibility to attach a basic manifest with expected digests to an image. Alter the image verification logic, so only digests specified by the manifest are allowed on the device. Signed-off-by: Tomasz Chyrowicz <[email protected]>

imgtool: Add a possibility to attach manifest TLV

f9a047c

Add a simple logic that allows to attach a manifest TLV to an image. Signed-off-by: Tomasz Chyrowicz <[email protected]>

tomchy added 2 commits November 7, 2025 12:33

bootutil: Add manifest-based loader for Direct XIP

89bb9fa

Add a loader variant that is capable of booting images, based on a simple manifest. Signed-off-by: Tomasz Chyrowicz <[email protected]>

doc: Add manifest conceptual description

937c80a

Add a short description about motivation behind manifest-based updates and the Direct XIP mode of operation if the manifests are enabled. Signed-off-by: Tomasz Chyrowicz <[email protected]>

tomchy force-pushed the feature/mcuboot/NCSDK-NONE_Transaction_manifest_xip_upstream branch from fbb5565 to 937c80a Compare November 7, 2025 11:33

bootutil: Add manifest-based loader for Direct XIP #2511

Are you sure you want to change the base?

bootutil: Add manifest-based loader for Direct XIP #2511

Uh oh!

Conversation

tomchy commented Oct 21, 2025 • edited by nvlsianpu Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JarmouniA left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

de-nordic Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

tomchy Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

de-nordic Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

tomchy Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

de-nordic Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

tomchy Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tomchy commented Nov 4, 2025

Uh oh!

JarmouniA commented Nov 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tomchy commented Oct 21, 2025 •

edited by nvlsianpu

Loading