nRF5 SDK for Mesh v3.2.0  08c60f6
flash_manager.h
1 /* Copyright (c) 2010 - 2019, Nordic Semiconductor ASA
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without modification,
5  * are permitted provided that the following conditions are met:
6  *
7  * 1. Redistributions of source code must retain the above copyright notice, this
8  * list of conditions and the following disclaimer.
9  *
10  * 2. Redistributions in binary form, except as embedded into a Nordic
11  * Semiconductor ASA integrated circuit in a product or a software update for
12  * such product, must reproduce the above copyright notice, this list of
13  * conditions and the following disclaimer in the documentation and/or other
14  * materials provided with the distribution.
15  *
16  * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
17  * contributors may be used to endorse or promote products derived from this
18  * software without specific prior written permission.
19  *
20  * 4. This software, with or without modification, must only be used with a
21  * Nordic Semiconductor ASA integrated circuit.
22  *
23  * 5. Any software provided in binary form under this license must not be reverse
24  * engineered, decompiled, modified and/or disassembled.
25  *
26  * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
27  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28  * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
29  * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
30  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
32  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
35  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36  */
37 #ifndef FLASH_MANAGER_H__
38 #define FLASH_MANAGER_H__
39 
40 #include <stdint.h>
41 #include <stdbool.h>
42 
43 #include "packet_buffer.h"
44 #include "nrf_mesh_config_core.h"
45 #include "queue.h"
46 #include "toolchain.h"
47 #include "bearer_event.h"
48 
66 #define FLASH_MANAGER_DATA_PER_PAGE (PAGE_SIZE - sizeof(flash_manager_metadata_t))
67 
74 #define FLASH_MANAGER_PAGE_COUNT_MINIMUM(DATA_SIZE, LARGEST_ENTRY_SIZE) (1 + ((DATA_SIZE) / (FLASH_MANAGER_DATA_PER_PAGE - LARGEST_ENTRY_SIZE)))
75 
76 #define FLASH_MANAGER_HANDLE_MAX (0x7EFF)
77 #define FLASH_MANAGER_HANDLE_INVALID (0x0000)
79 #define FLASH_MANAGER_ENTRY_LEN_OVERHEAD (sizeof(fm_header_t) / WORD_SIZE)
90 typedef uint16_t fm_handle_t;
91 
93 typedef struct
94 {
95  uint16_t len_words;
97 } fm_header_t;
98 
103 typedef struct
104 {
108 
110 typedef struct
111 {
112  fm_header_t header;
113  uint32_t data[];
114 } fm_entry_t;
115 
117 typedef enum
118 {
119  FM_STATE_UNINITIALIZED,
120  FM_STATE_BUILDING,
121  FM_STATE_READY,
122  FM_STATE_DEFRAG,
123  FM_STATE_REMOVING
124 } fm_state_t;
125 
127 typedef struct
128 {
129  uint8_t metadata_len;
134  uint8_t pages_in_area;
135  uint8_t page_index;
136  uint16_t _padding;
138 
140 typedef union
141 {
143  uint8_t raw[PAGE_SIZE];
145 
146 typedef struct flash_manager flash_manager_t;
147 
149 typedef enum
150 {
155 } fm_result_t;
156 
169 typedef void (*flash_manager_write_complete_cb_t)(const flash_manager_t * p_manager,
170  const fm_entry_t * p_entry,
171  fm_result_t result);
172 
181 typedef void (*flash_manager_invalidate_complete_cb_t)(const flash_manager_t * p_manager,
182  fm_handle_t handle,
183  fm_result_t result);
184 
193 typedef void (*flash_manager_remove_complete_cb_t)(const flash_manager_t * p_manager);
194 
199 typedef void (*flash_manager_queue_empty_cb_t)(void);
200 
204 typedef struct
205 {
207  uint32_t page_count;
214 
216 typedef struct
217 {
219  uint32_t invalid_bytes;
220  const fm_entry_t * p_seal;
222 
224 {
227 };
228 
234 typedef void (*flash_manager_mem_listener_cb_t)(void * p_args);
235 
237 typedef struct
238 {
239  queue_elem_t queue_elem;
241  void * p_args;
243 
245 typedef enum
246 {
250 
263 typedef fm_iterate_action_t (*flash_manager_read_cb_t)(const fm_entry_t * p_entry, void * p_args);
264 
270 void flash_manager_init(void);
271 
286 uint32_t flash_manager_add(flash_manager_t * p_manager,
287  const flash_manager_config_t * p_config);
288 
302 uint32_t flash_manager_remove(flash_manager_t * p_manager);
303 
314 _DEPRECATED const fm_entry_t * flash_manager_entry_get(const flash_manager_t * p_manager, fm_handle_t handle);
315 
342 uint32_t flash_manager_entry_read(const flash_manager_t * p_manager,
343  fm_handle_t handle,
344  void * p_data,
345  uint32_t * p_length);
346 
365 _DEPRECATED const fm_entry_t * flash_manager_entry_next_get(const flash_manager_t * p_manager,
366  const fm_handle_filter_t * p_filter,
367  const fm_entry_t * p_start);
368 
369 
386 uint32_t flash_manager_entries_read(const flash_manager_t * p_manager,
387  const fm_handle_filter_t * p_filter,
388  flash_manager_read_cb_t read_cb,
389  void * p_args);
390 
399 uint32_t flash_manager_entry_count_get(const flash_manager_t * p_manager, const fm_handle_filter_t * p_filter);
400 
418 fm_entry_t * flash_manager_entry_alloc(flash_manager_t * p_manager,
419  fm_handle_t handle,
420  uint32_t data_length);
421 
430 void flash_manager_entry_commit(const fm_entry_t * p_entry);
431 
441 uint32_t flash_manager_entry_invalidate(flash_manager_t * p_manager, fm_handle_t handle);
442 
449 
461 
468 bool flash_manager_is_stable(void);
469 
479 
485 const void * flash_manager_recovery_page_get(void);
486 
487 
489 static inline void flash_manager_wait(void)
490 {
491 #if !defined(HOST)
492  while (!flash_manager_is_stable())
493  {
494  /* Temporary hack to make sure that bearer events are handled while waiting for
495  * the flash manager to finish.
496  * TODO: Find a solution for this that does not include busy-waiting. */
497  if (bearer_event_handler())
498  {
499  __WFE();
500  }
501  }
502 #endif
503 }
504 
505 
508 #endif /* FLASH_MANAGER_H__ */
flash_manager_config_t
Flash manager configuration structure, defines the user-configurable parts of the flash manager.
Definition: flash_manager.h:204
fm_handle_filter_t::match
fm_handle_t match
Value that the masked portion of the handle has to match.
Definition: flash_manager.h:106
flash_manager_metadata_t::entry_type_length_bits
uint8_t entry_type_length_bits
Length of entry type field in bits.
Definition: flash_manager.h:132
flash_manager_page_t::metadata
flash_manager_metadata_t metadata
Metadata at the start of every managed page.
Definition: flash_manager.h:142
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.
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.
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.
flash_manager_queue_empty_cb_t
void(* flash_manager_queue_empty_cb_t)(void)
Action queue empty callback, indicating that the flash manager is finished processing all its ongoing...
Definition: flash_manager.h:199
FM_RESULT_ERROR_FLASH_MALFUNCTION
The flash HW malfunctioned, and the operation did not finish correctly.
Definition: flash_manager.h:154
FM_RESULT_ERROR_NOT_FOUND
The entry wasn't present in the manager.
Definition: flash_manager.h:153
flash_manager::config
flash_manager_config_t config
Manager configuration, as set by the user.
Definition: flash_manager.h:226
flash_manager_init
void flash_manager_init(void)
Initialize the flash manager.
fm_header_t
Header prepending every flash entry in a flash manager.
Definition: flash_manager.h:93
flash_manager_config_t::remove_complete_cb
flash_manager_remove_complete_cb_t remove_complete_cb
Callback called after the manager has been successfully removed.
Definition: flash_manager.h:212
flash_manager_internal_state_t::p_seal
const fm_entry_t * p_seal
Pointer to the seal entry.
Definition: flash_manager.h:220
flash_manager_config_t::page_count
uint32_t page_count
Number of pages in the area.
Definition: flash_manager.h:207
flash_manager_metadata_t::metadata_len
uint8_t metadata_len
Length of manager metadata in bytes.
Definition: flash_manager.h:129
fm_mem_listener_t::queue_elem
queue_elem_t queue_elem
Used for linked list operation, should not be altered by the user.
Definition: flash_manager.h:239
fm_mem_listener_t::p_args
void * p_args
Arguments pointer, set by the user and returned in the callback.
Definition: flash_manager.h:241
fm_state_t
fm_state_t
Valid state of a flash manager instance.
Definition: flash_manager.h:117
fm_handle_t
uint16_t fm_handle_t
Flash manager handle type, used to identify entries in a flash manager area.
Definition: flash_manager.h:90
fm_mem_listener_t
Memory listener.
Definition: flash_manager.h:237
flash_manager_wait
static void flash_manager_wait(void)
Waits for the flash manager to complete all its operations.
Definition: flash_manager.h:489
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.
flash_manager_metadata_t::page_index
uint8_t page_index
Index of this page in its area.
Definition: flash_manager.h:135
flash_manager_config_t::min_available_space
uint32_t min_available_space
Number of bytes that should always be left available during normal operation.
Definition: flash_manager.h:208
flash_manager_write_complete_cb_t
void(* flash_manager_write_complete_cb_t)(const flash_manager_t *p_manager, const fm_entry_t *p_entry, fm_result_t result)
Write complete callback, to give the user the result of an entry write action.
Definition: flash_manager.h:169
flash_manager_internal_state_t::invalid_bytes
uint32_t invalid_bytes
Bytes invalidated in the area.
Definition: flash_manager.h:219
flash_manager
Definition: flash_manager.h:223
flash_manager_recovery_page_get
const void * flash_manager_recovery_page_get(void)
Get the address of the recovery page.
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.
flash_manager_mem_listener_cb_t
void(* flash_manager_mem_listener_cb_t)(void *p_args)
Memory listener callback, that will be called once the flash manager has some memory available.
Definition: flash_manager.h:234
flash_manager_read_cb_t
fm_iterate_action_t(* flash_manager_read_cb_t)(const fm_entry_t *p_entry, void *p_args)
Entry read callback type.
Definition: flash_manager.h:263
flash_manager_invalidate_complete_cb_t
void(* flash_manager_invalidate_complete_cb_t)(const flash_manager_t *p_manager, fm_handle_t handle, fm_result_t result)
Invalidate complete callback, to give the user the result of an entry invalidation action.
Definition: flash_manager.h:181
FM_ITERATE_ACTION_STOP
Stop iterating through the entries.
Definition: flash_manager.h:247
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.
flash_manager_config_t::p_area
const flash_manager_page_t * p_area
Start of area owned by this flash manager.
Definition: flash_manager.h:206
flash_manager_metadata_t::entry_len_length_bits
uint8_t entry_len_length_bits
Length of entry len field in bits.
Definition: flash_manager.h:131
flash_manager_remove
uint32_t flash_manager_remove(flash_manager_t *p_manager)
Remove the given flash manager, and erase all of its contents.
fm_result_t
fm_result_t
Flash action result, returned in complete-callback.
Definition: flash_manager.h:149
flash_manager_metadata_t::entry_header_length
uint8_t entry_header_length
Length of each entry header in bytes.
Definition: flash_manager.h:130
fm_entry_t
Single flash manager entry.
Definition: flash_manager.h:110
fm_mem_listener_t::callback
flash_manager_mem_listener_cb_t callback
Callback to call when there's memory available.
Definition: flash_manager.h:240
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.
flash_manager_internal_state_t
Internal flash manager state, managed and used internally.
Definition: flash_manager.h:216
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.
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.
flash_manager_is_stable
bool flash_manager_is_stable(void)
Checks whether the module is in the progress of flashing anything.
flash_manager_config_t::invalidate_complete_cb
flash_manager_invalidate_complete_cb_t invalidate_complete_cb
Callback called after every completed entry invalidation, or NULL.
Definition: flash_manager.h:211
fm_header_t::handle
fm_handle_t handle
Entry handle.
Definition: flash_manager.h:96
flash_manager_remove_complete_cb_t
void(* flash_manager_remove_complete_cb_t)(const flash_manager_t *p_manager)
Remove complete callback, indicating that the requested remove operation has been completed.
Definition: flash_manager.h:193
fm_iterate_action_t
fm_iterate_action_t
Action returned from the read callback, determining whether to continue the iteration.
Definition: flash_manager.h:245
fm_handle_filter_t::mask
fm_handle_t mask
Mask to apply to the match value when comparing with a handle.
Definition: flash_manager.h:105
flash_manager_metadata_t::pages_in_area
uint8_t pages_in_area
Total number of pages in this area.
Definition: flash_manager.h:134
flash_manager_entry_commit
void flash_manager_entry_commit(const fm_entry_t *p_entry)
Commit the given write buffer for flashing.
flash_manager_config_t::write_complete_cb
flash_manager_write_complete_cb_t write_complete_cb
Callback called after every completed write action, or NULL.
Definition: flash_manager.h:210
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.
FM_RESULT_SUCCESS
The action completed successfully.
Definition: flash_manager.h:151
FM_RESULT_ERROR_AREA_FULL
The managed flash area is full, and cannot accept any new entries.
Definition: flash_manager.h:152
flash_manager_internal_state_t::state
fm_state_t state
State of the manager.
Definition: flash_manager.h:218
fm_header_t::len_words
uint16_t len_words
Length of entry in words, including header.
Definition: flash_manager.h:95
flash_manager_page_t
Single flash manager page.
Definition: flash_manager.h:140
flash_manager_metadata_t
Metadata structure denoting properties of a flash manager page.
Definition: flash_manager.h:127
fm_handle_filter_t
Handle filter, used to search through all handles to find matches.
Definition: flash_manager.h:103
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.
FM_ITERATE_ACTION_CONTINUE
Continue iterating through the entries.
Definition: flash_manager.h:248