The Flash Manager provides an entry-based persistent storage interface that works with the mesh.
More...
|
| Defines |
| Flash Manager definitions.
|
|
| Types |
| Flash Manager type definitions.
|
|
|
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...
|
|
static void | flash_manager_wait (void) |
| Waits for the flash manager to complete all its operations. More...
|
|
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.
◆ flash_manager_add()
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. |
◆ 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()
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()
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, 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
-
◆ 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()
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()
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_wait()
static void flash_manager_wait |
( |
void |
| ) |
|
|
inlinestatic |