Boot Verification Error Codes: Keep Authentication Failures Distinct from Flash Read Errors
Report the failing stage together with the observed cause and raw result. A boot error code alone may merge flash-read, format, hash and signature failures. Support can act on a precise refusal reason without weakening the refusal itself.
This guide pins U-Boot v2024.10’s simple-SPL FIT path and its verification helpers. The proposed public reason labels are an original integration design, not upstream API names. Other loaders and downstream builds require their own mapping. No boot, flash fault or image-verification test was executed.
1. Trace where detailed evidence is lost
In load_simple_fit(), an external-read return below the declared payload length produces -EIO, while a failed image-verification helper returns -EPERM. The requested read includes alignment padding, and the payload pointer advances past alignment overhead. This comparison is not against the complete aligned request, so this errno check alone does not prove that the entire aligned read completed. Configuration-verification failure also maps to -EPERM elsewhere in this path. Decompression failures can return -EIO too.
Therefore neither “EIO means flash is broken” nor “EPERM means the signing key is wrong” is a reliable general diagnosis. Preserve the operation that produced the result before a wrapper converts it into a coarser boot failure.
Build a call-path map from acquisition through parsing, configuration authorization, payload checking, transformation and handoff. Assign each checkpoint a stable identifier tied to the actual build. Do not infer ordering from the order of messages copied into a support ticket.
2. Keep observations separate from interpretations
The image verification code distinguishes unsupported hash selection, invalid digest length, digest mismatch, required-signature failure and malformed tree handling internally. Its caller may receive only a Boolean failure.
A digest mismatch proves that the checked data did not match the expected value under that operation. It does not alone identify malicious modification, bad media or the wrong artifact. Likewise, a required-signature failure can have several integration causes; avoid turning it into an unsupported accusation about the signer.
| Proposed report label | Minimum supporting observation | What must remain uncertain |
|---|---|---|
| SOURCE_READ_INCOMPLETE | Identified reader returned insufficient data | Physical-media root cause without further evidence |
| FORMAT_REJECTED | Parser rejected a named structural condition | Whether later authentication would have passed |
| HASH_SCHEME_UNAVAILABLE | Selected hash implementation could not be resolved | Artifact corruption or signer intent |
| PAYLOAD_DIGEST_MISMATCH | Computed and expected digests differed | Why the bytes differ |
| REQUIRED_AUTHENTICATION_FAILED | Required signature/key path rejected | The specific root cause unless separately observed |
| VERIFY_FAILED_UNCLASSIFIED | Only a coarse verification failure survived | Any finer category |
Retain the unclassified category. It is better than manufacturing a precise reason from a numeric code that no longer carries that information.
3. Design a bounded event record
Record the verifier build identifier, boot attempt identifier, selected component, stage, raw result, normalized category and observation completeness. Include a source-reader identifier when relevant. Use stable public release identifiers rather than private file paths.
A record should say whether the category came from a direct checkpoint or an analyst’s later inference. If the beginning of the log is missing, preserve that limitation. Do not replace an unavailable first failure with the last generic message as though it were the original cause.
Never include private keys, secret provider output, raw protected memory or customer payloads in a reason code. Public identifiers and bounded stage markers usually provide a better support boundary than unrestricted diagnostic dumps.
4. Preserve authentication policy while adding diagnostics
The required-signature implementation is part of the acceptance decision. Reporting changes must not convert a required-check failure into permission to continue, select an unsigned image or retry under relaxed trust.
Separate the diagnostic category from the recovery decision. A product may have an approved authenticated recovery route, but a category such as “read failure” does not automatically authorize any available fallback.
Review failure logging for bounded work and predictable storage use. If the diagnostic destination is unavailable, the refusal must remain effective. A logging error must neither erase the original failure nor turn it into success.
5. Create one controlled cause per fixture
| Proposed fixture | Expected evidence boundary |
|---|---|
| Unchanged approved image and complete read | Positive control reaches intended verification success |
| Reader deliberately returns fewer bytes than the declared payload length | Acquisition failure is recorded before payload verification |
| Malformed metadata with complete source | Structural failure remains distinct |
| Supported image with altered payload and original digest | Digest-check rejection is attributable to that stage |
| Coherent payload/digest change with unchanged required configuration signature | Required configuration authentication rejects the changed binding |
| Unavailable hash scheme in a controlled fixture | Capability rejection is not mislabeled as media failure |
| Missing diagnostic sink | Boot refusal persists with an explicit evidence gap |
Use preserved copies, approved synthetic artifacts and an instrumented reader before attempting hardware faults. Any later target run requires disposable media and verified recovery. Do not damage live storage to manufacture an error message.
A fixture must reach the intended stage. If configuration authentication rejects a modified hash-algorithm field first, that run has not tested hash dispatch. Adjust the approved test construction, not the production verifier policy, and record the actual stage reached.
Hypothetical misleading permission error
A fictional support collector translates every -EPERM into “wrong signing key.” In the reviewed build, the same wrapper result can follow a payload hash failure. Engineers begin changing signing inputs even though the artifact delivered to storage is incomplete or different.
The corrected collector records stage and available direct cause, with an unclassified fallback. Investigation can then compare acquired bytes or authentication inputs according to evidence, while every rejected candidate remains rejected.
6. Validate the mapping as a versioned interface
Keep a table connecting each normalized category to the exact source checkpoint and fixture result. Revalidate it when updating the loader, changing optional diagnostics or introducing another storage reader.
Do not promise the same raw errno across releases or platforms. The durable support contract is the bounded meaning of each category and its evidence level. A useful boot-failure report narrows the next investigation without claiming more than the verifier observed.
