Zephyr OS Settings Commit: Apply Related Values After the Load Phase

A settings handler that immediately applies every value as it is loaded can expose an incomplete configuration to the application. Related values, such as a lower and upper operating limit, may be individually valid but invalid as a pair until loading finishes. Zephyr's commit callback provides a useful application boundary for validating and applying that group.

The boundary is not a promise of an atomic persistent transaction. This article uses Zephyr 4.4.0 to distinguish loading values, validating a candidate configuration, applying it, and saving data. Mixing those operations under the word “commit” makes recovery behavior harder to reason about.

Stage values before activating them

The tagged settings interface gives a handler separate set and commit callbacks. The set callback receives a key and a backend read function; the commit callback runs after settings have been loaded and can apply them to the application.

Use a candidate structure for related values. The set handler can check the expected representation and length, read the value, and record whether that field was successfully supplied. Keep candidate validity separate from the active configuration used by control or communication code.

At commit, validate the relationships that only make sense across fields. For a hypothetical limit pair, check the lower limit against the upper limit. For a channel configuration, check whether the selected mode supports the associated parameter. These are illustrative application rules, not constraints automatically supplied by the settings subsystem.

Missing keys need an explicit policy

Loading does not guarantee that every desired key exists. A device may have old firmware data, a partly provisioned configuration, or a deliberate deletion. Decide whether a missing value uses a documented default, preserves an existing value, or prevents activation.

Reset candidate bookkeeping before the relevant load operation. Otherwise, a flag left over from an earlier successful load can make a missing key appear present during a later load. A candidate structure and a “seen this load” mask answer different questions and should not be conflated.

If a field has an invalid length or cannot be read, do not silently mark it as present. Preserve enough application error state for the commit decision to reject or explicitly repair the candidate according to the product's policy.

Know which load path calls commit

The tagged settings store implementation makes settings_load call the subtree-loading path. That path iterates the registered stores and then calls settings_commit_subtree. Its direct-subtree-loading path uses a supplied callback and does not make the same commit call.

This difference matters when replacing a normal load with a direct load for a diagnostic or migration utility. Do not assume the application activation hook still runs merely because values were read from the same storage backend. Review the exact API used by each call site.

The implementation also means a successful top-level result should not substitute for application-specific completeness checks. The active configuration should be justified by validated fields and relationships, rather than by a vague statement that storage loading returned.

Activation needs its own concurrency boundary

After validation, publish the candidate in a way readers can use consistently. A suitable project might copy it under a lock or switch an application-owned snapshot. The correct mechanism depends on reader context and data size; the settings callback alone does not make a multi-field update atomic for concurrent application code.

Avoid performing irreversible external actions during each individual set callback. If hardware must be reconfigured, define what happens when only part of that activation succeeds. Keeping the previous active configuration available can help, but the hardware recovery procedure still needs a device-specific design.

This is especially important for settings that change the communication channel used to report errors. An incomplete activation should not accidentally remove the only way to diagnose why loading failed.

Keep persistence guarantees separate

A commit callback is an application hook after loading. It does not establish that several earlier saves reached flash together, nor that a power failure cannot leave a mixed set of persistent values. If a group must be recovered as one version, design and verify an appropriate persistent representation or generation scheme with the selected backend.

A focused test changes key order, omits one required key, supplies an invalid length, and repeats a load after an earlier successful one. Check which candidate becomes active and why. Include the direct-load path only if the product actually uses it.

The desired result is a clear state transition: loaded values become a validated candidate, then an intentionally activated configuration. It is not merely that every individual set callback returned success.