Glimworm Beacons / nRF51822

test

Fork of nRF51822 by Nordic Semiconductor

source/nordic-sdk/components/drivers_nrf/pstorage/pstorage.h@448:b71e96a821de, 2015-10-10 (annotated)

Committer:
GlimwormBeacons
Date:
Sat Oct 10 09:19:50 2015 +0000
Revision:
448:b71e96a821de
Parent:
387:b13ab9a7ddb9 
test

Who changed what in which revision?

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