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