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 parallel 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 CONFIG_STREAM_FLASH_PROGRESS.

API Reference

group stream_flash

Abstraction over stream writes to flash.

Since

2.3

Version

0.1.0

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.

Param buf:

Pointer to the data read.

Param len:

The length of the data read.

Param 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 write with the flush set to true has to be issued as the last write request for a given context, as it concludes write of a stream, and flushes buffers to storage device.

Warning

There must not be any additional write requests issued for a flushed context, unless it is re-initialized, as such write attempts may result in the function failing and returning error. Once context has been flushed, it can be re-initialized and re-used for new stream flash session.

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

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 ctx then 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.