Stream to flash interface

Abstraction over stream writes to flash. More...

Data Structures
struct	stream_flash_ctx
	Structure for stream flash context. More...

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
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.
size_t	stream_flash_bytes_written (const struct stream_flash_ctx *ctx)
	Read number of bytes written to the 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.
int	stream_flash_erase_page (struct stream_flash_ctx *ctx, off_t off)
	Erase the flash page to which a given offset belongs.
int	stream_flash_progress_load (struct stream_flash_ctx *ctx, const char *settings_key)
	Load persistent stream write progress stored with key settings_key .
int	stream_flash_progress_save (const struct stream_flash_ctx *ctx, const char *settings_key)
	Save persistent stream write progress using key settings_key .
int	stream_flash_progress_clear (const struct stream_flash_ctx *ctx, const char *settings_key)
	Clear persistent stream write progress stored with key settings_key .

Detailed Description

Abstraction over stream writes to flash.

Since

2.3

Version

0.1.0

Typedef Documentation

stream_flash_callback_t

typedef int(* stream_flash_callback_t) (uint8_t *buf, size_t len, size_t offset)

#include <zephyr/storage/stream_flash.h>

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.

Function Documentation

stream_flash_buffered_write()

int stream_flash_buffered_write	(	struct stream_flash_ctx *	ctx,
		const uint8_t *	data,
		size_t	len,
		bool	flush )

#include <zephyr/storage/stream_flash.h>

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

stream_flash_bytes_written()

size_t stream_flash_bytes_written

(

const struct stream_flash_ctx *

ctx

)

#include <zephyr/storage/stream_flash.h>

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.

stream_flash_erase_page()

int stream_flash_erase_page	(	struct stream_flash_ctx *	ctx,
		off_t	off )

#include <zephyr/storage/stream_flash.h>

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

stream_flash_init()

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 )

#include <zephyr/storage/stream_flash.h>

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. Callback is supported when CONFIG_STREAM_FLASH_POST_WRITE_CALLBACK is enabled.

Returns

non-negative on success, negative errno code on fail

stream_flash_progress_clear()

int stream_flash_progress_clear	(	const struct stream_flash_ctx *	ctx,
		const char *	settings_key )

#include <zephyr/storage/stream_flash.h>

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

stream_flash_progress_load()

int stream_flash_progress_load	(	struct stream_flash_ctx *	ctx,
		const char *	settings_key )

#include <zephyr/storage/stream_flash.h>

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, -ERANGE in case when off is out of area designated for stream or negative errno code on fail

stream_flash_progress_save()

int stream_flash_progress_save	(	const struct stream_flash_ctx *	ctx,
		const char *	settings_key )

#include <zephyr/storage/stream_flash.h>

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