nRF5 SDK for Mesh v3.2.0  08c60f6
Flash Manager

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...
 
const _DEPRECATED fm_entry_tflash_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...
 
const _DEPRECATED fm_entry_tflash_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_tflash_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...
 
static void flash_manager_wait (void)
 Waits for the flash manager to complete all its operations.
 

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_managerFlash manager to initialize.
[in]p_configConfiguration parameters to use for the flash manager.
Return values
NRF_SUCCESSThe manager was added successfully.
NRF_ERROR_NO_MEMThe 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_managerFlash manager to remove.
Return values
NRF_SUCCESSThe given manager has successfully been scheduled for wiping.
NRF_ERROR_NO_MEMNot enough memory to schedule the action.

◆ flash_manager_entry_get()

const _DEPRECATED 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_managerFlash manager to operate on.
[in]handleEntry 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_managerFlash manager to operate on.
[in]handleEntry handle to search for.
[in,out]p_dataBuffer 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_lengthPointer 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_SUCCESSThe 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_STATEThe flash manager is not in a readable state.
NRF_ERROR_NULLAt least one parameter was NULL.
NRF_ERROR_INVALID_PARAMETERThe given handle isn't valid.
NRF_ERROR_NOT_FOUNDThe given handle doesn't exist in the manager.
NRF_ERROR_INVALID_LENGTHThe 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()

const _DEPRECATED 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_managerFlash manager to operate on.
[in]p_filterFilter to apply to search, or NULL if not filter should be applied.
[in]p_startEntry 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_managerFlash manager to operate on.
[in]p_filterFilter to apply to search, or NULL to pass all entries to the read callback.
[in]read_cbRead callback called for every entry that fits the filter, or NULL.
[in,out]p_argsArgument 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_managerFlash manager to operate on.
[in]p_filterFilter 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_managerFlash manager to operate on.
[in]handleEntry handle.
[in]data_lengthWanted length of the entry in bytes, including 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_entryWrite 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_managerFlash manager to operate on.
[in]handleHandle to invalidate.
Return values
NRF_SUCCESSThe entry has successfully been scheduled for invalidation.
NRF_ERROR_NO_MEMThere'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_entryEntry 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_listenerListener 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
trueif the flash manager's write queue is empty.
falseif 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_cbQueue 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.