shao ziyang / mbed-dev

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   SensorTileTest

Fork of mbed-dev by mbed official

targets/TARGET_NORDIC/TARGET_NRF5/sdk/drivers_nrf/pstorage/pstorage.h@149:156823d33999, 2016-10-28 (annotated)

Committer:
<>
Date:
Fri Oct 28 11:17:30 2016 +0100
Revision:
149:156823d33999
Parent:
targets/hal/TARGET_NORDIC/TARGET_NRF5/sdk/drivers_nrf/pstorage/pstorage.h@144:ef7eb2e8f9f7 
This updates the lib to the mbed lib v128



NOTE: This release includes a restructuring of the file and directory locations and thus some

include paths in your code may need updating accordingly.

Who changed what in which revision?

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