nRF5 SDK v12.1.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions

Module which provides functionality to store data to flash and erase flash pages. More...

Modules

 Flash storage module configuration
 

Data Structures

struct  fs_evt_t
 An fstorage event. More...
 
struct  fs_config_t
 fstorage application-specific configuration. More...
 

Macros

#define FS_REGISTER_CFG(cfg_var)   NRF_SECTION_VARS_REGISTER_VAR(fs_data, cfg_var)
 Macro for registering an fstorage configuration variable. Applications which use fstorage must register with the module using this macro. Registering involves defining a variable which holds the configuration of fstorage specific to the application which invokes the macro. More...
 

Typedefs

typedef void(* fs_cb_t )(fs_evt_t const *const evt, fs_ret_t result)
 fstorage event handler function prototype. More...
 

Enumerations

enum  fs_ret_t {
  FS_SUCCESS,
  FS_ERR_NOT_INITIALIZED,
  FS_ERR_INVALID_CFG,
  FS_ERR_NULL_ARG,
  FS_ERR_INVALID_ARG,
  FS_ERR_INVALID_ADDR,
  FS_ERR_UNALIGNED_ADDR,
  FS_ERR_QUEUE_FULL,
  FS_ERR_OPERATION_TIMEOUT,
  FS_ERR_INTERNAL,
  FS_ERR_FAILURE_SINCE_LAST
}
 fstorage return values. More...
 
enum  fs_evt_id_t {
  FS_EVT_STORE,
  FS_EVT_ERASE
}
 fstorage event IDs. More...
 

Functions

fs_ret_t fs_init (void)
 Function for initializing the module. More...
 
fs_ret_t fs_fake_init (void)
 
bool fs_check_addr (uint32_t const *const p_dest, uint32_t const *const p_src)
 
fs_ret_t fs_store (fs_config_t const *const p_config, uint32_t const *const p_dest, uint32_t const *const p_src, uint16_t length_words, void *p_context)
 Function for storing data in flash. More...
 
fs_ret_t fs_erase (fs_config_t const *const p_config, uint32_t const *const p_page_addr, uint16_t num_pages, void *p_context)
 Function for erasing flash pages. More...
 
fs_ret_t fs_queued_op_count_get (uint32_t *const p_op_count)
 Function for retrieving the number of queued flash operations. More...
 
void fs_sys_event_handler (uint32_t sys_evt)
 Function for handling system events from the SoftDevice. More...
 

Detailed Description

Module which provides functionality to store data to flash and erase flash pages.

Macro Definition Documentation

#define FS_REGISTER_CFG (   cfg_var)    NRF_SECTION_VARS_REGISTER_VAR(fs_data, cfg_var)

Macro for registering an fstorage configuration variable. Applications which use fstorage must register with the module using this macro. Registering involves defining a variable which holds the configuration of fstorage specific to the application which invokes the macro.

This macro places the configuration variable in a section named "fs_data" that fstorage uses during initialization and regular operation.

Parameters
[in]cfg_varA definition of a fs_config_t variable.

Typedef Documentation

typedef void(* fs_cb_t)(fs_evt_t const *const evt, fs_ret_t result)

fstorage event handler function prototype.

Parameters
[in]evtThe event.
[in]resultThe result of the operation.

Enumeration Type Documentation

fstorage event IDs.

Enumerator
FS_EVT_STORE 

Event for fs_store.

FS_EVT_ERASE 

Event for fs_erase.

enum fs_ret_t

fstorage return values.

Enumerator
FS_ERR_NOT_INITIALIZED 

Error. The module is not initialized.

FS_ERR_INVALID_CFG 

Error. Invalid fstorage configuration.

FS_ERR_NULL_ARG 

Error. Argument is NULL.

FS_ERR_INVALID_ARG 

Error. Argument contains invalid data.

FS_ERR_INVALID_ADDR 

Error. Address out of bounds.

FS_ERR_UNALIGNED_ADDR 

Error. Unaligned address.

FS_ERR_QUEUE_FULL 

Error. Queue is full.

FS_ERR_OPERATION_TIMEOUT 

Error. The operation has timed out.

FS_ERR_INTERNAL 

Error. Internal error.

FS_ERR_FAILURE_SINCE_LAST 

Error. Uncleared error since last call.

Function Documentation

fs_ret_t fs_erase ( fs_config_t const *const  p_config,
uint32_t const *const  p_page_addr,
uint16_t  num_pages,
void *  p_context 
)

Function for erasing flash pages.

Starting from the page at p_page_addr, erases num_pages flash pages. p_page_addr must be aligned to a page boundary. All pages to be erased must be within the bounds specified in the supplied fstorage configuration. This function is asynchronous. Completion is reported via an event.

Parameters
[in]p_configfstorage configuration registered by the application.
[in]p_page_addrAddress of the page to erase. Must be aligned to a page boundary.
[in]num_pagesNumber of pages to erase. May not be zero.
[in]p_contextUser-defined context passed to the interrupt handler.
Return values
FS_SUCCESSIf the operation was queued successfully.
FS_ERR_NOT_INITIALIZEDIf the module is not initialized.
FS_ERR_INVALID_CFGIf p_config is NULL or contains invalid data.
FS_ERR_NULL_ARGIf p_page_addr is NULL.
FS_ERR_INVALID_ARGIf num_pages is zero.
FS_ERR_INVALID_ADDRIf the operation would go beyond the flash memory boundaries specified in p_config.
FS_ERR_UNALIGNED_ADDRIf p_page_addr is not aligned to a page boundary.
FS_ERR_QUEUE_FULLIf the internal operation queue is full.
fs_ret_t fs_init ( void  )

Function for initializing the module.

This functions assigns pages in flash according to all registered configurations.

Return values
FS_SUCCESSIf the module was successfully initialized.
fs_ret_t fs_queued_op_count_get ( uint32_t *const  p_op_count)

Function for retrieving the number of queued flash operations.

Parameters
[out]p_op_countThe number of queued flash operations.
Return values
FS_SUCCESSIf the number of queued operations was retrieved successfully.
FS_ERR_NULL_ARGIf p_op_count is NULL.
fs_ret_t fs_store ( fs_config_t const *const  p_config,
uint32_t const *const  p_dest,
uint32_t const *const  p_src,
uint16_t  length_words,
void *  p_context 
)

Function for storing data in flash.

Copies length_words words from p_src to the location pointed by p_dest. If the length of the data exceeds FS_MAX_WRITE_SIZE_WORDS, the data will be written down in several chunks, as necessary. Only one event will be sent to the application upon completion. Both the source and the destination of the data must be word aligned. This function is asynchronous, completion is reported via an event sent the the callback function specified in the supplied configuration.

Warning
The data to be written to flash has to be kept in memory until the operation has terminated, i.e., an event is received.
Parameters
[in]p_configfstorage configuration registered by the application.
[in]p_destThe address in flash memory where to store the data.
[in]p_srcPointer to the data to store in flash.
[in]length_wordsLength of the data to store, in words.
[in]p_contextUser-defined context passed to the interrupt handler.
Return values
FS_SUCCESSIf the operation was queued successfully.
FS_ERR_NOT_INITIALIZEDIf the module is not initialized.
FS_ERR_INVALID_CFGIf p_config is NULL or contains invalid data.
FS_ERR_NULL_ARGIf p_dest or p_src are NULL.
FS_ERR_INVALID_ARGIf length_words is zero.
FS_ERR_INVALID_ADDRIf p_dest or p_src are outside of the flash memory boundaries specified in p_config.
FS_ERR_UNALIGNED_ADDRIf p_dest or p_src are not aligned to a word boundary.
FS_ERR_QUEUE_FULLIf the internal operation queue is full.
void fs_sys_event_handler ( uint32_t  sys_evt)

Function for handling system events from the SoftDevice.

If any of the modules used by the application rely on fstorage, the application should dispatch system events to fstorage using this function.

Parameters
[in]sys_evtSystem event from the SoftDevice.

Documentation feedback | Developer Zone | Subscribe | Updated