![](/media/cache/profiles/5f14615696649541a025d3d0f8e0447f.jpg.50x50_q85.jpg)
テスト用です。
nRF51822_wallbot/nordic/nrf-sdk/app_common/pstorage.h@0:8468a4403fea, 2016-10-11 (annotated)
- Committer:
- jksoft
- Date:
- Tue Oct 11 11:09:42 2016 +0000
- Revision:
- 0:8468a4403fea
SB??ver;
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
jksoft | 0:8468a4403fea | 1 | /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved. |
jksoft | 0:8468a4403fea | 2 | * |
jksoft | 0:8468a4403fea | 3 | * The information contained herein is property of Nordic Semiconductor ASA. |
jksoft | 0:8468a4403fea | 4 | * Terms and conditions of usage are described in detail in NORDIC |
jksoft | 0:8468a4403fea | 5 | * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. |
jksoft | 0:8468a4403fea | 6 | * |
jksoft | 0:8468a4403fea | 7 | * Licensees are granted free, non-transferable use of the information. NO |
jksoft | 0:8468a4403fea | 8 | * WARRANTY of ANY KIND is provided. This heading must NOT be removed from |
jksoft | 0:8468a4403fea | 9 | * the file. |
jksoft | 0:8468a4403fea | 10 | * |
jksoft | 0:8468a4403fea | 11 | */ |
jksoft | 0:8468a4403fea | 12 | |
jksoft | 0:8468a4403fea | 13 | /**@file |
jksoft | 0:8468a4403fea | 14 | * |
jksoft | 0:8468a4403fea | 15 | * @defgroup persistent_storage Persistent Storage Interface |
jksoft | 0:8468a4403fea | 16 | * @{ |
jksoft | 0:8468a4403fea | 17 | * @ingroup app_common |
jksoft | 0:8468a4403fea | 18 | * @brief Abstracted flash interface. |
jksoft | 0:8468a4403fea | 19 | * |
jksoft | 0:8468a4403fea | 20 | * @details In order to ensure that the SDK and application be moved to alternate persistent storage |
jksoft | 0:8468a4403fea | 21 | * options other than the default provided with NRF solution, an abstracted interface is provided |
jksoft | 0:8468a4403fea | 22 | * by the module to ensure SDK modules and application can be ported to alternate option with ease. |
jksoft | 0:8468a4403fea | 23 | */ |
jksoft | 0:8468a4403fea | 24 | |
jksoft | 0:8468a4403fea | 25 | #ifndef PSTORAGE_H__ |
jksoft | 0:8468a4403fea | 26 | #define PSTORAGE_H__ |
jksoft | 0:8468a4403fea | 27 | |
jksoft | 0:8468a4403fea | 28 | #ifdef __cplusplus |
jksoft | 0:8468a4403fea | 29 | extern "C" { |
jksoft | 0:8468a4403fea | 30 | #endif /* #ifdef __cplusplus */ |
jksoft | 0:8468a4403fea | 31 | |
jksoft | 0:8468a4403fea | 32 | #include "pstorage_platform.h" |
jksoft | 0:8468a4403fea | 33 | |
jksoft | 0:8468a4403fea | 34 | |
jksoft | 0:8468a4403fea | 35 | /**@defgroup ps_opcode Persistent Storage Access Operation Codes |
jksoft | 0:8468a4403fea | 36 | * @{ |
jksoft | 0:8468a4403fea | 37 | * @brief Persistent Storage Access Operation Codes. These are used to report any error during |
jksoft | 0:8468a4403fea | 38 | * a persistent storage access operation or any general error that may occur in the |
jksoft | 0:8468a4403fea | 39 | * interface. |
jksoft | 0:8468a4403fea | 40 | * |
jksoft | 0:8468a4403fea | 41 | * @details Persistent Storage Access Operation Codes used in error notification callback |
jksoft | 0:8468a4403fea | 42 | * registered with the interface to report any error during an persistent storage access |
jksoft | 0:8468a4403fea | 43 | * operation or any general error that may occur in the interface. |
jksoft | 0:8468a4403fea | 44 | */ |
jksoft | 0:8468a4403fea | 45 | #define PSTORAGE_ERROR_OP_CODE 0x01 /**< General Error Code */ |
jksoft | 0:8468a4403fea | 46 | #define PSTORAGE_STORE_OP_CODE 0x02 /**< Error when Store Operation was requested */ |
jksoft | 0:8468a4403fea | 47 | #define PSTORAGE_LOAD_OP_CODE 0x03 /**< Error when Load Operation was requested */ |
jksoft | 0:8468a4403fea | 48 | #define PSTORAGE_CLEAR_OP_CODE 0x04 /**< Error when Clear Operation was requested */ |
jksoft | 0:8468a4403fea | 49 | #define PSTORAGE_UPDATE_OP_CODE 0x05 /**< Update an already touched storage block */ |
jksoft | 0:8468a4403fea | 50 | |
jksoft | 0:8468a4403fea | 51 | /**@} */ |
jksoft | 0:8468a4403fea | 52 | |
jksoft | 0:8468a4403fea | 53 | /**@defgroup pstorage_data_types Persistent Memory Interface Data Types |
jksoft | 0:8468a4403fea | 54 | * @{ |
jksoft | 0:8468a4403fea | 55 | * @brief Data Types needed for interfacing with persistent memory. |
jksoft | 0:8468a4403fea | 56 | * |
jksoft | 0:8468a4403fea | 57 | * @details Data Types needed for interfacing with persistent memory. |
jksoft | 0:8468a4403fea | 58 | */ |
jksoft | 0:8468a4403fea | 59 | |
jksoft | 0:8468a4403fea | 60 | /**@brief Persistent Storage Error Reporting Callback |
jksoft | 0:8468a4403fea | 61 | * |
jksoft | 0:8468a4403fea | 62 | * @details Persistent Storage Error Reporting Callback that is used by the interface to report |
jksoft | 0:8468a4403fea | 63 | * success or failure of a flash operation. Therefore, for any operations, application |
jksoft | 0:8468a4403fea | 64 | * can know when the procedure was complete. For store operation, since no data copy |
jksoft | 0:8468a4403fea | 65 | * is made, receiving a success or failure notification, indicated by the reason |
jksoft | 0:8468a4403fea | 66 | * parameter of callback is an indication that the resident memory could now be reused |
jksoft | 0:8468a4403fea | 67 | * or freed, as the case may be. |
jksoft | 0:8468a4403fea | 68 | * |
jksoft | 0:8468a4403fea | 69 | * @param[in] handle Identifies module and block for which callback is received. |
jksoft | 0:8468a4403fea | 70 | * @param[in] op_code Identifies the operation for which the event is notified. |
jksoft | 0:8468a4403fea | 71 | * @param[in] result Identifies the result of flash access operation. |
jksoft | 0:8468a4403fea | 72 | * NRF_SUCCESS implies, operation succeeded. |
jksoft | 0:8468a4403fea | 73 | * @param[in] p_data Identifies the application data pointer. In case of store operation, this |
jksoft | 0:8468a4403fea | 74 | * points to the resident source of application memory that application can now |
jksoft | 0:8468a4403fea | 75 | * free or reuse. In case of clear, this is NULL as no application pointer is |
jksoft | 0:8468a4403fea | 76 | * needed for this operation. |
jksoft | 0:8468a4403fea | 77 | * @param[in] data_len Length data application had provided for the operation. |
jksoft | 0:8468a4403fea | 78 | * |
jksoft | 0:8468a4403fea | 79 | */ |
jksoft | 0:8468a4403fea | 80 | typedef void (*pstorage_ntf_cb_t)(pstorage_handle_t * p_handle, |
jksoft | 0:8468a4403fea | 81 | uint8_t op_code, |
jksoft | 0:8468a4403fea | 82 | uint32_t result, |
jksoft | 0:8468a4403fea | 83 | uint8_t * p_data, |
jksoft | 0:8468a4403fea | 84 | uint32_t data_len); |
jksoft | 0:8468a4403fea | 85 | |
jksoft | 0:8468a4403fea | 86 | |
jksoft | 0:8468a4403fea | 87 | typedef struct |
jksoft | 0:8468a4403fea | 88 | { |
jksoft | 0:8468a4403fea | 89 | pstorage_ntf_cb_t cb; /**< Callback registered with the module to be notified of any error occurring in persistent memory management */ |
jksoft | 0:8468a4403fea | 90 | 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, |
jksoft | 0:8468a4403fea | 91 | * 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 |
jksoft | 0:8468a4403fea | 92 | * how it would like to access or alter memory in persistent memory. |
jksoft | 0:8468a4403fea | 93 | * First option is preferred when single entries that need to be updated often when having no impact on the other entries. |
jksoft | 0:8468a4403fea | 94 | * While second option is preferred when entries of table are not changed on individually but have common point of loading and storing |
jksoft | 0:8468a4403fea | 95 | * data. */ |
jksoft | 0:8468a4403fea | 96 | pstorage_size_t block_count; /** Number of blocks requested by the module, minimum values is 1. */ |
jksoft | 0:8468a4403fea | 97 | } pstorage_module_param_t; |
jksoft | 0:8468a4403fea | 98 | |
jksoft | 0:8468a4403fea | 99 | /**@} */ |
jksoft | 0:8468a4403fea | 100 | |
jksoft | 0:8468a4403fea | 101 | /**@defgroup pstorage_routines Persistent Storage Access Routines |
jksoft | 0:8468a4403fea | 102 | * @{ |
jksoft | 0:8468a4403fea | 103 | * @brief Functions/Interface SDK modules use to persistently store data. |
jksoft | 0:8468a4403fea | 104 | * |
jksoft | 0:8468a4403fea | 105 | * @details Interface for Application & SDK module to load/store information persistently. |
jksoft | 0:8468a4403fea | 106 | * Note: that while implementation of each of the persistent storage access function |
jksoft | 0:8468a4403fea | 107 | * depends on the system and can specific to system/solution, the signature of the |
jksoft | 0:8468a4403fea | 108 | * interface routines should not be altered. |
jksoft | 0:8468a4403fea | 109 | */ |
jksoft | 0:8468a4403fea | 110 | |
jksoft | 0:8468a4403fea | 111 | /**@brief Module Initialization Routine. |
jksoft | 0:8468a4403fea | 112 | * |
jksoft | 0:8468a4403fea | 113 | * @details Initializes module. To be called once before any other APIs of the module are used. |
jksoft | 0:8468a4403fea | 114 | * |
jksoft | 0:8468a4403fea | 115 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 116 | */ |
jksoft | 0:8468a4403fea | 117 | uint32_t pstorage_init(void); |
jksoft | 0:8468a4403fea | 118 | |
jksoft | 0:8468a4403fea | 119 | |
jksoft | 0:8468a4403fea | 120 | /**@brief Register with persistent storage interface. |
jksoft | 0:8468a4403fea | 121 | * |
jksoft | 0:8468a4403fea | 122 | * @param[in] p_module_param Module registration param. |
jksoft | 0:8468a4403fea | 123 | * @param[out] p_block_id Block identifier to identify persistent memory blocks in case |
jksoft | 0:8468a4403fea | 124 | * registration succeeds. Application is expected to use the block ids |
jksoft | 0:8468a4403fea | 125 | * for subsequent operations on requested persistent memory. Maximum |
jksoft | 0:8468a4403fea | 126 | * registrations permitted is determined by configuration parameter |
jksoft | 0:8468a4403fea | 127 | * PSTORAGE_MAX_APPLICATIONS. |
jksoft | 0:8468a4403fea | 128 | * In case more than one memory blocks are requested, the identifier provided here is |
jksoft | 0:8468a4403fea | 129 | * the base identifier for the first block and to identify subsequent block, |
jksoft | 0:8468a4403fea | 130 | * application shall use \@ref pstorage_block_identifier_get with this base identifier |
jksoft | 0:8468a4403fea | 131 | * and block number. Therefore if 10 blocks of size 64 are requested and application |
jksoft | 0:8468a4403fea | 132 | * wishes to store memory in 6th block, it shall use |
jksoft | 0:8468a4403fea | 133 | * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. |
jksoft | 0:8468a4403fea | 134 | * This way application is only expected to remember the base block identifier. |
jksoft | 0:8468a4403fea | 135 | * |
jksoft | 0:8468a4403fea | 136 | * @note To register an area with a total size (block count * block size) larger than the |
jksoft | 0:8468a4403fea | 137 | * page size (usually 1024 bytes), the block size must be a divisor of the page size |
jksoft | 0:8468a4403fea | 138 | * (page size % block size == 0). |
jksoft | 0:8468a4403fea | 139 | * |
jksoft | 0:8468a4403fea | 140 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 141 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 142 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 143 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 144 | * @retval NRF_ERROR_NO_MEM in case no more registrations can be supported. |
jksoft | 0:8468a4403fea | 145 | */ |
jksoft | 0:8468a4403fea | 146 | uint32_t pstorage_register(pstorage_module_param_t * p_module_param, |
jksoft | 0:8468a4403fea | 147 | pstorage_handle_t * p_block_id); |
jksoft | 0:8468a4403fea | 148 | |
jksoft | 0:8468a4403fea | 149 | |
jksoft | 0:8468a4403fea | 150 | /** |
jksoft | 0:8468a4403fea | 151 | * @brief Function to get block id with reference to base block identifier provided at time of |
jksoft | 0:8468a4403fea | 152 | * registration. |
jksoft | 0:8468a4403fea | 153 | * |
jksoft | 0:8468a4403fea | 154 | * @details Function to get block id with reference to base block identifier provided at time of |
jksoft | 0:8468a4403fea | 155 | * registration. |
jksoft | 0:8468a4403fea | 156 | * In case more than one memory blocks were requested when registering, the identifier |
jksoft | 0:8468a4403fea | 157 | * provided here is the base identifier for the first block and to identify subsequent |
jksoft | 0:8468a4403fea | 158 | * block, application shall use this routine to get block identifier providing input as |
jksoft | 0:8468a4403fea | 159 | * base identifier and block number. Therefore if 10 blocks of size 64 are requested and |
jksoft | 0:8468a4403fea | 160 | * application wishes to store memory in 6th block, it shall use |
jksoft | 0:8468a4403fea | 161 | * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. |
jksoft | 0:8468a4403fea | 162 | * This way application is only expected to remember the base block identifier. |
jksoft | 0:8468a4403fea | 163 | * |
jksoft | 0:8468a4403fea | 164 | * @param[in] p_base_id Base block id received at the time of registration. |
jksoft | 0:8468a4403fea | 165 | * @param[in] block_num Block Number, with first block numbered zero. |
jksoft | 0:8468a4403fea | 166 | * @param[out] p_block_id Block identifier for the block number requested in case the API succeeds. |
jksoft | 0:8468a4403fea | 167 | * |
jksoft | 0:8468a4403fea | 168 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 169 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 170 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 171 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 172 | */ |
jksoft | 0:8468a4403fea | 173 | uint32_t pstorage_block_identifier_get(pstorage_handle_t * p_base_id, |
jksoft | 0:8468a4403fea | 174 | pstorage_size_t block_num, |
jksoft | 0:8468a4403fea | 175 | pstorage_handle_t * p_block_id); |
jksoft | 0:8468a4403fea | 176 | |
jksoft | 0:8468a4403fea | 177 | |
jksoft | 0:8468a4403fea | 178 | /**@brief Routine to persistently store data of length 'size' contained in 'p_src' address |
jksoft | 0:8468a4403fea | 179 | * in storage module at 'p_dest' address; Equivalent to Storage Write. |
jksoft | 0:8468a4403fea | 180 | * |
jksoft | 0:8468a4403fea | 181 | * @param[in] p_dest Destination address where data is to be stored persistently. |
jksoft | 0:8468a4403fea | 182 | * @param[in] p_src Source address containing data to be stored. API assumes this to be resident |
jksoft | 0:8468a4403fea | 183 | * memory and no intermediate copy of data is made by the API. |
jksoft | 0:8468a4403fea | 184 | * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. |
jksoft | 0:8468a4403fea | 185 | * @param[in] offset Offset in bytes to be applied when writing to the block. |
jksoft | 0:8468a4403fea | 186 | * For example, if within a block of 100 bytes, application wishes to |
jksoft | 0:8468a4403fea | 187 | * write 20 bytes at offset of 12, then this field should be set to 12. |
jksoft | 0:8468a4403fea | 188 | * Should be word aligned. |
jksoft | 0:8468a4403fea | 189 | * |
jksoft | 0:8468a4403fea | 190 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 191 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 192 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 193 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 194 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. |
jksoft | 0:8468a4403fea | 195 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
jksoft | 0:8468a4403fea | 196 | * |
jksoft | 0:8468a4403fea | 197 | * @warning No copy of the data is made, and hence memory provided for data source to be written |
jksoft | 0:8468a4403fea | 198 | * to flash cannot be freed or reused by the application until this procedure |
jksoft | 0:8468a4403fea | 199 | * is complete. End of this procedure is notified to the application using the |
jksoft | 0:8468a4403fea | 200 | * notification callback registered by the application. |
jksoft | 0:8468a4403fea | 201 | */ |
jksoft | 0:8468a4403fea | 202 | uint32_t pstorage_store(pstorage_handle_t * p_dest, |
jksoft | 0:8468a4403fea | 203 | uint8_t * p_src, |
jksoft | 0:8468a4403fea | 204 | pstorage_size_t size, |
jksoft | 0:8468a4403fea | 205 | pstorage_size_t offset); |
jksoft | 0:8468a4403fea | 206 | |
jksoft | 0:8468a4403fea | 207 | /**@brief Routine to update persistently stored data of length 'size' contained in 'p_src' address |
jksoft | 0:8468a4403fea | 208 | * in storage module at 'p_dest' address. |
jksoft | 0:8468a4403fea | 209 | * |
jksoft | 0:8468a4403fea | 210 | * @param[in] p_dest Destination address where data is to be updated. |
jksoft | 0:8468a4403fea | 211 | * @param[in] p_src Source address containing data to be stored. API assumes this to be resident |
jksoft | 0:8468a4403fea | 212 | * memory and no intermediate copy of data is made by the API. |
jksoft | 0:8468a4403fea | 213 | * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. |
jksoft | 0:8468a4403fea | 214 | * @param[in] offset Offset in bytes to be applied when writing to the block. |
jksoft | 0:8468a4403fea | 215 | * For example, if within a block of 100 bytes, application wishes to |
jksoft | 0:8468a4403fea | 216 | * write 20 bytes at offset of 12, then this field should be set to 12. |
jksoft | 0:8468a4403fea | 217 | * Should be word aligned. |
jksoft | 0:8468a4403fea | 218 | * |
jksoft | 0:8468a4403fea | 219 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 220 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 221 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 222 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 223 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. |
jksoft | 0:8468a4403fea | 224 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
jksoft | 0:8468a4403fea | 225 | * |
jksoft | 0:8468a4403fea | 226 | * @warning No copy of the data is made, and hence memory provided for data source to be written |
jksoft | 0:8468a4403fea | 227 | * to flash cannot be freed or reused by the application until this procedure |
jksoft | 0:8468a4403fea | 228 | * is complete. End of this procedure is notified to the application using the |
jksoft | 0:8468a4403fea | 229 | * notification callback registered by the application. |
jksoft | 0:8468a4403fea | 230 | */ |
jksoft | 0:8468a4403fea | 231 | uint32_t pstorage_update(pstorage_handle_t * p_dest, |
jksoft | 0:8468a4403fea | 232 | uint8_t * p_src, |
jksoft | 0:8468a4403fea | 233 | pstorage_size_t size, |
jksoft | 0:8468a4403fea | 234 | pstorage_size_t offset); |
jksoft | 0:8468a4403fea | 235 | |
jksoft | 0:8468a4403fea | 236 | /**@brief Routine to load persistently stored data of length 'size' from 'p_src' address |
jksoft | 0:8468a4403fea | 237 | * to 'p_dest' address; Equivalent to Storage Read. |
jksoft | 0:8468a4403fea | 238 | * |
jksoft | 0:8468a4403fea | 239 | * @param[in] p_dest Destination address where persistently stored data is to be loaded. |
jksoft | 0:8468a4403fea | 240 | * @param[in] p_src Source from where data is to be loaded from persistent memory. |
jksoft | 0:8468a4403fea | 241 | * @param[in] size Size of data to be loaded from persistent memory expressed in bytes. |
jksoft | 0:8468a4403fea | 242 | * Should be word aligned. |
jksoft | 0:8468a4403fea | 243 | * @param[in] offset Offset in bytes to be applied when loading from the block. |
jksoft | 0:8468a4403fea | 244 | * For example, if within a block of 100 bytes, application wishes to |
jksoft | 0:8468a4403fea | 245 | * load 20 bytes from offset of 12, then this field should be set to 12. |
jksoft | 0:8468a4403fea | 246 | * Should be word aligned. |
jksoft | 0:8468a4403fea | 247 | * |
jksoft | 0:8468a4403fea | 248 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 249 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 250 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 251 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 252 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned. |
jksoft | 0:8468a4403fea | 253 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
jksoft | 0:8468a4403fea | 254 | */ |
jksoft | 0:8468a4403fea | 255 | uint32_t pstorage_load(uint8_t * p_dest, |
jksoft | 0:8468a4403fea | 256 | pstorage_handle_t * p_src, |
jksoft | 0:8468a4403fea | 257 | pstorage_size_t size, |
jksoft | 0:8468a4403fea | 258 | pstorage_size_t offset); |
jksoft | 0:8468a4403fea | 259 | |
jksoft | 0:8468a4403fea | 260 | /**@brief Routine to clear data in persistent memory. |
jksoft | 0:8468a4403fea | 261 | * |
jksoft | 0:8468a4403fea | 262 | * @param[in] p_base_id Base block identifier in persistent memory that needs to cleared; |
jksoft | 0:8468a4403fea | 263 | * Equivalent to an Erase Operation. |
jksoft | 0:8468a4403fea | 264 | * |
jksoft | 0:8468a4403fea | 265 | * @param[in] size Size of data to be cleared from persistent memory expressed in bytes. |
jksoft | 0:8468a4403fea | 266 | * This parameter is to provision for clearing of certain blocks |
jksoft | 0:8468a4403fea | 267 | * of memory, or all memory blocks in a registered module. If the total size |
jksoft | 0:8468a4403fea | 268 | * of the application module is used (blocks * block size) in combination with |
jksoft | 0:8468a4403fea | 269 | * the identifier for the first block in the module, all blocks in the |
jksoft | 0:8468a4403fea | 270 | * module will be erased. |
jksoft | 0:8468a4403fea | 271 | * |
jksoft | 0:8468a4403fea | 272 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 273 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 274 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 275 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 276 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned. |
jksoft | 0:8468a4403fea | 277 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
jksoft | 0:8468a4403fea | 278 | * |
jksoft | 0:8468a4403fea | 279 | * @note Clear operations may take time. This API however, does not block until the clear |
jksoft | 0:8468a4403fea | 280 | * procedure is complete. Application is notified of procedure completion using |
jksoft | 0:8468a4403fea | 281 | * notification callback registered by the application. 'result' parameter of the |
jksoft | 0:8468a4403fea | 282 | * callback suggests if the procedure was successful or not. |
jksoft | 0:8468a4403fea | 283 | */ |
jksoft | 0:8468a4403fea | 284 | uint32_t pstorage_clear(pstorage_handle_t * p_base_id, pstorage_size_t size); |
jksoft | 0:8468a4403fea | 285 | |
jksoft | 0:8468a4403fea | 286 | /** |
jksoft | 0:8468a4403fea | 287 | * @brief API to get status of number of pending operations with the module. |
jksoft | 0:8468a4403fea | 288 | * |
jksoft | 0:8468a4403fea | 289 | * @param[out] p_count Number of storage operations pending with the module, if 0, |
jksoft | 0:8468a4403fea | 290 | * there are no outstanding requests. |
jksoft | 0:8468a4403fea | 291 | * |
jksoft | 0:8468a4403fea | 292 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 293 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 294 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 295 | */ |
jksoft | 0:8468a4403fea | 296 | uint32_t pstorage_access_status_get(uint32_t * p_count); |
jksoft | 0:8468a4403fea | 297 | |
jksoft | 0:8468a4403fea | 298 | #ifdef PSTORAGE_RAW_MODE_ENABLE |
jksoft | 0:8468a4403fea | 299 | |
jksoft | 0:8468a4403fea | 300 | /**@brief Function for registering with persistent storage interface. |
jksoft | 0:8468a4403fea | 301 | * |
jksoft | 0:8468a4403fea | 302 | * @param[in] p_module_param Module registration param. |
jksoft | 0:8468a4403fea | 303 | * @param[out] p_block_id Block identifier to identify persistent memory blocks in case |
jksoft | 0:8468a4403fea | 304 | * registration succeeds. Application is expected to use the block ids |
jksoft | 0:8468a4403fea | 305 | * for subsequent operations on requested persistent memory. |
jksoft | 0:8468a4403fea | 306 | * In case more than one memory blocks are requested, the identifier provided here is |
jksoft | 0:8468a4403fea | 307 | * the base identifier for the first block and to identify subsequent block, |
jksoft | 0:8468a4403fea | 308 | * application shall use \@ref pstorage_block_identifier_get with this base identifier |
jksoft | 0:8468a4403fea | 309 | * and block number. Therefore if 10 blocks of size 64 are requested and application |
jksoft | 0:8468a4403fea | 310 | * wishes to store memory in 6th block, it shall use |
jksoft | 0:8468a4403fea | 311 | * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. |
jksoft | 0:8468a4403fea | 312 | * This way application is only expected to remember the base block identifier. |
jksoft | 0:8468a4403fea | 313 | * |
jksoft | 0:8468a4403fea | 314 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 315 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 316 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 317 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 318 | * @retval NRF_ERROR_NO_MEM in case no more registrations can be supported. |
jksoft | 0:8468a4403fea | 319 | */ |
jksoft | 0:8468a4403fea | 320 | uint32_t pstorage_raw_register(pstorage_module_param_t * p_module_param, |
jksoft | 0:8468a4403fea | 321 | pstorage_handle_t * p_block_id); |
jksoft | 0:8468a4403fea | 322 | |
jksoft | 0:8468a4403fea | 323 | /**@brief Raw mode function for persistently storing data of length 'size' contained in 'p_src' |
jksoft | 0:8468a4403fea | 324 | * address in storage module at 'p_dest' address; Equivalent to Storage Write. |
jksoft | 0:8468a4403fea | 325 | * |
jksoft | 0:8468a4403fea | 326 | * @param[in] p_dest Destination address where data is to be stored persistently. |
jksoft | 0:8468a4403fea | 327 | * @param[in] p_src Source address containing data to be stored. API assumes this to be resident |
jksoft | 0:8468a4403fea | 328 | * memory and no intermediate copy of data is made by the API. |
jksoft | 0:8468a4403fea | 329 | * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. |
jksoft | 0:8468a4403fea | 330 | * @param[in] offset Offset in bytes to be applied when writing to the block. |
jksoft | 0:8468a4403fea | 331 | * For example, if within a block of 100 bytes, application wishes to |
jksoft | 0:8468a4403fea | 332 | * write 20 bytes at offset of 12, then this field should be set to 12. |
jksoft | 0:8468a4403fea | 333 | * Should be word aligned. |
jksoft | 0:8468a4403fea | 334 | * |
jksoft | 0:8468a4403fea | 335 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 336 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 337 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 338 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 339 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. |
jksoft | 0:8468a4403fea | 340 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
jksoft | 0:8468a4403fea | 341 | * |
jksoft | 0:8468a4403fea | 342 | * @warning No copy of the data is made, and hence memory provided for data source to be written |
jksoft | 0:8468a4403fea | 343 | * to flash cannot be freed or reused by the application until this procedure |
jksoft | 0:8468a4403fea | 344 | * is complete. End of this procedure is notified to the application using the |
jksoft | 0:8468a4403fea | 345 | * notification callback registered by the application. |
jksoft | 0:8468a4403fea | 346 | */ |
jksoft | 0:8468a4403fea | 347 | uint32_t pstorage_raw_store(pstorage_handle_t * p_dest, |
jksoft | 0:8468a4403fea | 348 | uint8_t * p_src, |
jksoft | 0:8468a4403fea | 349 | pstorage_size_t size, |
jksoft | 0:8468a4403fea | 350 | pstorage_size_t offset); |
jksoft | 0:8468a4403fea | 351 | |
jksoft | 0:8468a4403fea | 352 | /**@brief Function for clearing data in persistent memory in raw mode. |
jksoft | 0:8468a4403fea | 353 | * |
jksoft | 0:8468a4403fea | 354 | * @param[in] p_dest Base block identifier in persistent memory that needs to cleared; |
jksoft | 0:8468a4403fea | 355 | * Equivalent to an Erase Operation. |
jksoft | 0:8468a4403fea | 356 | * @param[in] size Size of data to be cleared from persistent memory expressed in bytes. |
jksoft | 0:8468a4403fea | 357 | * This is currently unused. And a clear would mean clearing all blocks, |
jksoft | 0:8468a4403fea | 358 | * however, this parameter is to provision for clearing of certain blocks |
jksoft | 0:8468a4403fea | 359 | * of memory only and not all if need be. |
jksoft | 0:8468a4403fea | 360 | * |
jksoft | 0:8468a4403fea | 361 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
jksoft | 0:8468a4403fea | 362 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
jksoft | 0:8468a4403fea | 363 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
jksoft | 0:8468a4403fea | 364 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
jksoft | 0:8468a4403fea | 365 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
jksoft | 0:8468a4403fea | 366 | * |
jksoft | 0:8468a4403fea | 367 | * @note Clear operations may take time. This API however, does not block until the clear |
jksoft | 0:8468a4403fea | 368 | * procedure is complete. Application is notified of procedure completion using |
jksoft | 0:8468a4403fea | 369 | * notification callback registered by the application. 'result' parameter of the |
jksoft | 0:8468a4403fea | 370 | * callback suggests if the procedure was successful or not. |
jksoft | 0:8468a4403fea | 371 | */ |
jksoft | 0:8468a4403fea | 372 | uint32_t pstorage_raw_clear(pstorage_handle_t * p_dest, pstorage_size_t size); |
jksoft | 0:8468a4403fea | 373 | |
jksoft | 0:8468a4403fea | 374 | #endif // PSTORAGE_RAW_MODE_ENABLE |
jksoft | 0:8468a4403fea | 375 | |
jksoft | 0:8468a4403fea | 376 | #ifdef __cplusplus |
jksoft | 0:8468a4403fea | 377 | } |
jksoft | 0:8468a4403fea | 378 | #endif /* #ifdef __cplusplus */ |
jksoft | 0:8468a4403fea | 379 | |
jksoft | 0:8468a4403fea | 380 | /**@} */ |
jksoft | 0:8468a4403fea | 381 | /**@} */ |
jksoft | 0:8468a4403fea | 382 | |
jksoft | 0:8468a4403fea | 383 | #endif // PSTORAGE_H__ |
jksoft | 0:8468a4403fea | 384 |