Stream Flash¶
The Stream Flash module takes contiguous fragments of a stream of data (e.g. from radio packets), aggregates them into a user-provided buffer, then when the buffer fills (or stream ends) writes it to a raw flash partition. It supports providing the read-back buffer to the client to use in validating the persisted stream content.
One typical use of a stream write operation is when receiving a new firmware image to be used in a DFU operation.
There are several reasons why one might want to use buffered writes instead of writing the data directly as it is made available. Some devices have hardware limitations which does not allow flash writes to be performed in parallell with other operations, such as radio RX and TX. Also, fewer write operations result in faster response times seen from the application.
Persistent stream write progress¶
Some stream write operations, such as DFU operations, may run for a long time. When performing such long running operations it can be useful to be able to save the stream write progress to persistent storage so that the operation can resume at the same point after an unexpected interruption.
The Stream Flash module offers an API for loading, saving and clearing stream write progress to persistent storage using the Settings module. The API can be enabled using :kconfig:`CONFIG_STREAM_FLASH_PROGRESS`.
API Reference¶
-
group
stream_flash Abstraction over stream writes to flash.
Typedefs
-
typedef int (*
stream_flash_callback_t)(uint8_t *buf, size_t len, size_t offset)¶ Signature for callback invoked after flash write completes.
Functions of this type are invoked with a buffer containing data read back from the flash after a flash write has completed. This enables verifying that the data has been correctly stored (for instance by using a SHA function). The write buffer ‘buf’ provided in stream_flash_init is used as a read buffer for this purpose.
- Parameters
buf – Pointer to the data read.
len – The length of the data read.
offset – The offset the data was read from.
Functions
-
int
stream_flash_init(struct stream_flash_ctx *ctx, const struct device *fdev, uint8_t *buf, size_t buf_len, size_t offset, size_t size, stream_flash_callback_t cb)¶ Initialize context needed for stream writes to flash.
- Parameters
ctx – context to be initialized
fdev – Flash device to operate on
buf – Write buffer
buf_len – Length of write buffer. Can not be larger than the page size. Must be multiple of the flash device write-block-size.
offset – Offset within flash device to start writing to
size – Number of bytes available for performing buffered write. If this is ‘0’, the size will be set to the total size of the flash device minus the offset.
cb – Callback to be invoked on completed flash write operations.
- Returns
non-negative on success, negative errno code on fail
-
size_t
stream_flash_bytes_written(struct stream_flash_ctx *ctx)¶ Read number of bytes written to the flash.
Note
api-tags: pre-kernel-ok isr-ok
- Parameters
ctx – context
- Returns
Number of payload bytes written to flash.
-
int
stream_flash_buffered_write(struct stream_flash_ctx *ctx, const uint8_t *data, size_t len, bool flush)¶ Process input buffers to be written to flash device in single blocks. Will store remainder between calls.
A final call to this function with flush set to true will write out the remaining block buffer to flash.
- Parameters
ctx – context
data – data to write
len – Number of bytes to write
flush – when true this forces any buffered data to be written to flash A flush write should be the last write operation in a sequence of write operations for given context (although this is not mandatory if the total data size is a multiple of the buffer size).
- Returns
non-negative on success, negative errno code on fail
-
int
stream_flash_erase_page(struct stream_flash_ctx *ctx, off_t off)¶ Erase the flash page to which a given offset belongs.
This function erases a flash page to which an offset belongs if this page is not the page previously erased by the provided ctx (ctx->last_erased_page_start_offset).
- Parameters
ctx – context
off – offset from the base address of the flash device
- Returns
non-negative on success, negative errno code on fail
-
int
stream_flash_progress_load(struct stream_flash_ctx *ctx, const char *settings_key)¶ Load persistent stream write progress stored with key
settings_key.This function should be called directly after stream_flash_init to load previous stream write progress before writing any data. If the loaded progress has fewer bytes written than
ctxthen it will be ignored.- Parameters
ctx – context
settings_key – key to use with the settings module for loading the stream write progress
- Returns
non-negative on success, negative errno code on fail
-
int
stream_flash_progress_save(struct stream_flash_ctx *ctx, const char *settings_key)¶ Save persistent stream write progress using key
settings_key.- Parameters
ctx – context
settings_key – key to use with the settings module for storing the stream write progress
- Returns
non-negative on success, negative errno code on fail
-
int
stream_flash_progress_clear(struct stream_flash_ctx *ctx, const char *settings_key)¶ Clear persistent stream write progress stored with key
settings_key.- Parameters
ctx – context
settings_key – key previously used for storing the stream write progress
- Returns
non-negative on success, negative errno code on fail
-
struct
stream_flash_ctx¶ - #include <stream_flash.h>
Structure for stream flash context.
Users should treat these structures as opaque values and only interact with them through the below API.
-
typedef int (*