| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
fstorage
SDK common libraries

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_var | A 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] | evt | The event.
  [in] | result | The result of the operation.

## Enumeration Type Documentation

enum fs_evt_id_t

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_config | fstorage configuration registered by the application.
  [in] | p_page_addr | Address of the page to erase. Must be aligned to a page boundary.
  [in] | num_pages | Number of pages to erase. May not be zero.
  [in] | p_context | User-defined context passed to the interrupt handler.

Return values

  FS_SUCCESS | If the operation was queued successfully.
  FS_ERR_NOT_INITIALIZED | If the module is not initialized.
  FS_ERR_INVALID_CFG | If `p_config` is NULL or contains invalid data.
  FS_ERR_NULL_ARG | If `p_page_addr` is NULL.
  FS_ERR_INVALID_ARG | If `num_pages` is zero.
  FS_ERR_INVALID_ADDR | If the operation would go beyond the flash memory boundaries specified in `p_config`.
  FS_ERR_UNALIGNED_ADDR | If `p_page_addr` is not aligned to a page boundary.
  FS_ERR_QUEUE_FULL | If 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_SUCCESS | If 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_count | The number of queued flash operations.

Return values

  FS_SUCCESS | If the number of queued operations was retrieved successfully.
  FS_ERR_NULL_ARG | If `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_config | fstorage configuration registered by the application.
  [in] | p_dest | The address in flash memory where to store the data.
  [in] | p_src | Pointer to the data to store in flash.
  [in] | length_words | Length of the data to store, in words.
  [in] | p_context | User-defined context passed to the interrupt handler.

Return values

  FS_SUCCESS | If the operation was queued successfully.
  FS_ERR_NOT_INITIALIZED | If the module is not initialized.
  FS_ERR_INVALID_CFG | If `p_config` is NULL or contains invalid data.
  FS_ERR_NULL_ARG | If `p_dest` or `p_src` are NULL.
  FS_ERR_INVALID_ARG | If `length_words` is zero.
  FS_ERR_INVALID_ADDR | If `p_dest` or `p_src` are outside of the flash memory boundaries specified in `p_config`.
  FS_ERR_UNALIGNED_ADDR | If `p_dest` or `p_src` are not aligned to a word boundary.
  FS_ERR_QUEUE_FULL | If 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_evt | System event from the SoftDevice.