nRF51 SDK - S120 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Persistent Storage Access Routines

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_countNumber of storage operations pending with the module, if 0, there are no outstanding requests.
Return values
NRF_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEis returned is API is called without module initialization.
NRF_ERROR_NULLif 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_idBase block id received at the time of registration.
[in]block_numBlock Number, with first block numbered zero.
[out]p_block_idBlock identifier for the block number requested in case the API succeeds.
Return values
NRF_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEis returned is API is called without module initialization.
NRF_ERROR_NULLif NULL parameter has been passed.
NRF_ERROR_INVALID_PARAMif 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_idBase block identifier in persistent memory that needs to cleared; Equivalent to an Erase Operation.
[in]sizeSize 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_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEis returned is API is called without module initialization.
NRF_ERROR_NULLif NULL parameter has been passed.
NRF_ERROR_INVALID_PARAMif invalid parameters are passed to the API.
NRF_ERROR_INVALID_ADDRin case data address 'p_dst' is not aligned.
NRF_ERROR_NO_MEMin 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_SUCCESSon 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_destDestination address where persistently stored data is to be loaded.
[in]p_srcSource from where data is to be loaded from persistent memory.
[in]sizeSize of data to be loaded from persistent memory expressed in bytes. Should be word aligned.
[in]offsetOffset 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_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEis returned is API is called without module initialization.
NRF_ERROR_NULLif NULL parameter has been passed.
NRF_ERROR_INVALID_PARAMif invalid parameters are passed to the API.
NRF_ERROR_INVALID_ADDRin case data address 'p_dst' is not aligned.
NRF_ERROR_NO_MEMin 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_paramModule registration param.
[out]p_block_idBlock 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.
Note
To register an area with a total size (block count * block size) larger than the page size (usually 1024 bytes), the block size must be a divisor of the page size (page size % block size == 0).
Return values
NRF_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEis returned is API is called without module initialization.
NRF_ERROR_NULLif NULL parameter has been passed.
NRF_ERROR_INVALID_PARAMif invalid parameters are passed to the API.
NRF_ERROR_NO_MEMin 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_destDestination address where data is to be stored persistently.
[in]p_srcSource 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]sizeSize of data to be stored expressed in bytes. Should be word aligned.
[in]offsetOffset 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_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEis returned is API is called without module initialization.
NRF_ERROR_NULLif NULL parameter has been passed.
NRF_ERROR_INVALID_PARAMif invalid parameters are passed to the API.
NRF_ERROR_INVALID_ADDRin case data address 'p_src' is not aligned.
NRF_ERROR_NO_MEMin 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_destDestination address where data is to be updated.
[in]p_srcSource 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]sizeSize of data to be stored expressed in bytes. Should be word aligned.
[in]offsetOffset 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_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEis returned is API is called without module initialization.
NRF_ERROR_NULLif NULL parameter has been passed.
NRF_ERROR_INVALID_PARAMif invalid parameters are passed to the API.
NRF_ERROR_INVALID_ADDRin case data address 'p_src' is not aligned.
NRF_ERROR_NO_MEMin 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.