Interface and implementations for storing data into flash in a persistent manner. More...

Files
file	ruuvi_interface_flash_test.h

file	ruuvi_interface_flash.h
	Interface functions to persistent flash storage.

Macros
#define	RI_FLASH_PAGES (10U)
	Enable implementation selected by application. More...

Functions
bool	ri_flash_run_integration_test (const rd_test_print_fp printfp)
	Run all flash tests. More...

rd_status_t	ri_flash_total_size_get (size_t *size)
	Get total size of usable flash, excluding any overhead bytes. More...

rd_status_t	ri_flash_page_size_get (size_t *size)
	Get size of usable page, excluding any overhead bytes If returned value is N, a record of N bytes must fit in one page. More...

rd_status_t	ri_flash_free_size_get (size_t *size)
	Get total size of free flash. More...

rd_status_t	ri_flash_record_delete (const uint32_t file_id, const uint32_t record_id)
	Mark a record for deletion. More...

rd_status_t	ri_flash_record_set (const uint32_t page_id, const uint32_t record_id, const size_t data_size, const void *const data)
	Set data to record in page. More...

rd_status_t	ri_flash_record_get (const uint32_t page_id, const uint32_t record_id, const size_t data_size, void *const data)
	Get data from record in page. More...

rd_status_t	ri_flash_gc_run (void)
	Run garbage collection. More...

rd_status_t	ri_flash_init (void)

rd_status_t	ri_flash_uninit (void)
	Unintialize flash. After uninitialization only initialization can be used. More...

void	ri_flash_purge (void)
	Purge flash. More...

bool	ri_flash_is_busy ()
	Check if flash is busy. More...

rd_status_t	ri_flash_protect (const size_t page)

Detailed Description

Interface and implementations for storing data into flash in a persistent manner.

Macro Definition Documentation

◆ RI_FLASH_PAGES

#define RI_FLASH_PAGES (10U)

Enable implementation selected by application.

Definition at line 37 of file ruuvi_interface_flash.h.

Function Documentation

◆ ri_flash_free_size_get()

rd_status_t ri_flash_free_size_get ( size_t * size )

Get total size of free flash.

Parameters

[out] size size of useable storage in bytes.

Return values

RD_SUCCESS	on success.
RD_ERROR_NULL	if size is null.
RD_ERROR_INVALID_STATE	if flash storage is not initialized.
error	code from stack on other error.

◆ ri_flash_gc_run()

rd_status_t ri_flash_gc_run ( void )

Run garbage collection.

Return values

RD_SUCCESS	on success.
RD_INVALID_STATE	if flash is not initialized.
error	code from stack on other error.

◆ ri_flash_init()

rd_status_t ri_flash_init ( void )

Initialize flash. After initialization other flash functions can be used.

Return values

RD_SUCCESS	on success.
RD_ERROR_INVALID_STATE	if flash is already initialized.
RD_ERROR_INVALID_LENGTH	if space configured in linker does not match space reserved by implementation.

◆ ri_flash_is_busy()

bool ri_flash_is_busy ( )

Check if flash is busy.

Returns: True if flash is running an operation.; False if flash is idle.

◆ ri_flash_page_size_get()

rd_status_t ri_flash_page_size_get ( size_t * size )

Get size of usable page, excluding any overhead bytes If returned value is N, a record of N bytes must fit in one page.

Parameters

[out] size Size of useable storage in bytes.

Return values

RD_SUCCESS	on success.
RD_ERROR_NULL	if size is null.
RD_ERROR_INVALID_STATE	if flash storage is not initialized.
error	code from stack on other error.

◆ ri_flash_protect()

rd_status_t ri_flash_protect ( const size_t page )

Protects a page in flash against overwriting. After protection has been enabled, only reset will clear the protection.

Parameters

page	Flash page to protect

Returns: RD_SUCCESS on success; RD_ERROR_INVALID_PARAM if target chip does not have given page.

◆ ri_flash_purge()

void ri_flash_purge ( void )

Purge flash.

This function is used to "rescue" flash which cannot be initialized normally, for example after data corruption. Completely erases all data content on flash. Does not erase application files.

This function is blocking, returns once flash is cleared.

◆ ri_flash_record_delete()

rd_status_t ri_flash_record_delete	(	const uint32_t	file_id,
		const uint32_t	record_id
	)

Mark a record for deletion.

Note that this only marks the record as freed and does not physically overwrite the flash. The function only starts the operation and returns immediately.

Parameters

[in]	file_id	ID of file which contains the record.
[in]	record_id	ID of record to delete.

Return values

RD_SUCCESS	if deletion was queued.
RD_ERROR_INVALID_STATE	if flash storage is not initialized.
RD_ERROR_BUSY	if another operation was ongoing.
RD_ERROR_NOT_FOUND	if give record was not found.

◆ ri_flash_record_get()

rd_status_t ri_flash_record_get	(	const uint32_t	page_id,
		const uint32_t	record_id,
		const size_t	data_size,
		void *const	data
	)

Get data from record in page.

Returns after data is read and ready to be used or error has occured.

Parameters

[in]	page_id	ID of a page. Can be random number.
[in]	record_id	ID of a record. Can be a random number.
[in,out]	data_size	input: Maximum size of data to retrieve. Output: Number of bytes retrieved.
[in]	data	pointer to memory which will be filled with retrieved data.

Return values

RD_SUCCESS	on success.
RD_ERROR_NULL	if data is null.
RD_ERROR_INVALID_STATE	if flash storage is not initialized.
RD_ERROR_NOT_FOUND	if given page id does not exist or if given record_id does not exist on given page.
error	code from stack on other error.

◆ ri_flash_record_set()

rd_status_t ri_flash_record_set	(	const uint32_t	page_id,
		const uint32_t	record_id,
		const size_t	data_size,
		const void *const	data
	)

Set data to record in page.

Automatically runs garbage collection if record cannot fit on page. Returns after data is successfully written or error has occured.

Parameters

[in]	page_id	ID of a page. Can be random number.
[in]	record_id	ID of a record. Can be a random number.
[in]	data_size	size data to store
[in]	data	pointer to data to store.

Return values

RD_SUCCESS	on success
RD_ERROR_NULL	if data is null
RD_ERROR_INVALID_STATE	if flash storage is not initialized
RD_ERROR_BUSY	if another operation is ongoing.
RD_ERROR_DATA_SIZE	if record is too large to fit on page
RD_ERROR_NO_MEM	if this record cannot fit on page.
error	code from stack on other error

◆ ri_flash_run_integration_test()

bool ri_flash_run_integration_test ( const rd_test_print_fp printfp )

Run all flash tests.

Parameters

[in] printfp Function pointer to which test result is printed.

Returns: false if test had no errors, true otherwise.

◆ ri_flash_total_size_get()

rd_status_t ri_flash_total_size_get ( size_t * size )

Get total size of usable flash, excluding any overhead bytes.

Parameters

[out] size Size of useable storage in bytes.

Return values

RD_SUCCESS	on success.
RD_ERROR_NULL	if size is null.
RD_ERROR_INVALID_STATE	if flash storage is not initialized.
error	code from stack on other error.

◆ ri_flash_uninit()

rd_status_t ri_flash_uninit ( void )

Unintialize flash. After uninitialization only initialization can be used.

Return values

RD_SUCCESS on success.

Files

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RI_FLASH_PAGES

Function Documentation

◆ ri_flash_free_size_get()

◆ ri_flash_gc_run()

◆ ri_flash_init()

◆ ri_flash_is_busy()

◆ ri_flash_page_size_get()

◆ ri_flash_protect()

◆ ri_flash_purge()

◆ ri_flash_record_delete()

◆ ri_flash_record_get()

◆ ri_flash_record_set()

◆ ri_flash_run_integration_test()

◆ ri_flash_total_size_get()

◆ ri_flash_uninit()