nRF51 SDK: Persistent Storage Access Routines

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Persistent Storage Access Routines
Persistent Storage Interface

Functions/Interface SDK modules use to persistently store data. More...

## Functions

uint32_t | pstorage_init (void)
| Module Initialization Routine. More...
uint32_t | pstorage_register (pstorage_module_param_t *p_module_param, pstorage_handle_t *p_block_id)
| Register with persistent storage interface. More...
uint32_t | pstorage_block_identifier_get (pstorage_handle_t *p_base_id, pstorage_size_t block_num, pstorage_handle_t *p_block_id)
| Function to get block id with reference to base block identifier provided at time of registration. More...
uint32_t | pstorage_store (pstorage_handle_t *p_dest, uint8_t *p_src, pstorage_size_t size, pstorage_size_t offset)
| Routine to persistently store data of length 'size' contained in 'p_src' address in storage module at 'p_dest' address; Equivalent to Storage Write. More...
uint32_t | pstorage_update (pstorage_handle_t *p_dest, uint8_t *p_src, pstorage_size_t size, pstorage_size_t offset)
| Routine to update persistently stored data of length 'size' contained in 'p_src' address in storage module at 'p_dest' address. More...
uint32_t | pstorage_load (uint8_t *p_dest, pstorage_handle_t *p_src, pstorage_size_t size, pstorage_size_t offset)
| Routine to load persistently stored data of length 'size' from 'p_src' address to 'p_dest' address; Equivalent to Storage Read. More...
uint32_t | pstorage_clear (pstorage_handle_t *p_base_id, pstorage_size_t size)
| Routine to clear data in persistent memory. More...
uint32_t | pstorage_access_status_get (uint32_t *p_count)
| API to get status of number of pending operations with the module. More...

## Detailed Description

Functions/Interface SDK modules use to persistently store data.

Interface for Application & SDK module to load/store information persistently. Note: that while implementation of each of the persistent storage access function depends on the system and can specific to system/solution, the signature of the interface routines should not be altered.

## Function Documentation

uint32_t pstorage_access_status_get | ( | uint32_t * | p_count | ) |

API to get status of number of pending operations with the module.

Parameters

  [out] | p_count | Number of storage operations pending with the module, if 0, there are no outstanding requests.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.
  NRF_ERROR_INVALID_STATE | is returned is API is called without module initialization.
  NRF_ERROR_NULL | if NULL parameter has been passed.

uint32_t pstorage_block_identifier_get | ( | pstorage_handle_t * | p_base_id,
|  | pstorage_size_t | block_num,
|  | pstorage_handle_t * | p_block_id
| ) |  |

Function to get block id with reference to base block identifier provided at time of registration.

Function to get block id with reference to base block identifier provided at time of registration. In case more than one memory blocks were requested when registering, the identifier provided here is the base identifier for the first block and to identify subsequent block, application shall use this routine to get block identifier providing input as base identifier and block number. Therefore if 10 blocks of size 64 are requested and application wishes to store memory in 6th block, it shall use @ref pstorage_block_identifier_get with based id and provide a block number of 5. This way application is only expected to remember the base block identifier.

Parameters

  [in] | p_base_id | Base block id received at the time of registration.
  [in] | block_num | Block Number, with first block numbered zero.
  [out] | p_block_id | Block identifier for the block number requested in case the API succeeds.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.
  NRF_ERROR_INVALID_STATE | is returned is API is called without module initialization.
  NRF_ERROR_NULL | if NULL parameter has been passed.
  NRF_ERROR_INVALID_PARAM | if invalid parameters are passed to the API.

uint32_t pstorage_clear | ( | pstorage_handle_t * | p_base_id,
|  | pstorage_size_t | size
| ) |  |

Routine to clear data in persistent memory.

Parameters

  [in] | p_base_id | Base block identifier in persistent memory that needs to cleared; Equivalent to an Erase Operation.
  [in] | size | Size of data to be cleared from persistent memory expressed in bytes. This parameter is to provision for clearing of certain blocks of memory, or all memory blocks in a registered module. If the total size of the application module is used (blocks * block size) in combination with the identifier for the first block in the module, all blocks in the module will be erased.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.
  NRF_ERROR_INVALID_STATE | is returned is API is called without module initialization.
  NRF_ERROR_NULL | if NULL parameter has been passed.
  NRF_ERROR_INVALID_PARAM | if invalid parameters are passed to the API.
  NRF_ERROR_INVALID_ADDR | in case data address 'p_dst' is not aligned.
  NRF_ERROR_NO_MEM | in case request cannot be processed.

Note
  Clear operations may take time. This API however, does not block until the clear procedure is complete. Application is notified of procedure completion using notification callback registered by the application. 'result' parameter of the callback suggests if the procedure was successful or not.

uint32_t pstorage_init | ( | void |  | ) |

Module Initialization Routine.

Initializes module. To be called once before any other APIs of the module are used.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.

uint32_t pstorage_load | ( | uint8_t * | p_dest,
|  | pstorage_handle_t * | p_src,
|  | pstorage_size_t | size,
|  | pstorage_size_t | offset
| ) |  |

Routine to load persistently stored data of length 'size' from 'p_src' address to 'p_dest' address; Equivalent to Storage Read.

Parameters

  [in] | p_dest | Destination address where persistently stored data is to be loaded.
  [in] | p_src | Source from where data is to be loaded from persistent memory.
  [in] | size | Size of data to be loaded from persistent memory expressed in bytes. Should be word aligned.
  [in] | offset | Offset in bytes to be applied when loading from the block. For example, if within a block of 100 bytes, application wishes to load 20 bytes from offset of 12, then this field should be set to 12. Should be word aligned.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.
  NRF_ERROR_INVALID_STATE | is returned is API is called without module initialization.
  NRF_ERROR_NULL | if NULL parameter has been passed.
  NRF_ERROR_INVALID_PARAM | if invalid parameters are passed to the API.
  NRF_ERROR_INVALID_ADDR | in case data address 'p_dst' is not aligned.
  NRF_ERROR_NO_MEM | in case request cannot be processed.

uint32_t pstorage_register | ( | pstorage_module_param_t * | p_module_param,
|  | pstorage_handle_t * | p_block_id
| ) |  |

Register with persistent storage interface.

Parameters

  [in] | p_module_param | Module registration param.
  [out] | p_block_id | Block identifier to identify persistent memory blocks in case registration succeeds. Application is expected to use the block ids for subsequent operations on requested persistent memory. Maximum registrations permitted is determined by configuration parameter PSTORAGE_MAX_APPLICATIONS. In case more than one memory blocks are requested, the identifier provided here is the base identifier for the first block and to identify subsequent block, application shall use @ref pstorage_block_identifier_get with this base identifier and block number. Therefore if 10 blocks of size 64 are requested and application wishes to store memory in 6th block, it shall use @ref pstorage_block_identifier_get with based id and provide a block number of 5. This way application is only expected to remember the base block identifier.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.
  NRF_ERROR_INVALID_STATE | is returned is API is called without module initialization.
  NRF_ERROR_NULL | if NULL parameter has been passed.
  NRF_ERROR_INVALID_PARAM | if invalid parameters are passed to the API.
  NRF_ERROR_NO_MEM | in case no more registrations can be supported.

uint32_t pstorage_store | ( | pstorage_handle_t * | p_dest,
|  | uint8_t * | p_src,
|  | pstorage_size_t | size,
|  | pstorage_size_t | offset
| ) |  |

Routine to persistently store data of length 'size' contained in 'p_src' address in storage module at 'p_dest' address; Equivalent to Storage Write.

Parameters

  [in] | p_dest | Destination address where data is to be stored persistently.
  [in] | p_src | Source address containing data to be stored. API assumes this to be resident memory and no intermediate copy of data is made by the API.
  [in] | size | Size of data to be stored expressed in bytes. Should be word aligned.
  [in] | offset | Offset in bytes to be applied when writing to the block. For example, if within a block of 100 bytes, application wishes to write 20 bytes at offset of 12, then this field should be set to 12. Should be word aligned.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.
  NRF_ERROR_INVALID_STATE | is returned is API is called without module initialization.
  NRF_ERROR_NULL | if NULL parameter has been passed.
  NRF_ERROR_INVALID_PARAM | if invalid parameters are passed to the API.
  NRF_ERROR_INVALID_ADDR | in case data address 'p_src' is not aligned.
  NRF_ERROR_NO_MEM | in case request cannot be processed.

Warning
  No copy of the data is made, and hence memory provided for data source to be written to flash cannot be freed or reused by the application until this procedure is complete. End of this procedure is notified to the application using the notification callback registered by the application.

uint32_t pstorage_update | ( | pstorage_handle_t * | p_dest,
|  | uint8_t * | p_src,
|  | pstorage_size_t | size,
|  | pstorage_size_t | offset
| ) |  |

Routine to update persistently stored data of length 'size' contained in 'p_src' address in storage module at 'p_dest' address.

Parameters

  [in] | p_dest | Destination address where data is to be updated.
  [in] | p_src | Source address containing data to be stored. API assumes this to be resident memory and no intermediate copy of data is made by the API.
  [in] | size | Size of data to be stored expressed in bytes. Should be word aligned.
  [in] | offset | Offset in bytes to be applied when writing to the block. For example, if within a block of 100 bytes, application wishes to write 20 bytes at offset of 12, then this field should be set to 12. Should be word aligned.

Return values

  NRF_SUCCESS | on success, else an error code indicating reason for failure.
  NRF_ERROR_INVALID_STATE | is returned is API is called without module initialization.
  NRF_ERROR_NULL | if NULL parameter has been passed.
  NRF_ERROR_INVALID_PARAM | if invalid parameters are passed to the API.
  NRF_ERROR_INVALID_ADDR | in case data address 'p_src' is not aligned.
  NRF_ERROR_NO_MEM | in case request cannot be processed.

Warning
  No copy of the data is made, and hence memory provided for data source to be written to flash cannot be freed or reused by the application until this procedure is complete. End of this procedure is notified to the application using the notification callback registered by the application.