The Flash Manager provides an entry-based persistent storage interface that works with the mesh. More...

Modules
	Defines
	Flash Manager definitions.

	Types
	Flash Manager type definitions.

Functions
void	flash_manager_init (void)
	Initialize the flash manager.

uint32_t	flash_manager_add (flash_manager_t p_manager, const flash_manager_config_t p_config)
	Add a flash manager instance. More...

uint32_t	flash_manager_remove (flash_manager_t *p_manager)
	Remove the given flash manager, and erase all of its contents. More...

_DEPRECATED const fm_entry_t *	flash_manager_entry_get (const flash_manager_t *p_manager, fm_handle_t handle)
	Get a pointer to the entry with the given index. More...

uint32_t	flash_manager_entry_read (const flash_manager_t p_manager, fm_handle_t handle, void p_data, uint32_t *p_length)
	Read out the contents of the entry with the given handle. More...

_DEPRECATED const fm_entry_t *	flash_manager_entry_next_get (const flash_manager_t p_manager, const fm_handle_filter_t p_filter, const fm_entry_t *p_start)
	Get the next entry matching the given filter. More...

uint32_t	flash_manager_entries_read (const flash_manager_t p_manager, const fm_handle_filter_t p_filter, flash_manager_read_cb_t read_cb, void *p_args)
	Read out flash manager entries. More...

uint32_t	flash_manager_entry_count_get (const flash_manager_t p_manager, const fm_handle_filter_t p_filter)
	Get the number of entries matching the given filter. More...

fm_entry_t *	flash_manager_entry_alloc (flash_manager_t *p_manager, fm_handle_t handle, uint32_t data_length)
	Allocate a buffer for a flash entry write. More...

void	flash_manager_entry_commit (const fm_entry_t *p_entry)
	Commit the given write buffer for flashing. More...

uint32_t	flash_manager_entry_invalidate (flash_manager_t *p_manager, fm_handle_t handle)
	Invalidate the entry with the given handle. More...

void	flash_manager_entry_release (fm_entry_t *p_entry)
	Release an allocated entry buffer that won't be committed after all. More...

void	flash_manager_mem_listener_register (fm_mem_listener_t *p_listener)
	Register a call back to be notified once memory has been made available in the internal buffer. More...

bool	flash_manager_is_stable (void)
	Checks whether the module is in the progress of flashing anything. More...

void	flash_manager_action_queue_empty_cb_set (flash_manager_queue_empty_cb_t queue_empty_cb)
	Sets a function to call when the flash manager's action queue is empty. More...

const void *	flash_manager_recovery_page_get (void)
	Get the address of the recovery page. More...

bool	flash_manager_is_building (flash_manager_t *p_manager)
	Checks whether given flash manager is building the file area. More...

bool	flash_manager_is_removing (flash_manager_t *p_manager)
	Checks whether given flash manager is removing the file area. More...

static void	flash_manager_wait (void)
	Waits for the flash manager to complete all its operations. More...

Detailed Description

The Flash Manager provides an entry-based persistent storage interface that works with the mesh.

The Flash Manager is used to store mesh data, but can also be used by the application.

For more information about the Flash Manager, see the Flash manager library document.

Function Documentation

◆ flash_manager_add()

uint32_t flash_manager_add	(	flash_manager_t *	p_manager,
		const flash_manager_config_t *	p_config
	)

Add a flash manager instance.

Warning: Adding a manager that's already in use may result in unwanted behavior.

Note: Two managers cannot have overlapping regions, and adding a flash manager area that's on top of another will trigger an assert.

Parameters

[in,out]	p_manager	Flash manager to initialize.
[in]	p_config	Configuration parameters to use for the flash manager.

Return values

NRF_SUCCESS	The manager was added successfully.
NRF_ERROR_NO_MEM	The internal buffer ran out of space.

◆ flash_manager_remove()

uint32_t flash_manager_remove ( flash_manager_t * p_manager )

Remove the given flash manager, and erase all of its contents.

All entries known to this manager will become permanently inaccessible and forgotten. If set, the managers remove_complete_cb (flash_manager_remove_complete_cb_t) will be called at the end of this operation. Only at that point will it be safe to reuse the flash area, or re-add the flash manager.

Parameters

[in,out] p_manager Flash manager to remove.

Return values

NRF_SUCCESS	The given manager has successfully been scheduled for wiping.
NRF_ERROR_NO_MEM	Not enough memory to schedule the action.
NRF_ERROR_INVALID_STATE	The flash manager was not in the ready or uninitialized state, and cannot be removed.

◆ flash_manager_entry_get()

_DEPRECATED const fm_entry_t* flash_manager_entry_get	(	const flash_manager_t *	p_manager,
		fm_handle_t	handle
	)

Get a pointer to the entry with the given index.

Parameters

[in]	p_manager	Flash manager to operate on.
[in]	handle	Entry handle to search for.

Returns: The flash entry with the given index, or NULL if no such entry exists.

◆ flash_manager_entry_read()

uint32_t flash_manager_entry_read	(	const flash_manager_t *	p_manager,
		fm_handle_t	handle,
		void *	p_data,
		uint32_t *	p_length
	)

Read out the contents of the entry with the given handle.

Will copy the entry into the p_data buffer, up to the size of the buffer.

Note: The entry length is stored in words, so entries whose size is not word-aligned will get their p_length parameter adjusted even if they are technically the right size. If the there's a mismatch between p_length and the stored length that can't have been caused by the word alignment, the function will return NRF_ERROR_INVALID_LENGTH.

Parameters

[in]	p_manager	Flash manager to operate on.
[in]	handle	Entry handle to search for.
[in,out]	p_data	Buffer to copy entry data into. The buffer must at least be as long as indicated by the initial value of `p_length`.
[in,out]	p_length	Pointer to a variable that holds the length of the given entry in bytes. Will be changed to reflect the actual length of the entry with the given handle.

Return values

NRF_SUCCESS	The entry was found, its data was successfully copied into the `p_data` buffer, and `p_length` was changed to reflect the actual length.
NRF_ERROR_INVALID_STATE	The flash manager is not in a readable state.
NRF_ERROR_NULL	At least one parameter was NULL.
NRF_ERROR_INVALID_PARAMETER	The given handle isn't valid.
NRF_ERROR_NOT_FOUND	The given handle doesn't exist in the manager.
NRF_ERROR_INVALID_LENGTH	The word aligned value of `p_length` does not match the entry length. `p_length` has been changed to indicate the correct length.

◆ flash_manager_entry_next_get()

_DEPRECATED const fm_entry_t* flash_manager_entry_next_get	(	const flash_manager_t *	p_manager,
		const fm_handle_filter_t *	p_filter,
		const fm_entry_t *	p_start
	)

Get the next entry matching the given filter.

Note: The entries will be returned in the order they're stored in, not by index. It's recommended to reset the p_start pointer if any changes are made to the area.

Parameters

[in]	p_manager	Flash manager to operate on.
[in]	p_filter	Filter to apply to search, or NULL if not filter should be applied.
[in]	p_start	Entry to start the search from, or `NULL` if starting from the beginning. This argument acts as an iterator token, allowing the user to get new entries. As long as the area is unchanged, passing the same `p_start` pointer will always return the same entry. To iterate through all entries, keep passing the pointer returned by the previous call.

Returns: The next entry from p_start matching the given filter, or NULL if no such entry exists in the given flash manager.

◆ flash_manager_entries_read()

uint32_t flash_manager_entries_read	(	const flash_manager_t *	p_manager,
		const fm_handle_filter_t *	p_filter,
		flash_manager_read_cb_t	read_cb,
		void *	p_args
	)

Read out flash manager entries.

Iterates through the given flash manager's area and passes each entry to the read callback. Freezes flash operations to avoid manipulating the data through defrag or other procedures.

Note: The order in which the entries are passed to the read callback isn't guaranteed to be the same as the order they're stored in.

Parameters

[in]	p_manager	Flash manager to operate on.
[in]	p_filter	Filter to apply to search, or `NULL` to pass all entries to the read callback.
[in]	read_cb	Read callback called for every entry that fits the filter, or `NULL`.
[in,out]	p_args	Argument pointer that will be passed to the read callback.

Returns: The number of entries read out to the read_cb.

◆ flash_manager_entry_count_get()

uint32_t flash_manager_entry_count_get	(	const flash_manager_t *	p_manager,
		const fm_handle_filter_t *	p_filter
	)

Get the number of entries matching the given filter.

Parameters

[in]	p_manager	Flash manager to operate on.
[in]	p_filter	Filter to apply to search, or `NULL` to count all entries.

Returns: The number of entries matching the given filter.

◆ flash_manager_entry_alloc()

fm_entry_t* flash_manager_entry_alloc	(	flash_manager_t *	p_manager,
		fm_handle_t	handle,
		uint32_t	data_length
	)

Allocate a buffer for a flash entry write.

Ensures that there's enough space in the manager's flash-area, and reserves a buffer in the process queue.

Note: The entry length will be rounded up to the nearest word, and any data in the padding may have garbage values.

Parameters

[in]	p_manager	Flash manager to operate on.
[in]	handle	Entry handle.
[in]	data_length	Wanted length of the entry in bytes, excluding the header. Cannot be longer than FLASH_MANAGER_ENTRY_MAX_SIZE.

Returns: A pointer to a reserved entry in the manager's write queue, that may be committed once the data and handle fields have been filled. The entry length field is prefilled, and shouldn't be altered.; NULL if no space is available in the process queue.

◆ flash_manager_entry_commit()

void flash_manager_entry_commit ( const fm_entry_t * p_entry )

Commit the given write buffer for flashing.

Warning: Will assert if p_entry is not a valid entry obtained through flash_manager_entry_alloc.

Parameters

[in] p_entry Write buffer allocated through flash_manager_entry_alloc.

◆ flash_manager_entry_invalidate()

uint32_t flash_manager_entry_invalidate	(	flash_manager_t *	p_manager,
		fm_handle_t	handle
	)

Invalidate the entry with the given handle.

Parameters

[in]	p_manager	Flash manager to operate on.
[in]	handle	Handle to invalidate.

Return values

NRF_SUCCESS	The entry has successfully been scheduled for invalidation.
NRF_ERROR_NO_MEM	There's not enough space available in the process queue.

◆ flash_manager_entry_release()

void flash_manager_entry_release ( fm_entry_t * p_entry )

Release an allocated entry buffer that won't be committed after all.

Parameters

[in] p_entry Entry to release.

◆ flash_manager_mem_listener_register()

void flash_manager_mem_listener_register ( fm_mem_listener_t * p_listener )

Register a call back to be notified once memory has been made available in the internal buffer.

This can be used to recover from NRF_ERROR_NO_MEM errors from the flash_manager_entry_alloc, flash_manager_remove, and flash_manager_entry_invalidate functions. Once called, the listener may re-attempt its allocation call, and if neccessary, call this function again, to get called the next time there's some more memory available.

Parameters

[in] p_listener Listener to register. Neither the listener or its callback can be NULL. The listener memory must be valid until it's called again.

◆ flash_manager_is_stable()

bool flash_manager_is_stable ( void )

Checks whether the module is in the progress of flashing anything.

Return values

true	if the flash manager's write queue is empty.
false	if the flash manager has some unfinished write operations.

Referenced by flash_manager_wait().

◆ flash_manager_action_queue_empty_cb_set()

void flash_manager_action_queue_empty_cb_set ( flash_manager_queue_empty_cb_t queue_empty_cb )

Sets a function to call when the flash manager's action queue is empty.

Warning: If there is already a callback registered, this function will assert.

Parameters

[in] queue_empty_cb Queue empty callback function or NULL to de-register the active callback.

◆ flash_manager_recovery_page_get()

const void* flash_manager_recovery_page_get ( void )

Get the address of the recovery page.

Returns: A pointer to the recovery page.

◆ flash_manager_is_building()

bool flash_manager_is_building ( flash_manager_t * p_manager )

Checks whether given flash manager is building the file area.

Return values

true	if the flash manager is building the file area.
false	if the flash manager is not building the file area.

◆ flash_manager_is_removing()

bool flash_manager_is_removing ( flash_manager_t * p_manager )

Checks whether given flash manager is removing the file area.

Return values

true	if the flash manager is removing the file area.
false	if the flash manager is not removing the file area.

◆ flash_manager_wait()

static void flash_manager_wait ( void )

inlinestatic

Waits for the flash manager to complete all its operations.

Definition at line 505 of file flash_manager.h.

References flash_manager_is_stable().

Modules

Functions

Detailed Description

Function Documentation

◆ flash_manager_add()

◆ flash_manager_remove()

◆ flash_manager_entry_get()

◆ flash_manager_entry_read()

◆ flash_manager_entry_next_get()

◆ flash_manager_entries_read()

◆ flash_manager_entry_count_get()

◆ flash_manager_entry_alloc()

◆ flash_manager_entry_commit()

◆ flash_manager_entry_invalidate()

◆ flash_manager_entry_release()

◆ flash_manager_mem_listener_register()

◆ flash_manager_is_stable()

◆ flash_manager_action_queue_empty_cb_set()

◆ flash_manager_recovery_page_get()

◆ flash_manager_is_building()

◆ flash_manager_is_removing()

◆ flash_manager_wait()