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_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.

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_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.