MCUboot Trailer Flags: Diagnose Why a Test Image Reverts After Reset
Read both slot trailers, decode their semantic states and apply the selected mode’s rules in order before calling a revert an image failure. An unconfirmed trial can request a revert even when its executable bytes are valid. Conversely, a swap request is not proof that the candidate will pass validation.
This guide pins MCUboot v2.2.0, swap using scratch, and the new-swap decision path after excluding an interrupted operation that needs resumption. Offset, move, overwrite, direct-XIP and RAM-load modes need their own trace. No trailer writes, resets or target tests were performed.
1. Preserve evidence before another boot changes it
Capture the current boot log, exact bootloader identity, image identities and a read-only snapshot of both relevant trailers through the product’s approved diagnostic path. Record when the snapshot was taken relative to the failed trial and reset.
Use the compiled partition map and trailer-layout helpers for this build. Do not copy an address from another board or assume the trailer begins at a fixed distance from the payload. Flash alignment, configuration and reserved state determine placement.
Keep the original snapshot intact and decode a separate working copy. Do not manually set image_ok or erase a trailer as a diagnostic shortcut. Such changes alter the very decision state being investigated and may remove a recovery route.
2. Decode semantic values instead of guessing bytes
The tagged flag reader recognizes erased storage as UNSET, the defined set value as SET, and other non-erased values as BAD. It uses the flash area’s erased value. Magic likewise has decoded states rather than a generic nonzero test.
Record raw bytes, field location, read status and decoded state separately. A failed read is not an erased field. BAD must not be silently normalized to UNSET because both look like “not confirmed” in a simplified dashboard.
Use symbolic names in the investigation table so the evidence does not depend on an assumed erase polarity. Retain the exact decoder version alongside the raw snapshot.
3. Exclude the resume path first
The image-trailer design distinguishes new swaps from resumed swaps. An interrupted operation uses retained swap information and progress; the new-swap table alone is not its recovery algorithm.
If the log or state indicates an interrupted copy, stop applying the simplified worksheet below. Collect the active progress/status source and follow the exact scratch-swap recovery path. A snapshot from the middle of a transfer can resemble a final state while having a different meaning.
Also record whether the application ever started and whether confirmation was attempted. An attempt log is evidence of intent, not proof that confirmation became persistent.
4. Evaluate new-swap rules in order
For the scoped scratch mode, the ordered decision first considers a good secondary magic with secondary image-ok UNSET as TEST, then good secondary magic with image-ok SET as PERM. Only afterward does good primary magic, primary image-ok UNSET and primary copy-done SET select REVERT. Otherwise the helper returns NONE.
| Read-only hypothetical snapshot | Requested operation | Interpretation |
|---|---|---|
| Secondary magic GOOD; secondary image-ok UNSET | TEST | Trial request has priority over a later primary rule |
| Secondary magic GOOD; secondary image-ok SET | PERM | Permanent request has priority over a later primary rule |
| No earlier rule matches; primary magic GOOD, image-ok UNSET, copy-done SET | REVERT | Completed unconfirmed trial requests return |
| No earlier rule matches; primary image-ok SET | NONE from this table | The stated revert predicate is not satisfied |
Other fields are not independent votes. In particular, reading only the primary trailer can miss a higher-priority secondary request. Use a row-by-row match record that names the first satisfied rule.
The offset-only rule is deliberately excluded here. Reusing this scratch worksheet for offset mode would lose a mode-specific secondary copy-done decision.
5. Keep read errors visible
In the scoped boot_swap_type_multi(), a primary-state read failure yields PANIC. A secondary BOOT_EFLASH result is logged and treated as an empty secondary state for this decision. Other secondary errors yield PANIC.
Thus an apparent “empty secondary” decision may have a read-error origin. Preserve that distinction in the support record. It can change the next investigation even though the subsequent table sees the same semantic values.
Do not fabricate trailer data to force the expected result. If raw evidence is incomplete, record the predicted decision as uncertain and obtain the smallest approved read-only observation that resolves it.
6. Separate requested operation from successful boot
The loader’s validation and update paths still determine whether an image is usable and whether an operation completes. A TEST label does not establish a valid signature, and NONE from this helper is not a certificate that the primary image can run.
Keep three results in the report: decoded request, validation outcome and observed next-boot image. This prevents a candidate rejection, an expected revert and a failed swap from collapsing into one “update failed” category.
Hypothetical unconfirmed trial
A fictional device starts its candidate once, then resets. Its captured state has no higher-priority secondary request; primary magic is GOOD, copy-done is SET and image-ok is UNSET. The scratch-mode table requests REVERT.
Investigate whether the intended confirmation path ran, whether its persistence operation succeeded and whether the snapshot belongs to the expected image pair. Do not conclude that the payload was corrupt merely because the old image returns.
7. Qualify the decoder with preserved fixtures
Build an offline fixture set containing the four snapshots above, BAD flags, failed reads and a clearly marked interrupted-operation case. Include a conflicting primary revert predicate plus a secondary TEST request to expose an incorrectly reordered decoder.
Require the decoder to report mode, field provenance, first matching rule and uncertainty. These fixtures are proposed and unexecuted. Later integration tests need recoverable devices and preserved original images; no live trailer-edit commands are needed for this review.
Close with the exact snapshot, decoder, source revision and stage-specific interpretation. This provides a concrete answer to why a trial requested reversion while leaving application readiness, signature enforcement and swap recovery as separately evidenced decisions.
