Zephyr OS Stream Flash: Flush the Last Partial Buffer Without Inventing Extra Payload

A successful buffered-write call does not always mean every supplied byte has reached flash. Data can remain in the stream's RAM buffer until it fills or an explicit final flush is requested. The final hardware write may also include alignment padding that is not part of the application's payload.

For a Zephyr OS transfer or image-staging path, keep accepted input, buffered bytes and committed payload bytes distinct. This explanation follows v4.4.0 and proposes review cases rather than reporting an executed update procedure.

Make end-of-stream an explicit operation

The tagged stream-flash interface exposes buffered writes with a flush argument and separate queries for bytes written and buffered. A transport's end-of-file indication should be mapped deliberately to the storage finalization policy, including its result handling.

Imagine a hypothetical transfer whose final chunk is shorter than the configured RAM buffer. Receiving that chunk and returning successfully from an unflushed write can leave the tail in RAM. A subsequent reset would therefore lose data that the transport had already delivered to the application.

Do not mark the object complete solely because the network's expected byte count has arrived. Completion needs the successful storage boundary required by the selected API, followed by whatever integrity and acceptance checks the object format requires. Stream-flash buffering by itself does not authenticate an update or decide whether it may boot.

Track logical bytes separately from the physical write extent

The tagged implementation fills the final partial write block using the device's erase value. It sends an aligned extent to flash_write(), while advancing bytes_written by the actual buffered payload length rather than the filler length.

For a hypothetical payload of 10 bytes and a write-block requirement of four bytes, the final physical write may need 12 bytes. The additional two bytes are storage padding, not two newly received payload bytes. That example describes arithmetic only; the actual buffer, range and device constraints must also be valid.

Preserve the original payload length for format parsing and integrity checks. Whether a particular format deliberately includes padding in a digest is a separate specification decision. Do not infer its digest scope from the driver's aligned write length.

End the session when requesting a final flush

The interface requires flush=true to be the last write through that context. Do not append again after a final flush, even when the payload happens to end on an aligned boundary. A subsequent stream requires reinitialization as a new session with valid storage parameters.

The implementation explains one practical risk: after a short final flush, its logical byte counter can be unaligned even though the physical write was aligned. Intermediate durable checkpoints need a separately designed storage strategy; they cannot be implemented by continuing to write through a context that has already been finally flushed.

Likewise, keep the stream context and RAM buffer owned by one coordinated transfer path. Two concurrent producers writing through the same context would need synchronization and ordering that a simple network callback sequence may not provide.

Do not blindly retry a failure after the write stage

With post-write callback support enabled, the implementation can write flash, read back the payload and invoke the callback before advancing its counters. A later read or callback failure can therefore follow a physical write that already occurred. The return value is a failure, but it is not proof that no storage changed.

Design retry and recovery around the actual failing stage. For a disposable test, inject a write failure separately from a readback or callback failure and observe the context and stored region. Replaying the same data without understanding flash programming and erase requirements can be unsafe.

Include final tails of zero, one less than a write block, one full block and just beyond a buffer boundary in the proposed test matrix. Compare logical payload length, buffered count, committed count and physical extent. A reliable completion record explains all four instead of calling them interchangeable totals.