Skip to content

boot: bootutil: Allow ports to size the image hash buffer - #2823

Merged
nordicjm merged 1 commit into
mcu-tools:mainfrom
danielriege:configurable-hash-buf-size
Aug 11, 2026
Merged

boot: bootutil: Allow ports to size the image hash buffer#2823
nordicjm merged 1 commit into
mcu-tools:mainfrom
danielriege:configurable-hash-buf-size

Conversation

@danielriege

Copy link
Copy Markdown
Contributor

What

Adds MCUBOOT_BOOT_TMPBUF_SZ, letting a port override the size of the buffer
used to read an image in chunks while computing its hash. The default stays at
256 bytes.

Why

BOOT_TMPBUF_SZ determines the chunk size in bootutil_img_hash(), so the
number of flash_area_read() calls over an image is
ceil(image_size / BOOT_TMPBUF_SZ).

On flash that is memory mapped the per-call cost is small. On flash that is not
— QSPI, SPI NOR, eMMC — each read is a bus transaction with a fixed
command/address overhead, so the read count rather than the byte count can
dominate validation time. At the 256 byte default a 1 MiB image is 4096
sequential reads.

The converse also applies: the buffer is statically allocated, so a
RAM-constrained port may want it smaller than 256.

Why not just pass a different tmp_buf_sz?

bootutil_img_hash() already takes the buffer and its size as parameters, but
every caller lives in boot/bootutil or in a port:

  • boot/bootutil/src/bootutil_loader.c
  • boot/bootutil/src/loader.c
  • boot/boot_serial/src/boot_serial_encryption.c
  • boot/zephyr/single_loader.c, boot/zephyr/firmware_loader.c
  • boot/mynewt/src/single_loader.c

A port that uses the in-tree loaders therefore has no way to reach it short of
forking those files. bootutil_priv.h already includes
mcuboot_config/mcuboot_config.h above the definition, so a guard is all that
is needed.

Design

Mirrors the existing MCUBOOT_BOOT_MAX_ALIGN -> BOOT_MAX_ALIGN pattern in
boot/bootutil/include/bootutil/bootutil_public.h — same #ifdef /
_Static_assert / #else default shape, and the option name is the existing
internal name with the usual MCUBOOT_ prefix, so no new vocabulary is
introduced.

Happy to rename it, or to add a corresponding Zephyr Kconfig option, if
maintainers prefer — note that this guard is a prerequisite for such a Kconfig
option working at all.

Impact

  • No behavioural change in any existing configuration; the default is unchanged
    and the new macro is defined nowhere in tree.
  • The simulator does not set it, so simulator behaviour is unchanged.
  • Documented in samples/mcuboot_config/mcuboot_config.template.h.
  • Release note stub included.

BOOT_TMPBUF_SZ is the buffer the image is read into, in chunks, while its
hash is computed, so the number of flash_area_read() calls over an image is
ceil(image_size / BOOT_TMPBUF_SZ). On flash that is not memory mapped every
one of those reads is a bus transaction with a fixed cost, which can make
this size dominate image validation time; ports that are short on RAM may
equally want to lower it from the 256 byte default.

The buffer is declared by the callers of bootutil_img_validate() rather
than passed in by the port, so a port using the in-tree loaders cannot
currently influence it at all.

Add MCUBOOT_BOOT_TMPBUF_SZ so a port can override it from
mcuboot_config.h, following the same pattern already used for
MCUBOOT_BOOT_MAX_ALIGN in bootutil_public.h. The default is unchanged, so
there is no behavioural change for any existing configuration.

Signed-off-by: Daniel Riege <daniel.riege99@gmail.com>
@nordicjm
nordicjm merged commit c8a4cb5 into mcu-tools:main Aug 11, 2026
87 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants