Nordic Semiconductor / nrf51-sdk

Nordic nrf51 sdk sources. Mirrored from https://github.com/ARMmbed/nrf51-sdk.

Dependents:   nRF51822 nRF51822

source/nordic_sdk/components/drivers_nrf/pstorage/pstorage.h@24:2aea0c1c57ee, 2016-04-07 (annotated)

Committer:
vcoubard
Date:
Thu Apr 07 17:37:49 2016 +0100
Revision:
24:2aea0c1c57ee
Parent:
22:67a8d2c0bbbf
Child:
27:0fe148f1bca3
Synchronized with git rev 709d3cdb

Author: Liyou Zhou

Change version number in README

Who changed what in which revision?

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