U-Boot FIT Best-Match Selection: Audit Compatibility Priority and Equal-Match Ties
Predict FIT best-match selection from the ordered compatibility list in U-Boot’s control device tree, then check equal-priority ties and explicit selectors separately. A chosen configuration is a selection result. It still needs the product’s authentication and board-qualification evidence before use.
This guide pins U-Boot v2024.10’s fit_conf_find_compat() and its fit_image_load() caller. It does not assert that every SPL loader, board override or downstream boot command follows this path. The fixtures below are hand-derived expectations for qualification; no bootloader or hardware tests were executed.
1. Freeze the inputs that control the result
Collect the exact U-Boot binary and configuration, its control FDT, the FIT artifact, and the invocation that selects the image. Preserve the configuration-node order in the compiled FIT. A spreadsheet copied from the source description is useful only after checking that the final artifact matches it.
The FIT_BEST_MATCH option describes automatic selection when no configuration is explicitly chosen. Earlier, more-specific entries in U-Boot’s root compatibility list take priority; the order inside a candidate’s list does not establish that priority.
Keep the control FDT distinct from a candidate operating-system FDT. If the audit extracts compatibility strings from the wrong tree, its predicted ranking can look internally consistent while disagreeing with the bootloader.
2. Reconstruct the candidate compatibility source
The tagged implementation first uses a configuration’s own compatible property. Otherwise it extracts compatibility from the referenced FDT image. That fallback skips missing or unresolved references, compressed FDT images, and failed data extraction.
Record where each candidate’s strings came from. A configuration-local declaration can make automatic selection possible without extraction, but it also creates another value that needs review against the actual board description and payload. Do not approve it merely because it produces the desired winner.
| Worksheet column | What to retain |
|---|---|
| Configuration identity | Node name and encounter order from the final FIT |
| Compatibility provenance | Configuration property or referenced FDT root |
| Candidate availability | Usable source, or exact reason extraction cannot participate |
| Best control-list index | First control-FDT string present in the candidate set |
| Tie group | Other candidates with the same best index |
| Disposition | Predicted winner, excluded candidate or unresolved evidence |
3. Apply priority and tie rules explicitly
In this implementation, a candidate replaces the current winner only for a lower control-list index. An equal-index candidate does not replace it. Consequently, equal matches retain the first configuration encountered; failure to find any match returns an error.
Use neutral symbols while reviewing the algorithm. Suppose the control list is [board-specific, board-family, generic]. These labels are illustrative identifiers, not real hardware compatibility promises.
| Hypothetical candidates in encounter order | Expected ranking result |
|---|---|
| A contains family; B contains specific | B, because its best index is earlier |
| A contains specific; B contains specific | A, retained on the equal-priority tie |
| B contains specific; A contains specific | B, after encounter order is reversed |
| A contains generic then specific; B contains family | A; candidate-list order does not reduce its match |
| Neither candidate contains any control-list entry | No best-match configuration |
Flag ties even when the current ordering is stable. A harmless-looking build-system change that reorders generated nodes can become a selection change. Either make ordering an explicit reviewed contract or remove ambiguity through a separately qualified packaging policy.
4. Identify when ranking is bypassed
In the scoped caller, an explicit image name goes directly to that image. An explicit configuration uses configuration lookup instead of best-match ranking. Automatic best-match failure returns a configuration error; this branch does not then retry the FIT default.
Retain the actual invocation with each test result. A successful explicit-selection test does not validate the automatic path. Likewise, modifying a default configuration cannot be assumed to repair an automatic no-match result.
Test both the normal startup path and authorized recovery paths if they use different selectors. The worksheet should identify which path was exercised without providing an instruction to bypass production policy.
5. Keep authorization and board safety separate
FIT configuration signatures can bind selected image references under a trusted required-key policy. Compatibility ranking does not establish that policy or replace its verification. Review the actual authenticated scope and required-key enforcement independently.
A match also does not prove that memory timings, peripherals, regulators or other board-specific behavior are safe. Treat those as product integration requirements with their own evidence. Two candidates claiming the same string can still contain different operating configurations.
If a selected image fails verification, retain that failure. Do not silently choose another candidate or relax authentication to obtain a boot. Any fallback behavior needs an explicit, independently qualified product policy.
6. Turn the worksheet into a release fixture set
Include a higher-priority candidate appearing later, two equal-priority candidates in both orders, reordered strings inside one candidate, no matching strings, a configuration-local override, and a compressed referenced FDT without that override. Add explicit-image and explicit-configuration cases.
For each fixture, record predicted selection, observed selection, invocation, source revision and artifact digest. Run only approved inert fixtures on a controlled test platform; retain original artifacts and recovery capability. These proposed cases have not been executed here.
Hypothetical duplicate family declaration
A fictional product packages two revisions with the same family string. Both select successfully, but reversing their node order changes the winner. The release gate should identify an ambiguous selection contract, not declare both revisions interchangeable.
Resolve the product’s intended priority and qualification evidence before approving the package. The completed deliverable is a reproducible selection explanation tied to exact artifacts, followed by separate authorization and board-safety decisions.
