Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of LinkNode-Test by
pstorage.h
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 In order to ensure that the SDK and application be moved to alternate persistent storage 00041 * options other than the default provided with NRF solution, an abstracted interface is provided 00042 * by the module to ensure SDK modules and application can be ported to alternate option with ease. 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. These are used to report any error during 00054 * a persistent storage access operation or any general error that may occur in the 00055 * interface. 00056 * 00057 * @details Persistent Storage Access Operation Codes used in error notification callback 00058 * registered with the interface to report any error during an persistent storage access 00059 * operation or any general error that may occur in the interface. 00060 */ 00061 #define PSTORAGE_ERROR_OP_CODE 0x01 /**< General Error Code */ 00062 #define PSTORAGE_STORE_OP_CODE 0x02 /**< Error when Store Operation was requested */ 00063 #define PSTORAGE_LOAD_OP_CODE 0x03 /**< Error when Load Operation was requested */ 00064 #define PSTORAGE_CLEAR_OP_CODE 0x04 /**< Error when Clear Operation was requested */ 00065 #define PSTORAGE_UPDATE_OP_CODE 0x05 /**< Update an already touched storage block */ 00066 00067 /**@} */ 00068 00069 /**@defgroup pstorage_data_types Persistent Memory Interface Data Types 00070 * @{ 00071 * @brief Data Types needed for interfacing with persistent memory. 00072 * 00073 * @details Data Types needed for interfacing with persistent memory. 00074 */ 00075 00076 /**@brief Persistent Storage Error Reporting Callback 00077 * 00078 * @details Persistent Storage Error Reporting Callback that is used by the interface to report 00079 * success or failure of a flash operation. Therefore, for any operations, application 00080 * can know when the procedure was complete. For store operation, since no data copy 00081 * is made, receiving a success or failure notification, indicated by the reason 00082 * parameter of callback is an indication that the resident memory could now be reused 00083 * or freed, as the case may be. 00084 * 00085 * @param[in] handle Identifies module and block for which callback is received. 00086 * @param[in] op_code Identifies the operation for which the event is notified. 00087 * @param[in] result Identifies the result of flash access operation. 00088 * NRF_SUCCESS implies, operation succeeded. 00089 * @param[in] p_data Identifies the application data pointer. In case of store operation, this 00090 * points to the resident source of application memory that application can now 00091 * free or reuse. In case of clear, this is NULL as no application pointer is 00092 * needed for this operation. 00093 * @param[in] data_len Length data application had provided for the operation. 00094 * 00095 */ 00096 typedef void (*pstorage_ntf_cb_t)(pstorage_handle_t * p_handle, 00097 uint8_t op_code, 00098 uint32_t result, 00099 uint8_t * p_data, 00100 uint32_t data_len); 00101 00102 00103 typedef struct 00104 { 00105 pstorage_ntf_cb_t cb; /**< Callback registered with the module to be notified of any error occurring in persistent memory management */ 00106 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, 00107 * 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 00108 * how it would like to access or alter memory in persistent memory. 00109 * First option is preferred when single entries that need to be updated often when having no impact on the other entries. 00110 * While second option is preferred when entries of table are not changed on individually but have common point of loading and storing 00111 * data. */ 00112 pstorage_size_t block_count; /** Number of blocks requested by the module, minimum values is 1. */ 00113 } pstorage_module_param_t; 00114 00115 /**@} */ 00116 00117 /**@defgroup pstorage_routines Persistent Storage Access Routines 00118 * @{ 00119 * @brief Functions/Interface SDK modules use to persistently store data. 00120 * 00121 * @details Interface for Application & SDK module to load/store information persistently. 00122 * Note: that while implementation of each of the persistent storage access function 00123 * depends on the system and can specific to system/solution, the signature of the 00124 * interface routines should not be altered. 00125 */ 00126 00127 /**@brief Module Initialization Routine. 00128 * 00129 * @details Initializes module. To be called once before any other APIs of the module are used. 00130 * 00131 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00132 */ 00133 uint32_t pstorage_init(void); 00134 00135 00136 /**@brief Register with persistent storage interface. 00137 * 00138 * @param[in] p_module_param Module registration param. 00139 * @param[out] p_block_id Block identifier to identify persistent memory blocks in case 00140 * registration succeeds. Application is expected to use the block ids 00141 * for subsequent operations on requested persistent memory. Maximum 00142 * registrations permitted is determined by configuration parameter 00143 * PSTORAGE_MAX_APPLICATIONS. 00144 * In case more than one memory blocks are requested, the identifier provided here is 00145 * the base identifier for the first block and to identify subsequent block, 00146 * application shall use \@ref pstorage_block_identifier_get with this base identifier 00147 * and block number. Therefore if 10 blocks of size 64 are requested and application 00148 * wishes to store memory in 6th block, it shall use 00149 * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. 00150 * This way application is only expected to remember the base block identifier. 00151 * 00152 * @note To register an area with a total size (block count * block size) larger than the 00153 * page size (usually 1024 bytes), the block size must be a divisor of the page size 00154 * (page size % block size == 0). 00155 * 00156 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00157 * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. 00158 * @retval NRF_ERROR_NULL if NULL parameter has been passed. 00159 * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. 00160 * @retval NRF_ERROR_NO_MEM in case no more registrations can be supported. 00161 */ 00162 uint32_t pstorage_register(pstorage_module_param_t * p_module_param, 00163 pstorage_handle_t * p_block_id); 00164 00165 00166 /** 00167 * @brief Function to get block id with reference to base block identifier provided at time of 00168 * registration. 00169 * 00170 * @details Function to get block id with reference to base block identifier provided at time of 00171 * registration. 00172 * In case more than one memory blocks were requested when registering, the identifier 00173 * provided here is the base identifier for the first block and to identify subsequent 00174 * block, application shall use this routine to get block identifier providing input as 00175 * base identifier and block number. Therefore if 10 blocks of size 64 are requested and 00176 * application wishes to store memory in 6th block, it shall use 00177 * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. 00178 * This way application is only expected to remember the base block identifier. 00179 * 00180 * @param[in] p_base_id Base block id received at the time of registration. 00181 * @param[in] block_num Block Number, with first block numbered zero. 00182 * @param[out] p_block_id Block identifier for the block number requested in case the API succeeds. 00183 * 00184 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00185 * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. 00186 * @retval NRF_ERROR_NULL if NULL parameter has been passed. 00187 * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. 00188 */ 00189 uint32_t pstorage_block_identifier_get(pstorage_handle_t * p_base_id, 00190 pstorage_size_t block_num, 00191 pstorage_handle_t * p_block_id); 00192 00193 00194 /**@brief Routine to persistently store data of length 'size' contained in 'p_src' address 00195 * in storage module at 'p_dest' address; Equivalent to Storage Write. 00196 * 00197 * @param[in] p_dest Destination address where data is to be stored persistently. 00198 * @param[in] p_src Source address containing data to be stored. API assumes this to be resident 00199 * memory and no intermediate copy of data is made by the API. 00200 * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. 00201 * @param[in] offset Offset in bytes to be applied when writing to the block. 00202 * For example, if within a block of 100 bytes, application wishes to 00203 * write 20 bytes at offset of 12, then this field should be set to 12. 00204 * Should be word aligned. 00205 * 00206 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00207 * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. 00208 * @retval NRF_ERROR_NULL if NULL parameter has been passed. 00209 * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. 00210 * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. 00211 * @retval NRF_ERROR_NO_MEM in case request cannot be processed. 00212 * 00213 * @warning No copy of the data is made, and hence memory provided for data source to be written 00214 * to flash cannot be freed or reused by the application until this procedure 00215 * is complete. End of this procedure is notified to the application using the 00216 * notification callback registered by the application. 00217 */ 00218 uint32_t pstorage_store(pstorage_handle_t * p_dest, 00219 uint8_t * p_src, 00220 pstorage_size_t size, 00221 pstorage_size_t offset); 00222 00223 /**@brief Routine to update persistently stored data of length 'size' contained in 'p_src' address 00224 * in storage module at 'p_dest' address. 00225 * 00226 * @param[in] p_dest Destination address where data is to be updated. 00227 * @param[in] p_src Source address containing data to be stored. API assumes this to be resident 00228 * memory and no intermediate copy of data is made by the API. 00229 * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. 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, application wishes to 00232 * write 20 bytes at offset of 12, then this field should be set to 12. 00233 * Should be word aligned. 00234 * 00235 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00236 * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. 00237 * @retval NRF_ERROR_NULL if NULL parameter has been passed. 00238 * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. 00239 * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. 00240 * @retval NRF_ERROR_NO_MEM in case request cannot be processed. 00241 * 00242 * @warning No copy of the data is made, and hence memory provided for data source to be written 00243 * to flash cannot be freed or reused by the application until this procedure 00244 * is complete. End of this procedure is notified to the application using the 00245 * notification callback registered by the application. 00246 */ 00247 uint32_t pstorage_update(pstorage_handle_t * p_dest, 00248 uint8_t * p_src, 00249 pstorage_size_t size, 00250 pstorage_size_t offset); 00251 00252 /**@brief Routine to load persistently stored data of length 'size' from 'p_src' address 00253 * to 'p_dest' address; Equivalent to Storage Read. 00254 * 00255 * @param[in] p_dest Destination address where persistently stored data is to be loaded. 00256 * @param[in] p_src Source from where data is to be loaded from persistent memory. 00257 * @param[in] size Size of data to be loaded from persistent memory expressed in bytes. 00258 * Should be word aligned. 00259 * @param[in] offset Offset in bytes to be applied when loading from the block. 00260 * For example, if within a block of 100 bytes, application wishes to 00261 * load 20 bytes from offset of 12, then this field should be set to 12. 00262 * Should be word aligned. 00263 * 00264 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00265 * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. 00266 * @retval NRF_ERROR_NULL if NULL parameter has been passed. 00267 * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. 00268 * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned. 00269 * @retval NRF_ERROR_NO_MEM in case request cannot be processed. 00270 */ 00271 uint32_t pstorage_load(uint8_t * p_dest, 00272 pstorage_handle_t * p_src, 00273 pstorage_size_t size, 00274 pstorage_size_t offset); 00275 00276 /**@brief Routine to clear data in persistent memory. 00277 * 00278 * @param[in] p_base_id Base block identifier in persistent memory that needs to cleared; 00279 * Equivalent to an Erase Operation. 00280 * 00281 * @param[in] size Size of data to be cleared from persistent memory expressed in bytes. 00282 * This parameter is to provision for clearing of certain blocks 00283 * of memory, or all memory blocks in a registered module. If the total size 00284 * of the application module is used (blocks * block size) in combination with 00285 * the identifier for the first block in the module, all blocks in the 00286 * module will be erased. 00287 * 00288 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00289 * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. 00290 * @retval NRF_ERROR_NULL if NULL parameter has been passed. 00291 * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. 00292 * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned. 00293 * @retval NRF_ERROR_NO_MEM in case request cannot be processed. 00294 * 00295 * @note Clear operations may take time. This API however, does not block until the clear 00296 * procedure is complete. Application is notified of procedure completion using 00297 * notification callback registered by the application. 'result' parameter of the 00298 * callback suggests if the procedure was successful or not. 00299 */ 00300 uint32_t pstorage_clear(pstorage_handle_t * p_base_id, pstorage_size_t size); 00301 00302 /** 00303 * @brief API to get status of number of pending operations with the module. 00304 * 00305 * @param[out] p_count Number of storage operations pending with the module, if 0, 00306 * there are no outstanding requests. 00307 * 00308 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. 00309 * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. 00310 * @retval NRF_ERROR_NULL if NULL parameter has been passed. 00311 */ 00312 uint32_t pstorage_access_status_get(uint32_t * p_count); 00313 00314 /**@} */ 00315 /**@} */ 00316 00317 #endif // PSTORAGE_H__
Generated on Tue Jul 12 2022 16:00:22 by
