test
Fork of nRF51822 by
nordic-sdk/components/drivers_nrf/pstorage/pstorage.h@371:8f7d2137727a, 2015-07-06 (annotated)
- Committer:
- rgrover1
- Date:
- Mon Jul 06 10:13:27 2015 +0100
- Revision:
- 371:8f7d2137727a
- Parent:
- 370:295f76db798e
Synchronized with git rev 2716309c
Author: Rohit Grover
Release 0.4.0
=============
This is a major release which introduces the GATT Client functionality. It
aligns with release 0.4.0 of BLE_API.
Enhancements
~~~~~~~~~~~~
* Introduce GattClient. This includes functionality for service-discovery,
connections, and attribute-reads and writes. You'll find a demo program for
LEDBlinker on the mbed.org Bluetooth team page to use the new APIs. Some of
the GATT client functionality hasn't been implemented yet, but the APIs have
been added.
* We've added an implementation for the abstract base class for
SecurityManager. All security related APIs have been moved into that.
* There has been a major cleanup of APIs under BLE. APIs have now been
categorized as belonging to Gap, GattServer, GattClient, or SecurityManager.
There are accessors to get references for Gap, GattServer, GattClient, and
SecurityManager. A former call to ble.setAddress(...) is now expected to be
achieved with ble.gap().setAddress(...).
* We've cleaned up our APIs, and this has resulted in dropping some APIs like
BLE::reset().
* We've also dropped GattServer::initializeGattDatabase(). THis was added at
some point to support controllers where a commit point was needed to
indicate when the application had finished constructing the GATT database.
This API would get called internally before Gap::startAdvertising(). We now
expect the underlying port to do the equivalent of initializeGattDatabase()
implicitly upon Gap::startAdvertising().
* We've added a version of Gap::disconnect() which takes a connection handle.
The previous API (which did not take a connection handle) has been
deprecated; it will still work for situations where there's only a single
active connection. We hold on to that API to allow existing code to migrate
to the new API.
Bugfixes
~~~~~~~~
* None.
Who changed what in which revision?
User | Revision | Line number | New 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); |
rgrover1 | 371:8f7d2137727a | 138 | |
rgrover1 | 371:8f7d2137727a | 139 | |
rgrover1 | 371:8f7d2137727a | 140 | /**@brief Register with persistent storage interface. |
rgrover1 | 371:8f7d2137727a | 141 | * |
rgrover1 | 371:8f7d2137727a | 142 | * @param[in] p_module_param Module registration param. |
rgrover1 | 371:8f7d2137727a | 143 | * @param[out] p_block_id Block identifier to identify persistent memory blocks in case |
rgrover1 | 371:8f7d2137727a | 144 | * registration succeeds. Application is expected to use the block ids |
rgrover1 | 371:8f7d2137727a | 145 | * for subsequent operations on requested persistent memory. Maximum |
rgrover1 | 371:8f7d2137727a | 146 | * registrations permitted is determined by configuration parameter |
rgrover1 | 371:8f7d2137727a | 147 | * PSTORAGE_MAX_APPLICATIONS. |
rgrover1 | 371:8f7d2137727a | 148 | * In case more than one memory blocks are requested, the identifier provided here is |
rgrover1 | 371:8f7d2137727a | 149 | * the base identifier for the first block and to identify subsequent block, |
rgrover1 | 371:8f7d2137727a | 150 | * application shall use \@ref pstorage_block_identifier_get with this base identifier |
rgrover1 | 371:8f7d2137727a | 151 | * and block number. Therefore if 10 blocks of size 64 are requested and application |
rgrover1 | 371:8f7d2137727a | 152 | * wishes to store memory in 6th block, it shall use |
rgrover1 | 371:8f7d2137727a | 153 | * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. |
rgrover1 | 371:8f7d2137727a | 154 | * This way application is only expected to remember the base block identifier. |
rgrover1 | 371:8f7d2137727a | 155 | * |
rgrover1 | 371:8f7d2137727a | 156 | * @note To register an area with a total size (block count * block size) larger than the |
rgrover1 | 371:8f7d2137727a | 157 | * page size (usually 1024 bytes), the block size must be a divisor of the page size |
rgrover1 | 371:8f7d2137727a | 158 | * (page size % block size == 0). |
rgrover1 | 371:8f7d2137727a | 159 | * |
rgrover1 | 371:8f7d2137727a | 160 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 161 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 162 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 163 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 164 | * @retval NRF_ERROR_NO_MEM in case no more registrations can be supported. |
rgrover1 | 371:8f7d2137727a | 165 | */ |
rgrover1 | 371:8f7d2137727a | 166 | uint32_t pstorage_register(pstorage_module_param_t * p_module_param, |
rgrover1 | 371:8f7d2137727a | 167 | pstorage_handle_t * p_block_id); |
rgrover1 | 371:8f7d2137727a | 168 | |
rgrover1 | 371:8f7d2137727a | 169 | |
rgrover1 | 371:8f7d2137727a | 170 | /** |
rgrover1 | 371:8f7d2137727a | 171 | * @brief Function to get block id with reference to base block identifier provided at time of |
rgrover1 | 371:8f7d2137727a | 172 | * registration. |
rgrover1 | 371:8f7d2137727a | 173 | * |
rgrover1 | 371:8f7d2137727a | 174 | * @details Function to get block id with reference to base block identifier provided at time of |
rgrover1 | 371:8f7d2137727a | 175 | * registration. |
rgrover1 | 371:8f7d2137727a | 176 | * In case more than one memory blocks were requested when registering, the identifier |
rgrover1 | 371:8f7d2137727a | 177 | * provided here is the base identifier for the first block and to identify subsequent |
rgrover1 | 371:8f7d2137727a | 178 | * block, application shall use this routine to get block identifier providing input as |
rgrover1 | 371:8f7d2137727a | 179 | * base identifier and block number. Therefore if 10 blocks of size 64 are requested and |
rgrover1 | 371:8f7d2137727a | 180 | * application wishes to store memory in 6th block, it shall use |
rgrover1 | 371:8f7d2137727a | 181 | * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. |
rgrover1 | 371:8f7d2137727a | 182 | * This way application is only expected to remember the base block identifier. |
rgrover1 | 371:8f7d2137727a | 183 | * |
rgrover1 | 371:8f7d2137727a | 184 | * @param[in] p_base_id Base block id received at the time of registration. |
rgrover1 | 371:8f7d2137727a | 185 | * @param[in] block_num Block Number, with first block numbered zero. |
rgrover1 | 371:8f7d2137727a | 186 | * @param[out] p_block_id Block identifier for the block number requested in case the API succeeds. |
rgrover1 | 371:8f7d2137727a | 187 | * |
rgrover1 | 371:8f7d2137727a | 188 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 189 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 190 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 191 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 192 | */ |
rgrover1 | 371:8f7d2137727a | 193 | uint32_t pstorage_block_identifier_get(pstorage_handle_t * p_base_id, |
rgrover1 | 371:8f7d2137727a | 194 | pstorage_size_t block_num, |
rgrover1 | 371:8f7d2137727a | 195 | pstorage_handle_t * p_block_id); |
rgrover1 | 371:8f7d2137727a | 196 | |
rgrover1 | 371:8f7d2137727a | 197 | |
rgrover1 | 371:8f7d2137727a | 198 | /**@brief Routine to persistently store data of length 'size' contained in 'p_src' address |
rgrover1 | 371:8f7d2137727a | 199 | * in storage module at 'p_dest' address; Equivalent to Storage Write. |
rgrover1 | 371:8f7d2137727a | 200 | * |
rgrover1 | 371:8f7d2137727a | 201 | * @param[in] p_dest Destination address where data is to be stored persistently. |
rgrover1 | 371:8f7d2137727a | 202 | * @param[in] p_src Source address containing data to be stored. API assumes this to be resident |
rgrover1 | 371:8f7d2137727a | 203 | * memory and no intermediate copy of data is made by the API. |
rgrover1 | 371:8f7d2137727a | 204 | * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 205 | * @param[in] offset Offset in bytes to be applied when writing to the block. |
rgrover1 | 371:8f7d2137727a | 206 | * For example, if within a block of 100 bytes, application wishes to |
rgrover1 | 371:8f7d2137727a | 207 | * write 20 bytes at offset of 12, then this field should be set to 12. |
rgrover1 | 371:8f7d2137727a | 208 | * Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 209 | * |
rgrover1 | 371:8f7d2137727a | 210 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 211 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 212 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 213 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 214 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. |
rgrover1 | 371:8f7d2137727a | 215 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
rgrover1 | 371:8f7d2137727a | 216 | * |
rgrover1 | 371:8f7d2137727a | 217 | * @warning No copy of the data is made, and hence memory provided for data source to be written |
rgrover1 | 371:8f7d2137727a | 218 | * to flash cannot be freed or reused by the application until this procedure |
rgrover1 | 371:8f7d2137727a | 219 | * is complete. End of this procedure is notified to the application using the |
rgrover1 | 371:8f7d2137727a | 220 | * notification callback registered by the application. |
rgrover1 | 371:8f7d2137727a | 221 | */ |
rgrover1 | 371:8f7d2137727a | 222 | uint32_t pstorage_store(pstorage_handle_t * p_dest, |
rgrover1 | 371:8f7d2137727a | 223 | uint8_t * p_src, |
rgrover1 | 371:8f7d2137727a | 224 | pstorage_size_t size, |
rgrover1 | 371:8f7d2137727a | 225 | pstorage_size_t offset); |
rgrover1 | 371:8f7d2137727a | 226 | |
rgrover1 | 371:8f7d2137727a | 227 | /**@brief Routine to update persistently stored data of length 'size' contained in 'p_src' address |
rgrover1 | 371:8f7d2137727a | 228 | * in storage module at 'p_dest' address. |
rgrover1 | 371:8f7d2137727a | 229 | * |
rgrover1 | 371:8f7d2137727a | 230 | * @param[in] p_dest Destination address where data is to be updated. |
rgrover1 | 371:8f7d2137727a | 231 | * @param[in] p_src Source address containing data to be stored. API assumes this to be resident |
rgrover1 | 371:8f7d2137727a | 232 | * memory and no intermediate copy of data is made by the API. |
rgrover1 | 371:8f7d2137727a | 233 | * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 234 | * @param[in] offset Offset in bytes to be applied when writing to the block. |
rgrover1 | 371:8f7d2137727a | 235 | * For example, if within a block of 100 bytes, application wishes to |
rgrover1 | 371:8f7d2137727a | 236 | * write 20 bytes at offset of 12, then this field should be set to 12. |
rgrover1 | 371:8f7d2137727a | 237 | * Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 238 | * |
rgrover1 | 371:8f7d2137727a | 239 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 240 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 241 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 242 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 243 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. |
rgrover1 | 371:8f7d2137727a | 244 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
rgrover1 | 371:8f7d2137727a | 245 | * |
rgrover1 | 371:8f7d2137727a | 246 | * @warning No copy of the data is made, and hence memory provided for data source to be written |
rgrover1 | 371:8f7d2137727a | 247 | * to flash cannot be freed or reused by the application until this procedure |
rgrover1 | 371:8f7d2137727a | 248 | * is complete. End of this procedure is notified to the application using the |
rgrover1 | 371:8f7d2137727a | 249 | * notification callback registered by the application. |
rgrover1 | 371:8f7d2137727a | 250 | */ |
rgrover1 | 371:8f7d2137727a | 251 | uint32_t pstorage_update(pstorage_handle_t * p_dest, |
rgrover1 | 371:8f7d2137727a | 252 | uint8_t * p_src, |
rgrover1 | 371:8f7d2137727a | 253 | pstorage_size_t size, |
rgrover1 | 371:8f7d2137727a | 254 | pstorage_size_t offset); |
rgrover1 | 371:8f7d2137727a | 255 | |
rgrover1 | 371:8f7d2137727a | 256 | /**@brief Routine to load persistently stored data of length 'size' from 'p_src' address |
rgrover1 | 371:8f7d2137727a | 257 | * to 'p_dest' address; Equivalent to Storage Read. |
rgrover1 | 371:8f7d2137727a | 258 | * |
rgrover1 | 371:8f7d2137727a | 259 | * @param[in] p_dest Destination address where persistently stored data is to be loaded. |
rgrover1 | 371:8f7d2137727a | 260 | * @param[in] p_src Source from where data is to be loaded from persistent memory. |
rgrover1 | 371:8f7d2137727a | 261 | * @param[in] size Size of data to be loaded from persistent memory expressed in bytes. |
rgrover1 | 371:8f7d2137727a | 262 | * Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 263 | * @param[in] offset Offset in bytes to be applied when loading from the block. |
rgrover1 | 371:8f7d2137727a | 264 | * For example, if within a block of 100 bytes, application wishes to |
rgrover1 | 371:8f7d2137727a | 265 | * load 20 bytes from offset of 12, then this field should be set to 12. |
rgrover1 | 371:8f7d2137727a | 266 | * Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 267 | * |
rgrover1 | 371:8f7d2137727a | 268 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 269 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 270 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 271 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 272 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned. |
rgrover1 | 371:8f7d2137727a | 273 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
rgrover1 | 371:8f7d2137727a | 274 | */ |
rgrover1 | 371:8f7d2137727a | 275 | uint32_t pstorage_load(uint8_t * p_dest, |
rgrover1 | 371:8f7d2137727a | 276 | pstorage_handle_t * p_src, |
rgrover1 | 371:8f7d2137727a | 277 | pstorage_size_t size, |
rgrover1 | 371:8f7d2137727a | 278 | pstorage_size_t offset); |
rgrover1 | 371:8f7d2137727a | 279 | |
rgrover1 | 371:8f7d2137727a | 280 | /**@brief Routine to clear data in persistent memory. |
rgrover1 | 371:8f7d2137727a | 281 | * |
rgrover1 | 371:8f7d2137727a | 282 | * @param[in] p_base_id Base block identifier in persistent memory that needs to cleared; |
rgrover1 | 371:8f7d2137727a | 283 | * Equivalent to an Erase Operation. |
rgrover1 | 371:8f7d2137727a | 284 | * |
rgrover1 | 371:8f7d2137727a | 285 | * @param[in] size Size of data to be cleared from persistent memory expressed in bytes. |
rgrover1 | 371:8f7d2137727a | 286 | * This parameter is to provision for clearing of certain blocks |
rgrover1 | 371:8f7d2137727a | 287 | * of memory, or all memory blocks in a registered module. If the total size |
rgrover1 | 371:8f7d2137727a | 288 | * of the application module is used (blocks * block size) in combination with |
rgrover1 | 371:8f7d2137727a | 289 | * the identifier for the first block in the module, all blocks in the |
rgrover1 | 371:8f7d2137727a | 290 | * module will be erased. |
rgrover1 | 371:8f7d2137727a | 291 | * |
rgrover1 | 371:8f7d2137727a | 292 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 293 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 294 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 295 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 296 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned. |
rgrover1 | 371:8f7d2137727a | 297 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
rgrover1 | 371:8f7d2137727a | 298 | * |
rgrover1 | 371:8f7d2137727a | 299 | * @note Clear operations may take time. This API however, does not block until the clear |
rgrover1 | 371:8f7d2137727a | 300 | * procedure is complete. Application is notified of procedure completion using |
rgrover1 | 371:8f7d2137727a | 301 | * notification callback registered by the application. 'result' parameter of the |
rgrover1 | 371:8f7d2137727a | 302 | * callback suggests if the procedure was successful or not. |
rgrover1 | 371:8f7d2137727a | 303 | */ |
rgrover1 | 371:8f7d2137727a | 304 | uint32_t pstorage_clear(pstorage_handle_t * p_base_id, pstorage_size_t size); |
rgrover1 | 371:8f7d2137727a | 305 | |
rgrover1 | 371:8f7d2137727a | 306 | /** |
rgrover1 | 371:8f7d2137727a | 307 | * @brief API to get status of number of pending operations with the module. |
rgrover1 | 371:8f7d2137727a | 308 | * |
rgrover1 | 371:8f7d2137727a | 309 | * @param[out] p_count Number of storage operations pending with the module, if 0, |
rgrover1 | 371:8f7d2137727a | 310 | * there are no outstanding requests. |
rgrover1 | 371:8f7d2137727a | 311 | * |
rgrover1 | 371:8f7d2137727a | 312 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 313 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 314 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 315 | */ |
rgrover1 | 371:8f7d2137727a | 316 | uint32_t pstorage_access_status_get(uint32_t * p_count); |
rgrover1 | 371:8f7d2137727a | 317 | |
rgrover1 | 371:8f7d2137727a | 318 | #ifdef PSTORAGE_RAW_MODE_ENABLE |
rgrover1 | 371:8f7d2137727a | 319 | |
rgrover1 | 371:8f7d2137727a | 320 | /**@brief Function for registering with persistent storage interface. |
rgrover1 | 371:8f7d2137727a | 321 | * |
rgrover1 | 371:8f7d2137727a | 322 | * @param[in] p_module_param Module registration param. |
rgrover1 | 371:8f7d2137727a | 323 | * @param[out] p_block_id Block identifier to identify persistent memory blocks in case |
rgrover1 | 371:8f7d2137727a | 324 | * registration succeeds. Application is expected to use the block ids |
rgrover1 | 371:8f7d2137727a | 325 | * for subsequent operations on requested persistent memory. |
rgrover1 | 371:8f7d2137727a | 326 | * In case more than one memory blocks are requested, the identifier provided here is |
rgrover1 | 371:8f7d2137727a | 327 | * the base identifier for the first block and to identify subsequent block, |
rgrover1 | 371:8f7d2137727a | 328 | * application shall use \@ref pstorage_block_identifier_get with this base identifier |
rgrover1 | 371:8f7d2137727a | 329 | * and block number. Therefore if 10 blocks of size 64 are requested and application |
rgrover1 | 371:8f7d2137727a | 330 | * wishes to store memory in 6th block, it shall use |
rgrover1 | 371:8f7d2137727a | 331 | * \@ref pstorage_block_identifier_get with based id and provide a block number of 5. |
rgrover1 | 371:8f7d2137727a | 332 | * This way application is only expected to remember the base block identifier. |
rgrover1 | 371:8f7d2137727a | 333 | * |
rgrover1 | 371:8f7d2137727a | 334 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 335 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 336 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 337 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 338 | * @retval NRF_ERROR_NO_MEM in case no more registrations can be supported. |
rgrover1 | 371:8f7d2137727a | 339 | */ |
rgrover1 | 371:8f7d2137727a | 340 | uint32_t pstorage_raw_register(pstorage_module_param_t * p_module_param, |
rgrover1 | 371:8f7d2137727a | 341 | pstorage_handle_t * p_block_id); |
rgrover1 | 371:8f7d2137727a | 342 | |
rgrover1 | 371:8f7d2137727a | 343 | /**@brief Raw mode function for persistently storing data of length 'size' contained in 'p_src' |
rgrover1 | 371:8f7d2137727a | 344 | * address in storage module at 'p_dest' address; Equivalent to Storage Write. |
rgrover1 | 371:8f7d2137727a | 345 | * |
rgrover1 | 371:8f7d2137727a | 346 | * @param[in] p_dest Destination address where data is to be stored persistently. |
rgrover1 | 371:8f7d2137727a | 347 | * @param[in] p_src Source address containing data to be stored. API assumes this to be resident |
rgrover1 | 371:8f7d2137727a | 348 | * memory and no intermediate copy of data is made by the API. |
rgrover1 | 371:8f7d2137727a | 349 | * @param[in] size Size of data to be stored expressed in bytes. Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 350 | * @param[in] offset Offset in bytes to be applied when writing to the block. |
rgrover1 | 371:8f7d2137727a | 351 | * For example, if within a block of 100 bytes, application wishes to |
rgrover1 | 371:8f7d2137727a | 352 | * write 20 bytes at offset of 12, then this field should be set to 12. |
rgrover1 | 371:8f7d2137727a | 353 | * Should be word aligned. |
rgrover1 | 371:8f7d2137727a | 354 | * |
rgrover1 | 371:8f7d2137727a | 355 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 356 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 357 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 358 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 359 | * @retval NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned. |
rgrover1 | 371:8f7d2137727a | 360 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
rgrover1 | 371:8f7d2137727a | 361 | * |
rgrover1 | 371:8f7d2137727a | 362 | * @warning No copy of the data is made, and hence memory provided for data source to be written |
rgrover1 | 371:8f7d2137727a | 363 | * to flash cannot be freed or reused by the application until this procedure |
rgrover1 | 371:8f7d2137727a | 364 | * is complete. End of this procedure is notified to the application using the |
rgrover1 | 371:8f7d2137727a | 365 | * notification callback registered by the application. |
rgrover1 | 371:8f7d2137727a | 366 | */ |
rgrover1 | 371:8f7d2137727a | 367 | uint32_t pstorage_raw_store(pstorage_handle_t * p_dest, |
rgrover1 | 371:8f7d2137727a | 368 | uint8_t * p_src, |
rgrover1 | 371:8f7d2137727a | 369 | pstorage_size_t size, |
rgrover1 | 371:8f7d2137727a | 370 | pstorage_size_t offset); |
rgrover1 | 371:8f7d2137727a | 371 | |
rgrover1 | 371:8f7d2137727a | 372 | /**@brief Function for clearing data in persistent memory in raw mode. |
rgrover1 | 371:8f7d2137727a | 373 | * |
rgrover1 | 371:8f7d2137727a | 374 | * @param[in] p_dest Base block identifier in persistent memory that needs to cleared; |
rgrover1 | 371:8f7d2137727a | 375 | * Equivalent to an Erase Operation. |
rgrover1 | 371:8f7d2137727a | 376 | * @param[in] size Size of data to be cleared from persistent memory expressed in bytes. |
rgrover1 | 371:8f7d2137727a | 377 | * This is currently unused. And a clear would mean clearing all blocks, |
rgrover1 | 371:8f7d2137727a | 378 | * however, this parameter is to provision for clearing of certain blocks |
rgrover1 | 371:8f7d2137727a | 379 | * of memory only and not all if need be. |
rgrover1 | 371:8f7d2137727a | 380 | * |
rgrover1 | 371:8f7d2137727a | 381 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
rgrover1 | 371:8f7d2137727a | 382 | * @retval NRF_ERROR_INVALID_STATE is returned is API is called without module initialization. |
rgrover1 | 371:8f7d2137727a | 383 | * @retval NRF_ERROR_NULL if NULL parameter has been passed. |
rgrover1 | 371:8f7d2137727a | 384 | * @retval NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API. |
rgrover1 | 371:8f7d2137727a | 385 | * @retval NRF_ERROR_NO_MEM in case request cannot be processed. |
rgrover1 | 371:8f7d2137727a | 386 | * |
rgrover1 | 371:8f7d2137727a | 387 | * @note Clear operations may take time. This API however, does not block until the clear |
rgrover1 | 371:8f7d2137727a | 388 | * procedure is complete. Application is notified of procedure completion using |
rgrover1 | 371:8f7d2137727a | 389 | * notification callback registered by the application. 'result' parameter of the |
rgrover1 | 371:8f7d2137727a | 390 | * callback suggests if the procedure was successful or not. |
rgrover1 | 371:8f7d2137727a | 391 | */ |
rgrover1 | 371:8f7d2137727a | 392 | uint32_t pstorage_raw_clear(pstorage_handle_t * p_dest, pstorage_size_t size); |
rgrover1 | 371:8f7d2137727a | 393 | |
rgrover1 | 371:8f7d2137727a | 394 | #endif // PSTORAGE_RAW_MODE_ENABLE |
rgrover1 | 371:8f7d2137727a | 395 | |
rgrover1 | 371:8f7d2137727a | 396 | /**@} */ |
rgrover1 | 371:8f7d2137727a | 397 | /**@} */ |
rgrover1 | 371:8f7d2137727a | 398 | |
rgrover1 | 371:8f7d2137727a | 399 | #ifdef __cplusplus |
rgrover1 | 371:8f7d2137727a | 400 | } |
rgrover1 | 371:8f7d2137727a | 401 | #endif /* #ifdef __cplusplus */ |
rgrover1 | 371:8f7d2137727a | 402 | |
rgrover1 | 371:8f7d2137727a | 403 | #endif // PSTORAGE_H__ |