Functions/Interface SDK modules used to persistently store data.
More...
|
uint32_t | pstorage_init (void) |
| Function for initializing the module. More...
|
|
uint32_t | pstorage_register (pstorage_module_param_t *p_module_param, pstorage_handle_t *p_block_id) |
| Function for registering 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 for getting block ID with reference to base block identifier provided at the 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) |
| Function for persistently storing data of length 'size' contained in the 'p_src' address in the 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) |
| Function for updating persistently stored data of length 'size' contained in the 'p_src' address in the 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) |
| Function for loading 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) |
| Function for clearing data in persistent memory. More...
|
|
uint32_t | pstorage_access_status_get (uint32_t *p_count) |
| Function for getting the number of pending operations with the module. More...
|
|
Functions/Interface SDK modules used to persistently store data.
Interface for the Application and SDK modules to load/store information persistently. Note: While implementation of each of the persistent storage access functions depends on the system and is specific to system/solution, the signature of the interface routines should not be altered.
uint32_t pstorage_access_status_get |
( |
uint32_t * |
p_count | ) |
|
Function for getting the 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 | Operation success. |
NRF_ERROR_INVALID_STATE | Operation failure. API is called without module initialization. |
NRF_ERROR_NULL | Operation failure. 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 for getting block ID with reference to base block identifier provided at the time of registration.
Function to get the block ID with reference to base block identifier provided at the time of registration. If more than one memory block was requested when registering, the identifier provided here is the base identifier for the first block which is used to identify subsequent blocks. The application shall use this routine to get the block identifier, providing input as base identifier and block number. Therefore, if 10 blocks of size 64 are requested and the application wishes to store memory in the 6th block, it shall use @ref pstorage_block_identifier_get with the base ID and provide a block number of 5. This way the 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 when the API succeeds. |
- Return values
-
NRF_SUCCESS | Operation success. |
NRF_ERROR_INVALID_STATE | Operation failure. API is called without module initialization. |
NRF_ERROR_NULL | Operation failure. NULL parameter has been passed. |
NRF_ERROR_INVALID_PARAM | Operation failure. Invalid parameter has been passed. |
uint32_t pstorage_clear |
( |
pstorage_handle_t * |
p_base_id, |
|
|
pstorage_size_t |
size |
|
) |
| |
Function for clearing data in persistent memory.
- Parameters
-
[in] | p_base_id | Base block identifier in persistent memory that needs to be 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. Must be multiple of block size. |
- Return values
-
NRF_SUCCESS | Operation success. |
NRF_ERROR_INVALID_STATE | Operation failure. API is called without module initialization. |
NRF_ERROR_NULL | Operation failure. NULL parameter has been passed. |
NRF_ERROR_INVALID_PARAM | Operation failure. Invalid parameter has been passed. |
NRF_ERROR_INVALID_ADDR | Operation failure. Parameter is not aligned. |
NRF_ERROR_NO_MEM | Operation failure. No storage space available. |
- Note
- Clear operations may take time. This API however, does not block until the clear procedure is complete. The application is notified of procedure completion using a notification callback registered by the application. The 'result' parameter of the callback indicates if the procedure was successful or not.
uint32_t pstorage_init |
( |
void |
| ) |
|
Function for initializing the module.
Function for initializing the module. This function is called once before any other APIs of the module are used.
- Return values
-
NRF_SUCCESS | Operation success. |
uint32_t pstorage_load |
( |
uint8_t * |
p_dest, |
|
|
pstorage_handle_t * |
p_src, |
|
|
pstorage_size_t |
size, |
|
|
pstorage_size_t |
offset |
|
) |
| |
Function for loading 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 where data is 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, the application wishes to load 20 bytes from offset of 12 bytes, then this field should be set to 12. Should be word aligned. |
- Return values
-
NRF_SUCCESS | Operation success. |
NRF_ERROR_INVALID_STATE | Operation failure. API is called without module initialization. |
NRF_ERROR_NULL | Operation failure. NULL parameter has been passed. |
NRF_ERROR_INVALID_PARAM | Operation failure. Invalid parameter has been passed. |
NRF_ERROR_INVALID_ADDR | Operation failure. Parameter is not aligned. |
NRF_ERROR_NO_MEM | Operation failure. No storage space available. |
Function for registering with persistent storage interface.
- Parameters
-
[in] | p_module_param | Module registration parameter. |
[out] | p_block_id | Block identifier to identify persistent memory blocks when registration succeeds. Application is expected to use the block IDs for subsequent operations on requested persistent memory. Maximum registrations permitted is determined by the configuration of the parameter PSTORAGE_NUM_OF_PAGES. If more than one memory block is requested, the identifier provided here is the base identifier for the first block and used to identify the subsequent block. The application uses @ref pstorage_block_identifier_get with this base identifier and block number. Therefore if 10 blocks of size 64 are requested and the application wishes to store memory in the 6th block, it shall use @ref pstorage_block_identifier_get with the base ID and provide a block number of 5. This way the application is only expected to remember the base block identifier. |
- Return values
-
NRF_SUCCESS | Operation success. |
NRF_ERROR_INVALID_STATE | Operation failure. API is called without module initialization. |
NRF_ERROR_NULL | Operation failure. NULL parameter has been passed. |
NRF_ERROR_INVALID_PARAM | Operation failure. Invalid parameter has been passed. |
NRF_ERROR_NO_MEM | Operation failure. Additional registrations can't be supported. |
uint32_t pstorage_store |
( |
pstorage_handle_t * |
p_dest, |
|
|
uint8_t * |
p_src, |
|
|
pstorage_size_t |
size, |
|
|
pstorage_size_t |
offset |
|
) |
| |
Function for persistently storing data of length 'size' contained in the 'p_src' address in the 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. Must be word aligned. |
[in] | size | Size of data to be stored expressed in bytes. Must be word aligned and size + offset must be <= block size. |
[in] | offset | Offset in bytes to be applied when writing to the block. For example, if within a block of 100 bytes, the application wishes to write 20 bytes at an offset of 12, then this field should be set to 12. Must be word aligned. |
- Return values
-
NRF_SUCCESS | Operation success. |
NRF_ERROR_INVALID_STATE | Operation failure. API is called without module initialization. |
NRF_ERROR_NULL | Operation failure. NULL parameter has been passed. |
NRF_ERROR_INVALID_PARAM | Operation failure. Invalid parameter has been passed. |
NRF_ERROR_INVALID_ADDR | Operation failure. Parameter is not aligned. |
NRF_ERROR_NO_MEM | Operation failure. No storage space available. |
- Warning
- No copy of the data is made, meaning memory provided for the data source that is to be written to flash cannot be freed or reused by the application until this procedure is complete. The application is notified when the procedure is finished 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 |
|
) |
| |
Function for updating persistently stored data of length 'size' contained in the 'p_src' address in the 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. Must be word aligned and size + offset must be <= block size. |
[in] | offset | Offset in bytes to be applied when writing to the block. For example, if within a block of 100 bytes, the application wishes to write 20 bytes at an offset of 12 bytes, then this field should be set to 12. Must be word aligned. |
- Return values
-
NRF_SUCCESS | Operation success. |
NRF_ERROR_INVALID_STATE | Operation failure. API is called without module initialization. |
NRF_ERROR_NULL | Operation failure. NULL parameter has been passed. |
NRF_ERROR_INVALID_PARAM | Operation failure. Invalid parameter has been passed. |
NRF_ERROR_INVALID_ADDR | Operation failure. Parameter is not aligned. |
NRF_ERROR_NO_MEM | Operation failure. No storage space available. |
- Warning
- No copy of the data is made, meaning memory provided for the data source that is to be written to flash cannot be freed or reused by the application until this procedure is complete. The application is notified when the procedure is finished using the notification callback registered by the application.