Nordic Semiconductor
Nordic nrf51 sdk sources. Mirrored from https://github.com/ARMmbed/nrf51-sdk.
Embed:
(wiki syntax)
Show/hide line numbers
pstorage.h
Go to the documentation of this file.
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 /**@file 00034 * 00035 * @defgroup persistent_storage Persistent Storage Interface 00036 * @{ 00037 * @ingroup app_common 00038 * @brief Abstracted flash interface. 00039 * 00040 * @details An abstracted interface is provided by the module to easily port the application and 00041 * SDK modules to an alternate option. This ensures that the SDK and application are moved 00042 * to alternate persistent storage instead of the one provided by default. 00043 */ 00044 00045 #ifndef PSTORAGE_H__ 00046 #define PSTORAGE_H__ 00047 00048 #include "pstorage_platform.h" 00049 00050 00051 /**@defgroup ps_opcode Persistent Storage Access Operation Codes 00052 * @{ 00053 * @brief Persistent Storage Access Operation Codes. 00054 * 00055 * @details Persistent Storage Access Operation Codes are used by Persistent storage operation 00056 * completion callback @ref pstorage_ntf_cb_t to identify the operation type requested by 00057 * the application. 00058 */ 00059 #define PSTORAGE_STORE_OP_CODE 0x01 /**< Store Operation type. */ 00060 #define PSTORAGE_LOAD_OP_CODE 0x02 /**< Load Operation type. */ 00061 #define PSTORAGE_CLEAR_OP_CODE 0x03 /**< Clear Operation type. */ 00062 #define PSTORAGE_UPDATE_OP_CODE 0x04 /**< Update Operation type. */ 00063 00064 /**@} */ 00065 00066 /**@defgroup pstorage_data_types Persistent Memory Interface Data Types 00067 * @{ 00068 * @brief Data Types needed for interfacing with persistent memory. 00069 * 00070 * @details Data Types needed for interfacing with persistent memory. 00071 */ 00072 00073 /**@brief Persistent storage operation completion callback function type. 00074 * 00075 * @details The persistent storage operation completion callback is used by the interface to report 00076 * success or failure of a flash operation. Since data is not copied for a store operation, 00077 * a callback is an indication that the resident memory can now be reused or freed. 00078 * 00079 * @param[in] handle Identifies the module and block for the callback that is received. 00080 * @param[in] op_code Identifies the operation for the event that is notified. 00081 * @param[in] result Identifies the result of a flash access operation. NRF_SUCCESS implies 00082 * operation succeeded. 00083 * 00084 * @note Unmanaged (abnormal behaviour) error codes from the SoftDevice flash 00085 * access API are forwarded as is and are expected to be handled by the 00086 * application. For details refer to the implementation file and corresponding 00087 * SoftDevice flash API documentation. 00088 * 00089 * @param[in] p_data Identifies the application data pointer. For a store operation, this points 00090 * to the resident source of application memory that the application can now 00091 * free or reuse. When there is a clear operation, this is NULL since no 00092 * application pointer is needed for this operation. 00093 * @param[in] data_len Length data the application provided for the operation. 00094 */ 00095 typedef void (*pstorage_ntf_cb_t)(pstorage_handle_t * p_handle, 00096 uint8_t op_code, 00097 uint32_t result, 00098 uint8_t * p_data, 00099 uint32_t data_len); 00100 00101 /**@brief Struct containing module registration context. */ 00102 typedef struct 00103 { 00104 pstorage_ntf_cb_t cb; /**< Persistent storage operation completion callback function @ref pstorage_ntf_cb_t. */ 00105 pstorage_size_t block_size; /**< Desired block size for persistent memory storage. For example, if a module has a table with 10 entries, and each entry is 64 bytes in size, 00106 * it can request 10 blocks with a block size of 64 bytes. The module can also request one block that is 640 bytes depending 00107 * on how it would like to access or alter the memory in persistent memory. 00108 * The first option is preferred when it is a single entry that needs to be updated often and doesn't impact the other entries. 00109 * The second option is preferred when table entries are not changed individually but have a common point of loading and storing 00110 * data. */ 00111 pstorage_size_t block_count; /** Number of blocks requested by the module; minimum values is 1. */ 00112 } pstorage_module_param_t; 00113 00114 /**@} */ 00115 00116 /**@defgroup pstorage_routines Persistent Storage Access Routines 00117 * @{ 00118 * @brief Functions/Interface SDK modules used to persistently store data. 00119 * 00120 * @details Interface for the Application and SDK modules to load/store information persistently. 00121 * Note: While implementation of each of the persistent storage access functions 00122 * depends on the system and is specific to system/solution, the signature of the 00123 * interface routines should not be altered. 00124 */ 00125 00126 /**@brief Function for initializing the module. 00127 * 00128 * @details Function for initializing the module. This function is called once before any other APIs 00129 * of the module are used. 00130 * 00131 * @retval NRF_SUCCESS Operation success. 00132 */ 00133 uint32_t pstorage_init(void); 00134 00135 /**@brief Function for registering with persistent storage interface. 00136 * 00137 * @param[in] p_module_param Module registration parameter. 00138 * @param[out] p_block_id Block identifier to identify persistent memory blocks when 00139 * registration succeeds. Application is expected to use the block IDs 00140 * for subsequent operations on requested persistent memory. Maximum 00141 * registrations permitted is determined by the configuration of the 00142 * parameter PSTORAGE_NUM_OF_PAGES. If more than one memory block is 00143 * requested, the identifier provided here is the base identifier for the 00144 * first block and used to identify the subsequent block. The application 00145 * uses \@ref pstorage_block_identifier_get with this base identifier and 00146 * block number. Therefore if 10 blocks of size 64 are requested and the 00147 * application wishes to store memory in the 6th block, it shall use 00148 * \@ref pstorage_block_identifier_get with the base ID and provide a 00149 * block number of 5. This way the application is only expected to 00150 * remember the base block identifier. 00151 * 00152 * @retval NRF_SUCCESS Operation success. 00153 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00154 * initialization. 00155 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00156 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00157 * @retval NRF_ERROR_NO_MEM Operation failure. Additional registrations can't be 00158 * supported. 00159 */ 00160 uint32_t pstorage_register(pstorage_module_param_t * p_module_param, 00161 pstorage_handle_t * p_block_id); 00162 00163 /**@brief Function for getting block ID with reference to base block identifier provided at the time 00164 * of registration. 00165 * 00166 * @details Function to get the block ID with reference to base block identifier provided at the 00167 * time of registration. 00168 * If more than one memory block was requested when registering, the identifier provided 00169 * here is the base identifier for the first block which is used to identify subsequent 00170 * blocks. The application shall use this routine to get the block identifier, providing 00171 * input as base identifier and block number. Therefore, if 10 blocks of size 64 are 00172 * requested and the application wishes to store memory in the 6th block, it shall use 00173 * \@ref pstorage_block_identifier_get with the base ID and provide a block number of 5. 00174 * This way the application is only expected to remember the base block identifier. 00175 * 00176 * @param[in] p_base_id Base block ID received at the time of registration. 00177 * @param[in] block_num Block Number, with first block numbered zero. 00178 * @param[out] p_block_id Block identifier for the block number requested when the API succeeds. 00179 * 00180 * @retval NRF_SUCCESS Operation success. 00181 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00182 * initialization. 00183 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00184 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00185 */ 00186 uint32_t pstorage_block_identifier_get(pstorage_handle_t * p_base_id, 00187 pstorage_size_t block_num, 00188 pstorage_handle_t * p_block_id); 00189 00190 /**@brief Function for persistently storing data of length 'size' contained in the 'p_src' address 00191 * in the storage module at 'p_dest' address. Equivalent to Storage Write. 00192 * 00193 * @param[in] p_dest Destination address where data is to be stored persistently. 00194 * @param[in] p_src Source address containing data to be stored. API assumes this to be resident 00195 * memory and no intermediate copy of data is made by the API. Must be word 00196 * aligned. 00197 * @param[in] size Size of data to be stored expressed in bytes. Must be word aligned and size + 00198 * offset must be <= block size. 00199 * @param[in] offset Offset in bytes to be applied when writing to the block. 00200 * For example, if within a block of 100 bytes, the application wishes to 00201 * write 20 bytes at an offset of 12, then this field should be set to 12. 00202 * Must be word aligned. 00203 * 00204 * @retval NRF_SUCCESS Operation success. 00205 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00206 * initialization. 00207 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00208 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00209 * @retval NRF_ERROR_INVALID_ADDR Operation failure. Parameter is not aligned. 00210 * @retval NRF_ERROR_NO_MEM Operation failure. No storage space available. 00211 * 00212 * @warning No copy of the data is made, meaning memory provided for the data source that is to 00213 * be written to flash cannot be freed or reused by the application until this procedure 00214 * is complete. The application is notified when the procedure is finished using the 00215 * notification callback registered by the application. 00216 */ 00217 uint32_t pstorage_store(pstorage_handle_t * p_dest, 00218 uint8_t * p_src, 00219 pstorage_size_t size, 00220 pstorage_size_t offset); 00221 00222 /**@brief Function for updating persistently stored data of length 'size' contained in the 'p_src' 00223 * address in the storage module at 'p_dest' address. 00224 * 00225 * @param[in] p_dest Destination address where data is to be updated. 00226 * @param[in] p_src Source address containing data to be stored. API assumes this to be resident 00227 * memory and no intermediate copy of data is made by the API. 00228 * @param[in] size Size of data to be stored expressed in bytes. Must be word aligned and size + 00229 * offset must be <= block size. 00230 * @param[in] offset Offset in bytes to be applied when writing to the block. 00231 * For example, if within a block of 100 bytes, the application wishes to 00232 * write 20 bytes at an offset of 12 bytes, then this field should be set to 12. 00233 * Must be word aligned. 00234 * 00235 * @retval NRF_SUCCESS Operation success. 00236 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00237 * initialization. 00238 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00239 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00240 * @retval NRF_ERROR_INVALID_ADDR Operation failure. Parameter is not aligned. 00241 * @retval NRF_ERROR_NO_MEM Operation failure. No storage space available. 00242 * 00243 * @warning No copy of the data is made, meaning memory provided for the data source that is to 00244 * be written to flash cannot be freed or reused by the application until this procedure 00245 * is complete. The application is notified when the procedure is finished using the 00246 * notification callback registered by the application. 00247 */ 00248 uint32_t pstorage_update(pstorage_handle_t * p_dest, 00249 uint8_t * p_src, 00250 pstorage_size_t size, 00251 pstorage_size_t offset); 00252 00253 /**@brief Function for loading persistently stored data of length 'size' from 'p_src' address 00254 * to 'p_dest' address. Equivalent to Storage Read. 00255 * 00256 * @param[in] p_dest Destination address where persistently stored data is to be loaded. 00257 * @param[in] p_src Source where data is loaded from persistent memory. 00258 * @param[in] size Size of data to be loaded from persistent memory expressed in bytes. 00259 * Should be word aligned. 00260 * @param[in] offset Offset in bytes, to be applied when loading from the block. 00261 * For example, if within a block of 100 bytes, the application wishes to 00262 * load 20 bytes from offset of 12 bytes, then this field should be set to 12. 00263 * Should be word aligned. 00264 * 00265 * @retval NRF_SUCCESS Operation success. 00266 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00267 * initialization. 00268 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00269 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00270 * @retval NRF_ERROR_INVALID_ADDR Operation failure. Parameter is not aligned. 00271 * @retval NRF_ERROR_NO_MEM Operation failure. No storage space available. 00272 */ 00273 uint32_t pstorage_load(uint8_t * p_dest, 00274 pstorage_handle_t * p_src, 00275 pstorage_size_t size, 00276 pstorage_size_t offset); 00277 00278 /**@brief Function for clearing data in persistent memory. 00279 * 00280 * @param[in] p_base_id Base block identifier in persistent memory that needs to be cleared; 00281 * equivalent to an Erase Operation. 00282 * @param[in] size Size of data to be cleared from persistent memory expressed in bytes. 00283 * This parameter is to provision for clearing of certain blocks 00284 * of memory, or all memory blocks in a registered module. If the total size 00285 * of the application module is used (blocks * block size) in combination with 00286 * the identifier for the first block in the module, all blocks in the 00287 * module will be erased. Must be multiple of block size. 00288 * 00289 * @retval NRF_SUCCESS Operation success. 00290 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00291 * initialization. 00292 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00293 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00294 * @retval NRF_ERROR_INVALID_ADDR Operation failure. Parameter is not aligned. 00295 * @retval NRF_ERROR_NO_MEM Operation failure. No storage space available. 00296 * 00297 * @note Clear operations may take time. This API however, does not block until the clear 00298 * procedure is complete. The application is notified of procedure completion using 00299 * a notification callback registered by the application. The 'result' parameter of the 00300 * callback indicates if the procedure was successful or not. 00301 */ 00302 uint32_t pstorage_clear(pstorage_handle_t * p_base_id, pstorage_size_t size); 00303 00304 /**@brief Function for getting the number of pending operations with the module. 00305 * 00306 * @param[out] p_count Number of storage operations pending with the module. If 0, there are no 00307 * outstanding requests. 00308 * 00309 * @retval NRF_SUCCESS Operation success. 00310 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00311 * initialization. 00312 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00313 */ 00314 uint32_t pstorage_access_status_get(uint32_t * p_count); 00315 00316 #ifdef PSTORAGE_RAW_MODE_ENABLE 00317 00318 /**@brief Function for registering with the persistent storage interface. 00319 * 00320 * @param[in] p_module_param Module registration parameter. 00321 * @param[out] p_block_id Block identifier used to identify persistent memory blocks upon 00322 * successful registration. The application is expected to use the block 00323 * IDs for subsequent operations on requested persistent memory. When 00324 * more than one memory block is requested, this identifier is the base 00325 * identifier for the first block and used to identify subsequent blocks. 00326 * The application shall use \@ref pstorage_block_identifier_get with 00327 * this base identifier and block number. Therefore if 10 blocks of size 00328 * 64 are requested and the application wishes to store memory in the 6th 00329 * block, it shall use \@ref pstorage_block_identifier_get with the base 00330 * ID and provide a block number of 5. Therefore, the application is only 00331 * expected to remember the base block identifier. 00332 * 00333 * @retval NRF_SUCCESS Operation success. 00334 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00335 * initialization. 00336 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00337 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00338 * @retval NRF_ERROR_NO_MEM Operation failure. No storage space available. 00339 */ 00340 uint32_t pstorage_raw_register(pstorage_module_param_t * p_module_param, 00341 pstorage_handle_t * p_block_id); 00342 00343 /**@brief Function for persistently storing data of length 'size' contained in 'p_src' address in 00344 * storage module at 'p_dest' address. Equivalent to Storage Write. 00345 * 00346 * @param[in] p_dest Destination address where data is to be stored persistently. 00347 * @param[in] p_src Source address containing data to be stored. The API assumes this is resident 00348 * memory and no intermediate copy of data is made by the API. Must be word 00349 * aligned. 00350 * @param[in] size Size of data to be stored expressed in bytes. Must be word aligned. 00351 * @param[in] offset Offset in bytes to be applied when writing to the block. 00352 * For example, if within a block of 100 bytes, the application wishes to 00353 * write 20 bytes at an offset of 12 bytes, this field should be set to 12. 00354 * Must be word aligned. 00355 * 00356 * @retval NRF_SUCCESS Operation success. 00357 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00358 * initialization. 00359 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00360 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00361 * @retval NRF_ERROR_INVALID_ADDR Operation failure. Parameter is not aligned. 00362 * @retval NRF_ERROR_NO_MEM Operation failure. No storage space available. 00363 * 00364 * @warning No copy of the data is made, meaning memory provided for data source that is to be 00365 * written to flash cannot be freed or reused by the application until this procedure 00366 * is complete. The application is notified when the procedure is finished using the 00367 * notification callback registered by the application. 00368 */ 00369 uint32_t pstorage_raw_store(pstorage_handle_t * p_dest, 00370 uint8_t * p_src, 00371 pstorage_size_t size, 00372 pstorage_size_t offset); 00373 00374 /**@brief Function for clearing data in persistent memory in raw mode. 00375 * 00376 * @param[in] p_dest Base block identifier in persistent memory that needs to be cleared. 00377 * Equivalent to an Erase Operation. 00378 * @param[in] size Size of data to be cleared from persistent memory expressed in bytes. 00379 * Not used. 00380 * 00381 * @retval NRF_SUCCESS Operation success. 00382 * @retval NRF_ERROR_INVALID_STATE Operation failure. API is called without module 00383 * initialization. 00384 * @retval NRF_ERROR_NULL Operation failure. NULL parameter has been passed. 00385 * @retval NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed. 00386 * @retval NRF_ERROR_NO_MEM Operation failure. No storage space available. 00387 * 00388 * @note Clear operations may take time. This API, however, does not block until the clear 00389 * procedure is complete. The application is notified of procedure completion using 00390 * a notification callback registered by the application. The 'result' parameter of the 00391 * callback indicates if the procedure was successful or not. 00392 */ 00393 uint32_t pstorage_raw_clear(pstorage_handle_t * p_dest, pstorage_size_t size); 00394 00395 #endif // PSTORAGE_RAW_MODE_ENABLE 00396 00397 /**@} */ 00398 /**@} */ 00399 00400 #endif // PSTORAGE_H__ 00401
Generated on Tue Jul 12 2022 15:05:59 by
1.7.2