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.

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.

Return

non-negative on success, negative errno code on fail

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.

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

Return

Number of payload bytes written to flash.

Parameters

  • ctx: context

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.

Return

non-negative on success, negative errno code on fail

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).

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).

Return

non-negative on success, negative errno code on fail

Parameters

  • ctx: context

  • off: offset from the base address of the flash device

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.