Zephyr OS FCB Entries: Finish a Record Before Treating It as Committed Data
Reserving an entry in a flash circular buffer does not complete the record. The application still has to write the payload and finish the append operation. Reporting success after reservation alone confuses allocated space with a completed storage entry.
This distinction matters for Zephyr OS devices recording measurements or diagnostic events. The implementation discussion uses v4.4.0. Any interrupted-write experiments described here require disposable storage and are proposed tests, not a claim of verified power-loss behavior on a particular board.
Follow the append lifecycle through all three stages
The tagged FCB interface gives the application a location through fcb_append(). The caller writes the entry contents and then calls fcb_append_finish(). Check each result; successful space reservation does not imply that the data write or finishing step succeeded.
Imagine a hypothetical event recorder that acknowledges a measurement to its producer immediately after fcb_append(). A power interruption before the payload is written would leave the producer's acknowledgement stronger than the evidence actually stored. Move the acknowledgement boundary to the storage state that the product intends it to represent.
Keep the entry location associated with the exact payload being written. Do not reuse one location structure for unrelated overlapping appends before their operations are complete. Even when internal allocation is synchronized, the application remains responsible for maintaining its own record identity and data lifetime.
Understand what the finishing write contributes
The tagged append implementation reserves aligned space for length, data and an ending marker. The finish function obtains that marker and writes it after the aligned payload region. Failures during marker generation or writing are returned to the caller.
The public configuration also allows a fixed-end-marker mode when the corresponding support is enabled. Do not claim that every FCB instance necessarily uses the same CRC-based integrity policy. Record the selected configuration when defining what a successfully finished entry establishes.
Even with an integrity check, storage validity is not application validity. A complete record can contain an obsolete schema version, an out-of-range value or an event from an earlier acquisition generation. Include the application metadata needed to reject those cases rather than assuming the container knows their meaning.
Define recovery separately from capacity management
The official FCB guide explains the append-and-finish pattern and checksum-based detection of interrupted entries in its general model. Treat that as a starting point for the configured implementation, not a universal promise about every flash failure.
For a hypothetical diagnostic recorder, distinguish an incomplete newest entry from a completed older entry that has legitimately been removed by rotation. The first concerns committing a record; the second concerns retention policy. Increasing the number of sectors does not remove the need to define the commit boundary.
On restart, preserve enough information to identify which records the reader accepts. Do not manufacture a replacement event merely because its reservation existed before interruption. If the application must retry a logical event, use its own identifier to decide whether an already-completed copy exists.
Interrupt each stage deliberately on test media
Propose separate fault points after reservation, during payload writing and during the finishing marker write. Reinitialize the storage reader and compare accepted record identities and contents with the expected completed set. Repeat using the actual alignment and marker configuration intended for the product.
Also test an ordinary payload-write error without a power interruption. Confirm that the application does not proceed to report a successful record merely because later cleanup returned normally. Capture the original failing stage in the test result.
A useful completion statement is specific: the requested payload was written, the append was finished successfully, and the reader accepted the expected record under the selected configuration. “The append call returned zero” is only enough when it names the correct stage and does not silently stand in for the entire transaction.
