| User | Revision | Line number | New contents of line |
|---|
| jinu |
0:6ba9b94b8997
|
1
|
/* Copyright (c) Nordic Semiconductor ASA
|
| jinu |
0:6ba9b94b8997
|
2
|
* All rights reserved.
|
| jinu |
0:6ba9b94b8997
|
3
|
*
|
| jinu |
0:6ba9b94b8997
|
4
|
* Redistribution and use in source and binary forms, with or without modification,
|
| jinu |
0:6ba9b94b8997
|
5
|
* are permitted provided that the following conditions are met:
|
| jinu |
0:6ba9b94b8997
|
6
|
*
|
| jinu |
0:6ba9b94b8997
|
7
|
* 1. Redistributions of source code must retain the above copyright notice, this
|
| jinu |
0:6ba9b94b8997
|
8
|
* list of conditions and the following disclaimer.
|
| jinu |
0:6ba9b94b8997
|
9
|
*
|
| jinu |
0:6ba9b94b8997
|
10
|
* 2. Redistributions in binary form must reproduce the above copyright notice, this
|
| jinu |
0:6ba9b94b8997
|
11
|
* list of conditions and the following disclaimer in the documentation and/or
|
| jinu |
0:6ba9b94b8997
|
12
|
* other materials provided with the distribution.
|
| jinu |
0:6ba9b94b8997
|
13
|
*
|
| jinu |
0:6ba9b94b8997
|
14
|
* 3. Neither the name of Nordic Semiconductor ASA nor the names of other
|
| jinu |
0:6ba9b94b8997
|
15
|
* contributors to this software may be used to endorse or promote products
|
| jinu |
0:6ba9b94b8997
|
16
|
* derived from this software without specific prior written permission.
|
| jinu |
0:6ba9b94b8997
|
17
|
*
|
| jinu |
0:6ba9b94b8997
|
18
|
* 4. This software must only be used in a processor manufactured by Nordic
|
| jinu |
0:6ba9b94b8997
|
19
|
* Semiconductor ASA, or in a processor manufactured by a third party that
|
| jinu |
0:6ba9b94b8997
|
20
|
* is used in combination with a processor manufactured by Nordic Semiconductor.
|
| jinu |
0:6ba9b94b8997
|
21
|
*
|
| jinu |
0:6ba9b94b8997
|
22
|
*
|
| jinu |
0:6ba9b94b8997
|
23
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
| jinu |
0:6ba9b94b8997
|
24
|
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
| jinu |
0:6ba9b94b8997
|
25
|
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
| jinu |
0:6ba9b94b8997
|
26
|
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
| jinu |
0:6ba9b94b8997
|
27
|
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
| jinu |
0:6ba9b94b8997
|
28
|
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
| jinu |
0:6ba9b94b8997
|
29
|
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
| jinu |
0:6ba9b94b8997
|
30
|
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
| jinu |
0:6ba9b94b8997
|
31
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
| jinu |
0:6ba9b94b8997
|
32
|
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
| jinu |
0:6ba9b94b8997
|
33
|
*/
|
| jinu |
0:6ba9b94b8997
|
34
|
|
| jinu |
0:6ba9b94b8997
|
35
|
/**@file
|
| jinu |
0:6ba9b94b8997
|
36
|
*
|
| jinu |
0:6ba9b94b8997
|
37
|
* @defgroup persistent_storage Persistent Storage Interface
|
| jinu |
0:6ba9b94b8997
|
38
|
* @{
|
| jinu |
0:6ba9b94b8997
|
39
|
* @ingroup app_common
|
| jinu |
0:6ba9b94b8997
|
40
|
* @brief Abstracted flash interface.
|
| jinu |
0:6ba9b94b8997
|
41
|
*
|
| jinu |
0:6ba9b94b8997
|
42
|
* @details In order to ensure that the SDK and application be moved to alternate persistent storage
|
| jinu |
0:6ba9b94b8997
|
43
|
* options other than the default provided with NRF solution, an abstracted interface is provided
|
| jinu |
0:6ba9b94b8997
|
44
|
* by the module to ensure SDK modules and application can be ported to alternate option with ease.
|
| jinu |
0:6ba9b94b8997
|
45
|
*/
|
| jinu |
0:6ba9b94b8997
|
46
|
|
| jinu |
0:6ba9b94b8997
|
47
|
#ifndef PSTORAGE_H__
|
| jinu |
0:6ba9b94b8997
|
48
|
#define PSTORAGE_H__
|
| jinu |
0:6ba9b94b8997
|
49
|
|
| jinu |
0:6ba9b94b8997
|
50
|
#include <stdint.h>
|
| jinu |
0:6ba9b94b8997
|
51
|
/**@defgroup ps_opcode Persistent Storage Access Operation Codes
|
| jinu |
0:6ba9b94b8997
|
52
|
* @{
|
| jinu |
0:6ba9b94b8997
|
53
|
* @brief Persistent Storage Access Operation Codes. These are used to report any error during
|
| jinu |
0:6ba9b94b8997
|
54
|
* a persistent storage access operation or any general error that may occur in the
|
| jinu |
0:6ba9b94b8997
|
55
|
* interface.
|
| jinu |
0:6ba9b94b8997
|
56
|
*
|
| jinu |
0:6ba9b94b8997
|
57
|
* @details Persistent Storage Access Operation Codes used in error notification callback
|
| jinu |
0:6ba9b94b8997
|
58
|
* registered with the interface to report any error during an persistent storage access
|
| jinu |
0:6ba9b94b8997
|
59
|
* operation or any general error that may occur in the interface.
|
| jinu |
0:6ba9b94b8997
|
60
|
*/
|
| jinu |
0:6ba9b94b8997
|
61
|
#define PSTORAGE_ERROR_OP_CODE 0x01 /**< General Error Code */
|
| jinu |
0:6ba9b94b8997
|
62
|
#define PSTORAGE_STORE_OP_CODE 0x02 /**< Error when Store Operation was requested */
|
| jinu |
0:6ba9b94b8997
|
63
|
#define PSTORAGE_LOAD_OP_CODE 0x03 /**< Error when Load Operation was requested */
|
| jinu |
0:6ba9b94b8997
|
64
|
#define PSTORAGE_CLEAR_OP_CODE 0x04 /**< Error when Clear Operation was requested */
|
| jinu |
0:6ba9b94b8997
|
65
|
#define PSTORAGE_UPDATE_OP_CODE 0x05 /**< Update an already touched storage block */
|
| jinu |
0:6ba9b94b8997
|
66
|
|
| jinu |
0:6ba9b94b8997
|
67
|
/** Abstracts persistently memory block identifier. */
|
| jinu |
0:6ba9b94b8997
|
68
|
typedef uint32_t pstorage_block_t;
|
| jinu |
0:6ba9b94b8997
|
69
|
|
| jinu |
0:6ba9b94b8997
|
70
|
typedef struct
|
| jinu |
0:6ba9b94b8997
|
71
|
{
|
| jinu |
0:6ba9b94b8997
|
72
|
uint32_t module_id; /**< Module ID.*/
|
| jinu |
0:6ba9b94b8997
|
73
|
pstorage_block_t block_id; /**< Block ID.*/
|
| jinu |
0:6ba9b94b8997
|
74
|
} pstorage_handle_t;
|
| jinu |
0:6ba9b94b8997
|
75
|
|
| jinu |
0:6ba9b94b8997
|
76
|
typedef uint16_t pstorage_size_t; /** Size of length and offset fields. */
|
| jinu |
0:6ba9b94b8997
|
77
|
|
| jinu |
0:6ba9b94b8997
|
78
|
/**@} */
|
| jinu |
0:6ba9b94b8997
|
79
|
|
| jinu |
0:6ba9b94b8997
|
80
|
/**@defgroup pstorage_data_types Persistent Memory Interface Data Types
|
| jinu |
0:6ba9b94b8997
|
81
|
* @{
|
| jinu |
0:6ba9b94b8997
|
82
|
* @brief Data Types needed for interfacing with persistent memory.
|
| jinu |
0:6ba9b94b8997
|
83
|
*
|
| jinu |
0:6ba9b94b8997
|
84
|
* @details Data Types needed for interfacing with persistent memory.
|
| jinu |
0:6ba9b94b8997
|
85
|
*/
|
| jinu |
0:6ba9b94b8997
|
86
|
|
| jinu |
0:6ba9b94b8997
|
87
|
/**@brief Persistent Storage Error Reporting Callback
|
| jinu |
0:6ba9b94b8997
|
88
|
*
|
| jinu |
0:6ba9b94b8997
|
89
|
* @details Persistent Storage Error Reporting Callback that is used by the interface to report
|
| jinu |
0:6ba9b94b8997
|
90
|
* success or failure of a flash operation. Therefore, for store operation or clear
|
| jinu |
0:6ba9b94b8997
|
91
|
* operations, that take time, application can know when the procedure was complete.
|
| jinu |
0:6ba9b94b8997
|
92
|
* For store operation, since no data copy is made, receiving a success or failure
|
| jinu |
0:6ba9b94b8997
|
93
|
* notification, indicated by the reason parameter of callback is an indication that
|
| jinu |
0:6ba9b94b8997
|
94
|
* the resident memory could now be reused or freed, as the case may be.
|
| jinu |
0:6ba9b94b8997
|
95
|
* This callback is not received for load operation.
|
| jinu |
0:6ba9b94b8997
|
96
|
*
|
| jinu |
0:6ba9b94b8997
|
97
|
* @param[in] handle Identifies module and block for which callback is received.
|
| jinu |
0:6ba9b94b8997
|
98
|
* @param[in] op_code Identifies the operation for which the event is notified.
|
| jinu |
0:6ba9b94b8997
|
99
|
* @param[in] result Identifies the result of flash access operation.
|
| jinu |
0:6ba9b94b8997
|
100
|
* NRF_SUCCESS implies, operation succeeded.
|
| jinu |
0:6ba9b94b8997
|
101
|
* @param[in] p_data Identifies the application data pointer. In case of store operation, this
|
| jinu |
0:6ba9b94b8997
|
102
|
* points to the resident source of application memory that application can now
|
| jinu |
0:6ba9b94b8997
|
103
|
* free or reuse. In case of clear, this is NULL as no application pointer is
|
| jinu |
0:6ba9b94b8997
|
104
|
* needed for this operation.
|
| jinu |
0:6ba9b94b8997
|
105
|
* @param[in] data_len Length data application had provided for the operation.
|
| jinu |
0:6ba9b94b8997
|
106
|
*
|
| jinu |
0:6ba9b94b8997
|
107
|
*/
|
| jinu |
0:6ba9b94b8997
|
108
|
typedef void (*pstorage_ntf_cb_t)(pstorage_handle_t * p_handle,
|
| jinu |
0:6ba9b94b8997
|
109
|
uint8_t op_code,
|
| jinu |
0:6ba9b94b8997
|
110
|
uint32_t result,
|
| jinu |
0:6ba9b94b8997
|
111
|
uint8_t * p_data,
|
| jinu |
0:6ba9b94b8997
|
112
|
uint32_t data_len);
|
| jinu |
0:6ba9b94b8997
|
113
|
|
| jinu |
0:6ba9b94b8997
|
114
|
|
| jinu |
0:6ba9b94b8997
|
115
|
typedef struct
|
| jinu |
0:6ba9b94b8997
|
116
|
{
|
| jinu |
0:6ba9b94b8997
|
117
|
pstorage_ntf_cb_t cb; /**< Callback registered with the module to be notified of any error occurring in persistent memory management */
|
| jinu |
0:6ba9b94b8997
|
118
|
pstorage_size_t block_size; /**< Desired block size for persistent memory storage, for example, if a module has a table with 10 entries, each entry is size 64 bytes,
|
| jinu |
0:6ba9b94b8997
|
119
|
* it can request 10 blocks with block size 64 bytes. On the other hand, the module can also request one block of size 640 based on
|
| jinu |
0:6ba9b94b8997
|
120
|
* how it would like to access or alter memory in persistent memory.
|
| jinu |
0:6ba9b94b8997
|
121
|
* First option is preferred when single entries that need to be updated often when having no impact on the other entries.
|
| jinu |
0:6ba9b94b8997
|
122
|
* While second option is preferred when entries of table are not changed on individually but have common point of loading and storing
|
| jinu |
0:6ba9b94b8997
|
123
|
* data. */
|
| jinu |
0:6ba9b94b8997
|
124
|
pstorage_size_t block_count; /** Number of blocks requested by the module, minimum values is 1. */
|
| jinu |
0:6ba9b94b8997
|
125
|
} pstorage_module_param_t;
|
| jinu |
0:6ba9b94b8997
|
126
|
|
| jinu |
0:6ba9b94b8997
|
127
|
/**@} */
|
| jinu |
0:6ba9b94b8997
|
128
|
|
| jinu |
0:6ba9b94b8997
|
129
|
/**@defgroup pstorage_routines Persistent Storage Access Routines
|
| jinu |
0:6ba9b94b8997
|
130
|
* @{
|
| jinu |
0:6ba9b94b8997
|
131
|
* @brief Functions/Interface SDK modules use to persistently store data.
|
| jinu |
0:6ba9b94b8997
|
132
|
*
|
| jinu |
0:6ba9b94b8997
|
133
|
* @details Interface for Application & SDK module to load/store information persistently.
|
| jinu |
0:6ba9b94b8997
|
134
|
* Note: that while implementation of each of the persistent storage access function
|
| jinu |
0:6ba9b94b8997
|
135
|
* depends on the system and can specific to system/solution, the signature of the
|
| jinu |
0:6ba9b94b8997
|
136
|
* interface routines should not be altered.
|
| jinu |
0:6ba9b94b8997
|
137
|
*/
|
| jinu |
0:6ba9b94b8997
|
138
|
|
| jinu |
0:6ba9b94b8997
|
139
|
/**@brief Module Initialization Routine.
|
| jinu |
0:6ba9b94b8997
|
140
|
*
|
| jinu |
0:6ba9b94b8997
|
141
|
* @details Initializes module. To be called once before any other APIs of the module are used.
|
| jinu |
0:6ba9b94b8997
|
142
|
*
|
| jinu |
0:6ba9b94b8997
|
143
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
144
|
*/
|
| jinu |
0:6ba9b94b8997
|
145
|
uint32_t pstorage_init(void);
|
| jinu |
0:6ba9b94b8997
|
146
|
|
| jinu |
0:6ba9b94b8997
|
147
|
|
| jinu |
0:6ba9b94b8997
|
148
|
/**@brief Register with persistent storage interface.
|
| jinu |
0:6ba9b94b8997
|
149
|
*
|
| jinu |
0:6ba9b94b8997
|
150
|
* @param[in] p_module_param Module registration param.
|
| jinu |
0:6ba9b94b8997
|
151
|
* @param[out] p_block_id Block identifier to identify persistent memory blocks in case
|
| jinu |
0:6ba9b94b8997
|
152
|
* registration succeeds. Application is expected to use the block ids
|
| jinu |
0:6ba9b94b8997
|
153
|
* for subsequent operations on requested persistent memory. Maximum
|
| jinu |
0:6ba9b94b8997
|
154
|
* registrations permitted is determined by configuration parameter
|
| jinu |
0:6ba9b94b8997
|
155
|
* PSTORAGE_MAX_APPLICATIONS.
|
| jinu |
0:6ba9b94b8997
|
156
|
* In case more than one memory blocks are requested, the identifier provided here is
|
| jinu |
0:6ba9b94b8997
|
157
|
* the base identifier for the first block and to identify subsequent block,
|
| jinu |
0:6ba9b94b8997
|
158
|
* application shall use \@ref pstorage_block_identifier_get with this base identifier
|
| jinu |
0:6ba9b94b8997
|
159
|
* and block number. Therefore if 10 blocks of size 64 are requested and application
|
| jinu |
0:6ba9b94b8997
|
160
|
* wishes to store memory in 6th block, it shall use
|
| jinu |
0:6ba9b94b8997
|
161
|
* \@ref pstorage_block_identifier_get with based id and provide a block number of 5.
|
| jinu |
0:6ba9b94b8997
|
162
|
* This way application is only expected to remember the base block identifier.
|
| jinu |
0:6ba9b94b8997
|
163
|
*
|
| jinu |
0:6ba9b94b8997
|
164
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
165
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
166
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
167
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
168
|
* @retval NRF_ERROR_NO_MEM in case no more registrations can be supported.
|
| jinu |
0:6ba9b94b8997
|
169
|
*/
|
| jinu |
0:6ba9b94b8997
|
170
|
uint32_t pstorage_register(pstorage_module_param_t * p_module_param,
|
| jinu |
0:6ba9b94b8997
|
171
|
pstorage_handle_t * p_block_id);
|
| jinu |
0:6ba9b94b8997
|
172
|
|
| jinu |
0:6ba9b94b8997
|
173
|
|
| jinu |
0:6ba9b94b8997
|
174
|
/**
|
| jinu |
0:6ba9b94b8997
|
175
|
* @brief Function to get block id with reference to base block identifier provided at time of
|
| jinu |
0:6ba9b94b8997
|
176
|
* registration.
|
| jinu |
0:6ba9b94b8997
|
177
|
*
|
| jinu |
0:6ba9b94b8997
|
178
|
* @details Function to get block id with reference to base block identifier provided at time of
|
| jinu |
0:6ba9b94b8997
|
179
|
* registration.
|
| jinu |
0:6ba9b94b8997
|
180
|
* In case more than one memory blocks were requested when registering, the identifier
|
| jinu |
0:6ba9b94b8997
|
181
|
* provided here is the base identifier for the first block and to identify subsequent
|
| jinu |
0:6ba9b94b8997
|
182
|
* block, application shall use this routine to get block identifier providing input as
|
| jinu |
0:6ba9b94b8997
|
183
|
* base identifier and block number. Therefore if 10 blocks of size 64 are requested and
|
| jinu |
0:6ba9b94b8997
|
184
|
* application wishes to store memory in 6th block, it shall use
|
| jinu |
0:6ba9b94b8997
|
185
|
* \@ref pstorage_block_identifier_get with based id and provide a block number of 5.
|
| jinu |
0:6ba9b94b8997
|
186
|
* This way application is only expected to remember the base block identifier.
|
| jinu |
0:6ba9b94b8997
|
187
|
*
|
| jinu |
0:6ba9b94b8997
|
188
|
* @param[in] p_base_id Base block id received at the time of registration.
|
| jinu |
0:6ba9b94b8997
|
189
|
* @param[in] block_num Block Number, with first block numbered zero.
|
| jinu |
0:6ba9b94b8997
|
190
|
* @param[out] p_block_id Block identifier for the block number requested in case the API succeeds.
|
| jinu |
0:6ba9b94b8997
|
191
|
*
|
| jinu |
0:6ba9b94b8997
|
192
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
193
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
194
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
195
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
196
|
*/
|
| jinu |
0:6ba9b94b8997
|
197
|
uint32_t pstorage_block_identifier_get(pstorage_handle_t * p_base_id,
|
| jinu |
0:6ba9b94b8997
|
198
|
pstorage_size_t block_num,
|
| jinu |
0:6ba9b94b8997
|
199
|
pstorage_handle_t * p_block_id);
|
| jinu |
0:6ba9b94b8997
|
200
|
|
| jinu |
0:6ba9b94b8997
|
201
|
|
| jinu |
0:6ba9b94b8997
|
202
|
/**@brief Routine to persistently store data of length 'size' contained in 'p_src' address
|
| jinu |
0:6ba9b94b8997
|
203
|
* in storage module at 'p_dest' address; Equivalent to Storage Write.
|
| jinu |
0:6ba9b94b8997
|
204
|
*
|
| jinu |
0:6ba9b94b8997
|
205
|
* @param[in] p_dest Destination address where data is to be stored persistently.
|
| jinu |
0:6ba9b94b8997
|
206
|
* @param[in] p_src Source address containing data to be stored. API assumes this to be resident
|
| jinu |
0:6ba9b94b8997
|
207
|
* memory and no intermediate copy of data is made by the API.
|
| jinu |
0:6ba9b94b8997
|
208
|
* @param[in] size Size of data to be stored expressed in bytes. Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
209
|
* @param[in] offset Offset in bytes to be applied when writing to the block.
|
| jinu |
0:6ba9b94b8997
|
210
|
* For example, if within a block of 100 bytes, application wishes to
|
| jinu |
0:6ba9b94b8997
|
211
|
* write 20 bytes at offset of 12, then this field should be set to 12.
|
| jinu |
0:6ba9b94b8997
|
212
|
* Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
213
|
*
|
| jinu |
0:6ba9b94b8997
|
214
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
215
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
216
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
217
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
218
|
* @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned.
|
| jinu |
0:6ba9b94b8997
|
219
|
* @retval NRF_ERROR_NO_MEM in case request cannot be processed.
|
| jinu |
0:6ba9b94b8997
|
220
|
*
|
| jinu |
0:6ba9b94b8997
|
221
|
* @warning No copy of the data is made, and hence memory provided for data source to be written
|
| jinu |
0:6ba9b94b8997
|
222
|
* to flash cannot be freed or reused by the application until this procedure
|
| jinu |
0:6ba9b94b8997
|
223
|
* is complete. End of this procedure is notified to the application using the
|
| jinu |
0:6ba9b94b8997
|
224
|
* notification callback registered by the application.
|
| jinu |
0:6ba9b94b8997
|
225
|
*/
|
| jinu |
0:6ba9b94b8997
|
226
|
uint32_t pstorage_store(pstorage_handle_t * p_dest,
|
| jinu |
0:6ba9b94b8997
|
227
|
uint8_t * p_src,
|
| jinu |
0:6ba9b94b8997
|
228
|
pstorage_size_t size,
|
| jinu |
0:6ba9b94b8997
|
229
|
pstorage_size_t offset);
|
| jinu |
0:6ba9b94b8997
|
230
|
|
| jinu |
0:6ba9b94b8997
|
231
|
/**@brief Routine to update persistently stored data of length 'size' contained in 'p_src' address
|
| jinu |
0:6ba9b94b8997
|
232
|
* in storage module at 'p_dest' address.
|
| jinu |
0:6ba9b94b8997
|
233
|
*
|
| jinu |
0:6ba9b94b8997
|
234
|
* @param[in] p_dest Destination address where data is to be updated.
|
| jinu |
0:6ba9b94b8997
|
235
|
* @param[in] p_src Source address containing data to be stored. API assumes this to be resident
|
| jinu |
0:6ba9b94b8997
|
236
|
* memory and no intermediate copy of data is made by the API.
|
| jinu |
0:6ba9b94b8997
|
237
|
* @param[in] size Size of data to be stored expressed in bytes. Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
238
|
* @param[in] offset Offset in bytes to be applied when writing to the block.
|
| jinu |
0:6ba9b94b8997
|
239
|
* For example, if within a block of 100 bytes, application wishes to
|
| jinu |
0:6ba9b94b8997
|
240
|
* write 20 bytes at offset of 12, then this field should be set to 12.
|
| jinu |
0:6ba9b94b8997
|
241
|
* Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
242
|
*
|
| jinu |
0:6ba9b94b8997
|
243
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
244
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
245
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
246
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
247
|
* @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned.
|
| jinu |
0:6ba9b94b8997
|
248
|
* @retval NRF_ERROR_NO_MEM in case request cannot be processed.
|
| jinu |
0:6ba9b94b8997
|
249
|
*
|
| jinu |
0:6ba9b94b8997
|
250
|
* @warning No copy of the data is made, and hence memory provided for data source to be written
|
| jinu |
0:6ba9b94b8997
|
251
|
* to flash cannot be freed or reused by the application until this procedure
|
| jinu |
0:6ba9b94b8997
|
252
|
* is complete. End of this procedure is notified to the application using the
|
| jinu |
0:6ba9b94b8997
|
253
|
* notification callback registered by the application.
|
| jinu |
0:6ba9b94b8997
|
254
|
*/
|
| jinu |
0:6ba9b94b8997
|
255
|
uint32_t pstorage_update(pstorage_handle_t * p_dest,
|
| jinu |
0:6ba9b94b8997
|
256
|
uint8_t * p_src,
|
| jinu |
0:6ba9b94b8997
|
257
|
pstorage_size_t size,
|
| jinu |
0:6ba9b94b8997
|
258
|
pstorage_size_t offset);
|
| jinu |
0:6ba9b94b8997
|
259
|
|
| jinu |
0:6ba9b94b8997
|
260
|
/**@brief Routine to load persistently stored data of length 'size' from 'p_src' address
|
| jinu |
0:6ba9b94b8997
|
261
|
* to 'p_dest' address; Equivalent to Storage Read.
|
| jinu |
0:6ba9b94b8997
|
262
|
*
|
| jinu |
0:6ba9b94b8997
|
263
|
* @param[in] p_dest Destination address where persistently stored data is to be loaded.
|
| jinu |
0:6ba9b94b8997
|
264
|
* @param[in] p_src Source from where data is to be loaded from persistent memory.
|
| jinu |
0:6ba9b94b8997
|
265
|
* @param[in] size Size of data to be loaded from persistent memory expressed in bytes.
|
| jinu |
0:6ba9b94b8997
|
266
|
* Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
267
|
* @param[in] offset Offset in bytes to be applied when loading from the block.
|
| jinu |
0:6ba9b94b8997
|
268
|
* For example, if within a block of 100 bytes, application wishes to
|
| jinu |
0:6ba9b94b8997
|
269
|
* load 20 bytes from offset of 12, then this field should be set to 12.
|
| jinu |
0:6ba9b94b8997
|
270
|
* Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
271
|
*
|
| jinu |
0:6ba9b94b8997
|
272
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
273
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
274
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
275
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
276
|
* @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned.
|
| jinu |
0:6ba9b94b8997
|
277
|
* @retval NRF_ERROR_NO_MEM in case request cannot be processed.
|
| jinu |
0:6ba9b94b8997
|
278
|
*/
|
| jinu |
0:6ba9b94b8997
|
279
|
uint32_t pstorage_load(uint8_t * p_dest,
|
| jinu |
0:6ba9b94b8997
|
280
|
pstorage_handle_t * p_src,
|
| jinu |
0:6ba9b94b8997
|
281
|
pstorage_size_t size,
|
| jinu |
0:6ba9b94b8997
|
282
|
pstorage_size_t offset);
|
| jinu |
0:6ba9b94b8997
|
283
|
|
| jinu |
0:6ba9b94b8997
|
284
|
/**@brief Routine to clear data in persistent memory.
|
| jinu |
0:6ba9b94b8997
|
285
|
*
|
| jinu |
0:6ba9b94b8997
|
286
|
* @param[in] p_base_id Base block identifier in persistent memory that needs to cleared;
|
| jinu |
0:6ba9b94b8997
|
287
|
* Equivalent to an Erase Operation.
|
| jinu |
0:6ba9b94b8997
|
288
|
*
|
| jinu |
0:6ba9b94b8997
|
289
|
* @param[in] size Size of data to be cleared from persistent memory expressed in bytes.
|
| jinu |
0:6ba9b94b8997
|
290
|
* This parameter is to provision for clearing of certain blocks
|
| jinu |
0:6ba9b94b8997
|
291
|
* of memory, or all memory blocks in a registered module. If the total size
|
| jinu |
0:6ba9b94b8997
|
292
|
* of the application module is used (blocks * block size) in combination with
|
| jinu |
0:6ba9b94b8997
|
293
|
* the identifier for the first block in the module, all blocks in the
|
| jinu |
0:6ba9b94b8997
|
294
|
* module will be erased.
|
| jinu |
0:6ba9b94b8997
|
295
|
*
|
| jinu |
0:6ba9b94b8997
|
296
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
297
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
298
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
299
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
300
|
* @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned.
|
| jinu |
0:6ba9b94b8997
|
301
|
* @retval NRF_ERROR_NO_MEM in case request cannot be processed.
|
| jinu |
0:6ba9b94b8997
|
302
|
*
|
| jinu |
0:6ba9b94b8997
|
303
|
* @note Clear operations may take time. This API however, does not block until the clear
|
| jinu |
0:6ba9b94b8997
|
304
|
* procedure is complete. Application is notified of procedure completion using
|
| jinu |
0:6ba9b94b8997
|
305
|
* notification callback registered by the application. 'result' parameter of the
|
| jinu |
0:6ba9b94b8997
|
306
|
* callback suggests if the procedure was successful or not.
|
| jinu |
0:6ba9b94b8997
|
307
|
*/
|
| jinu |
0:6ba9b94b8997
|
308
|
uint32_t pstorage_clear(pstorage_handle_t * p_base_id, pstorage_size_t size);
|
| jinu |
0:6ba9b94b8997
|
309
|
|
| jinu |
0:6ba9b94b8997
|
310
|
/**
|
| jinu |
0:6ba9b94b8997
|
311
|
* @brief API to get status of number of pending operations with the module.
|
| jinu |
0:6ba9b94b8997
|
312
|
*
|
| jinu |
0:6ba9b94b8997
|
313
|
* @param[out] p_count Number of storage operations pending with the module, if 0,
|
| jinu |
0:6ba9b94b8997
|
314
|
* there are no outstanding requests.
|
| jinu |
0:6ba9b94b8997
|
315
|
*
|
| jinu |
0:6ba9b94b8997
|
316
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
317
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
318
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
319
|
*/
|
| jinu |
0:6ba9b94b8997
|
320
|
uint32_t pstorage_access_status_get(uint32_t * p_count);
|
| jinu |
0:6ba9b94b8997
|
321
|
|
| jinu |
0:6ba9b94b8997
|
322
|
#ifdef PSTORAGE_RAW_MODE_ENABLE
|
| jinu |
0:6ba9b94b8997
|
323
|
|
| jinu |
0:6ba9b94b8997
|
324
|
/**@brief Function for registering with persistent storage interface.
|
| jinu |
0:6ba9b94b8997
|
325
|
*
|
| jinu |
0:6ba9b94b8997
|
326
|
* @param[in] p_module_param Module registration param.
|
| jinu |
0:6ba9b94b8997
|
327
|
* @param[out] p_block_id Block identifier to identify persistent memory blocks in case
|
| jinu |
0:6ba9b94b8997
|
328
|
* registration succeeds. Application is expected to use the block ids
|
| jinu |
0:6ba9b94b8997
|
329
|
* for subsequent operations on requested persistent memory.
|
| jinu |
0:6ba9b94b8997
|
330
|
* In case more than one memory blocks are requested, the identifier provided here is
|
| jinu |
0:6ba9b94b8997
|
331
|
* the base identifier for the first block and to identify subsequent block,
|
| jinu |
0:6ba9b94b8997
|
332
|
* application shall use \@ref pstorage_block_identifier_get with this base identifier
|
| jinu |
0:6ba9b94b8997
|
333
|
* and block number. Therefore if 10 blocks of size 64 are requested and application
|
| jinu |
0:6ba9b94b8997
|
334
|
* wishes to store memory in 6th block, it shall use
|
| jinu |
0:6ba9b94b8997
|
335
|
* \@ref pstorage_block_identifier_get with based id and provide a block number of 5.
|
| jinu |
0:6ba9b94b8997
|
336
|
* This way application is only expected to remember the base block identifier.
|
| jinu |
0:6ba9b94b8997
|
337
|
*
|
| jinu |
0:6ba9b94b8997
|
338
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
339
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
340
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
341
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
342
|
* @retval NRF_ERROR_NO_MEM in case no more registrations can be supported.
|
| jinu |
0:6ba9b94b8997
|
343
|
*/
|
| jinu |
0:6ba9b94b8997
|
344
|
uint32_t pstorage_raw_register(pstorage_module_param_t * p_module_param,
|
| jinu |
0:6ba9b94b8997
|
345
|
pstorage_handle_t * p_block_id);
|
| jinu |
0:6ba9b94b8997
|
346
|
|
| jinu |
0:6ba9b94b8997
|
347
|
/**@brief Raw mode function for persistently storing data of length 'size' contained in 'p_src'
|
| jinu |
0:6ba9b94b8997
|
348
|
* address in storage module at 'p_dest' address; Equivalent to Storage Write.
|
| jinu |
0:6ba9b94b8997
|
349
|
*
|
| jinu |
0:6ba9b94b8997
|
350
|
* @param[in] p_dest Destination address where data is to be stored persistently.
|
| jinu |
0:6ba9b94b8997
|
351
|
* @param[in] p_src Source address containing data to be stored. API assumes this to be resident
|
| jinu |
0:6ba9b94b8997
|
352
|
* memory and no intermediate copy of data is made by the API.
|
| jinu |
0:6ba9b94b8997
|
353
|
* @param[in] size Size of data to be stored expressed in bytes. Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
354
|
* @param[in] offset Offset in bytes to be applied when writing to the block.
|
| jinu |
0:6ba9b94b8997
|
355
|
* For example, if within a block of 100 bytes, application wishes to
|
| jinu |
0:6ba9b94b8997
|
356
|
* write 20 bytes at offset of 12, then this field should be set to 12.
|
| jinu |
0:6ba9b94b8997
|
357
|
* Should be word aligned.
|
| jinu |
0:6ba9b94b8997
|
358
|
*
|
| jinu |
0:6ba9b94b8997
|
359
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
360
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
361
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
362
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
363
|
* @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned.
|
| jinu |
0:6ba9b94b8997
|
364
|
* @retval NRF_ERROR_NO_MEM in case request cannot be processed.
|
| jinu |
0:6ba9b94b8997
|
365
|
*
|
| jinu |
0:6ba9b94b8997
|
366
|
* @warning No copy of the data is made, and hence memory provided for data source to be written
|
| jinu |
0:6ba9b94b8997
|
367
|
* to flash cannot be freed or reused by the application until this procedure
|
| jinu |
0:6ba9b94b8997
|
368
|
* is complete. End of this procedure is notified to the application using the
|
| jinu |
0:6ba9b94b8997
|
369
|
* notification callback registered by the application.
|
| jinu |
0:6ba9b94b8997
|
370
|
*/
|
| jinu |
0:6ba9b94b8997
|
371
|
uint32_t pstorage_raw_store(pstorage_handle_t * p_dest,
|
| jinu |
0:6ba9b94b8997
|
372
|
uint8_t * p_src,
|
| jinu |
0:6ba9b94b8997
|
373
|
pstorage_size_t size,
|
| jinu |
0:6ba9b94b8997
|
374
|
pstorage_size_t offset);
|
| jinu |
0:6ba9b94b8997
|
375
|
|
| jinu |
0:6ba9b94b8997
|
376
|
/**@brief Function for clearing data in persistent memory in raw mode.
|
| jinu |
0:6ba9b94b8997
|
377
|
*
|
| jinu |
0:6ba9b94b8997
|
378
|
* @param[in] p_dest Base block identifier in persistent memory that needs to cleared;
|
| jinu |
0:6ba9b94b8997
|
379
|
* Equivalent to an Erase Operation.
|
| jinu |
0:6ba9b94b8997
|
380
|
* @param[in] size Size of data to be cleared from persistent memory expressed in bytes.
|
| jinu |
0:6ba9b94b8997
|
381
|
* This is currently unused. And a clear would mean clearing all blocks,
|
| jinu |
0:6ba9b94b8997
|
382
|
* however, this parameter is to provision for clearing of certain blocks
|
| jinu |
0:6ba9b94b8997
|
383
|
* of memory only and not all if need be.
|
| jinu |
0:6ba9b94b8997
|
384
|
*
|
| jinu |
0:6ba9b94b8997
|
385
|
* @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
|
| jinu |
0:6ba9b94b8997
|
386
|
* @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
|
| jinu |
0:6ba9b94b8997
|
387
|
* @retval NRF_ERROR_NULL if NULL parameter has been passed.
|
| jinu |
0:6ba9b94b8997
|
388
|
* @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
|
| jinu |
0:6ba9b94b8997
|
389
|
* @retval NRF_ERROR_NO_MEM in case request cannot be processed.
|
| jinu |
0:6ba9b94b8997
|
390
|
*
|
| jinu |
0:6ba9b94b8997
|
391
|
* @note Clear operations may take time. This API however, does not block until the clear
|
| jinu |
0:6ba9b94b8997
|
392
|
* procedure is complete. Application is notified of procedure completion using
|
| jinu |
0:6ba9b94b8997
|
393
|
* notification callback registered by the application. 'result' parameter of the
|
| jinu |
0:6ba9b94b8997
|
394
|
* callback suggests if the procedure was successful or not.
|
| jinu |
0:6ba9b94b8997
|
395
|
*/
|
| jinu |
0:6ba9b94b8997
|
396
|
uint32_t pstorage_raw_clear(pstorage_handle_t * p_dest, pstorage_size_t size);
|
| jinu |
0:6ba9b94b8997
|
397
|
|
| jinu |
0:6ba9b94b8997
|
398
|
#endif // PSTORAGE_RAW_MODE_ENABLE
|
| jinu |
0:6ba9b94b8997
|
399
|
|
| jinu |
0:6ba9b94b8997
|
400
|
/**@} */
|
| jinu |
0:6ba9b94b8997
|
401
|
/**@} */
|
| jinu |
0:6ba9b94b8997
|
402
|
|
| jinu |
0:6ba9b94b8997
|
403
|
#endif // PSTORAGE_H__
|
| jinu |
0:6ba9b94b8997
|
404
|
|
| jinu |
0:6ba9b94b8997
|
405
|
|