U-Boot Binman Replacement: allow-repack Preserves Explicit Layout Constraints

An image built with allow-repack can still reject a
larger replacement component. Repacking permits Binman to reconsider
derived placement, but it does not grant permission to ignore offsets
and sizes explicitly required by the original image description.

For U-Boot v2025.01, diagnose replacement failures by separating
three questions: can Binman recover the image’s entry map, may the
operation resize entries, and can the new contents satisfy the retained
layout constraints? Increasing one permission does not answer all
three.

Begin with the
image that was actually built

The Binman
guide requires an fdtmap entry for replacing entries in
an existing image. It also says the original image must have been
generated with allow-repack when replacement requires a
size change.

These are properties of the image and its recorded description, not
facts established by a replacement filename. Preserve the input image
and inspect its entry paths and map before selecting a target. A
component filename on disk is not necessarily the hierarchical path of
its entry inside the image.

The guide separately provides --fix-size, which disables
resizing for that replacement operation. An image’s permission to repack
and the current invocation’s permission to resize are therefore distinct
gates.

Follow the two resize gates

In the replacement
controller, BeforeReplace() prepares loaded image state
and loads existing entry data. It resets placement for repacking only
when both the image allows repacking and the operation allows
resizing.

ReplaceOneEntry() asks the entry to accept new data. If
the entry reports that resizing is required, the controller rejects an
image without repack permission and separately rejects an operation with
resizing disabled.

This decision is based on the entry’s update result, not merely a
superficial comparison of two source-file names or timestamps.
Entry-specific processing and compression can affect the representation
stored in the image. The guide’s --compressed option also
changes whether replacement input is treated as already compressed; use
the input form required by that entry.

Original constraints
survive the reset

The guide explains why orig-offset and
orig-size are recorded for repackable images: Binman must
distinguish a position it calculated from a position the description
explicitly required.

The entry
implementation reflects that distinction.
ResetForPack() saves the previous packed size, then
restores offset and size from their original constraint values. It does
not simply make every entry unconstrained.

Thus a component constrained to a fixed region can remain unable to
grow even when other entries may move. Removing an intentional fixed
offset or enlarging a reserved region is a layout-design change, not a
routine way to silence the replacement error. Check the downstream
loader and hardware image contract before changing such constraints.

Inspect nested
replacements separately

Replacing a whole section introduces another boundary. The guide
warns that information about entries inside that section can become
outdated, because Binman cannot infer arbitrary internal movement or
resizing from an opaque replacement byte sequence.

Prefer the intended individual entry when it is represented and
supported. If the workflow deliberately replaces a complete nested
container, qualify that container’s own map and consumers instead of
assuming the enclosing image map proves every internal offset remains
correct.

Use a disposable
size-change fixture

For a proposed host-side experiment, keep a preserved source image
and try a same-size replacement, a growth requiring repacking, and a
replacement that conflicts with an explicit original size. Compare map
output and affected entry bytes after each accepted operation. Treat
each rejected case as its own gate rather than one generic “replacement
failed” result.

No Binman replacement was executed for this article. The acceptance
record should retain the original description, input form, resize policy
and resulting map. Repack permission means the tool may solve the layout
again within its constraints; it does not mean every larger component
can be made to fit.