U-Boot Bootcount Files: Qualify the upgrade_available Persistence Gate

A device repeatedly resets during startup, yet its fallback boot
action never runs. The obvious explanation is a broken counter. With
U-Boot’s filesystem bootcount backend, however, the first question
should be whether the product enabled persistence for the trial at all.
A displayed count, a stored record and a boot-policy decision are
different pieces of evidence.

The scope here is upstream U-Boot v2025.01 with bootcount support and
the filesystem backend selected. Other backends can have different
persistence behavior. The examples are proposed qualification cases, not
observations from tested hardware. For a Buildroot-based product, trace
these mechanisms in the U-Boot revision and board configuration selected
by that product; Buildroot integration does not replace that check.

Identify the record
that survives reset

The Boot Count
Limit documentation describes a filesystem record containing
byte-sized magic, version, bootcount and upgrade_available fields. For
this backend, upgrade_available controls whether the count is saved. Its
documented successful-boot procedure clears both the upgrade indication
and count.

That gate matters when interpreting repeated resets. If persistence
is not enabled for the trial, observing a count during one U-Boot
session does not establish that the next session will load an
incremented record. Conversely, a stale trial indication can leave
ordinary restarts participating in a policy intended only for
qualification of a newly selected system.

Start the investigation with the actual backend and storage location.
Record the interface, device or partition specification, filename and
firmware configuration. Confirm which userspace component reads or
writes that same record. A service editing an unrelated environment
variable is not evidence that it updated the selected backend.

Test the exact threshold

The tagged bootcount
helper implementation tests for a nonzero bootlimit and a count
strictly greater than that limit. Equality is a separate case. The code
also contains stage-dependent increment handling, so inspect whether SPL
or TPL already owns the increment before assuming U-Boot proper adds
another one.

Use a small, deliberately chosen limit in an isolated fixture. For
example, a limit of three creates useful boundary observations at counts
two, three and four. Those values illustrate the comparison only; they
do not prescribe a retry budget for a real product. Capture the loaded
count, the value used for comparison and the command selected after that
comparison.

Do not derive a promised number of user-visible failures from the
limit alone. The starting record, increment stage, reset behavior and
acknowledgement timing all affect what a user experiences. Write the
expected state transition first, then check it against the tagged code
and target configuration.

Define what successful boot
means

A process starting is an easy acknowledgement event to implement. It
may be too early for the product. Imagine a system that clears the trial
state immediately after mounting its root filesystem, then resets when
its main service loads configuration. The counter can be correctly
implemented while the chosen acknowledgement point defeats the intended
recovery policy.

Define the minimum health evidence needed before acknowledgement. It
might include loading required configuration, reaching a local
application-ready state and confirming that essential persistent data is
readable. Avoid making an external cloud connection the only success
condition unless the product explicitly treats an unavailable network as
a failed software trial.

Give acknowledgement one owner. Document what that owner writes, how
it checks failure, and what happens if it is interrupted between related
updates. Do not assume that two writes form one atomic operation merely
because they occur in the same function. Review the backend’s actual
update method and its durability boundary.

Exercise resets around
acknowledgement

A useful test matrix distinguishes when the interruption happens
rather than merely repeating a reboot command. Run each case on
recoverable hardware or an appropriate disposable fixture:

1. Start a trial with the persistence gate enabled and reset before the
   health decision.
2. Repeat with the gate disabled and compare the stored record after
   each reset.
3. Reach the health decision but make its record update fail. Confirm
   that the failure is visible to the owning service.
4. Interrupt the acknowledgement operation using a backend-aware
   method, then inspect the next boot’s state.
5. Complete acknowledgement and perform an ordinary restart to verify
   the intended non-trial behavior.

Preserve the record bytes and console output for each case. A line
printed by an application before a write is not proof that the write
became durable. Likewise, an unchanged record after reset does not
identify the cause without the preceding gate value and update
result.

Include cold power cycles and the supported reset paths as separately
named tests. Do not infer that a watchdog reset reproduces loss of power
to the storage device. State exactly which reset condition was exercised
in any eventual report.

Review the alternate action
itself

A threshold can be crossed correctly while the product still has no
useful recovery. The documented policy selects altbootcmd rather than
bootcmd; an absent alternate command can leave U-Boot interactive.
Review the configured alternate action as carefully as the ordinary
path, including its availability on a production unit without a
technician attached.

Keep three acceptance results separate: the count persisted as
intended, the comparison selected the expected action, and that action
reached the required recovery state. A failure in the third result
should not be disguised as a counter problem, and a correct counter
should not earn a blanket recovery claim.

The final fix should explain the ownership chain from trial
activation to durable acknowledgement. When those transitions are
explicit, repeated resets become a traceable state machine rather than
an argument over the last number shown at the prompt.