test

Fork of nRF51822 by Nordic Semiconductor

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?

UserRevisionLine numberNew contents of line
rgrover1 371:8f7d2137727a 1 /*
rgrover1 371:8f7d2137727a 2 * Copyright (c) Nordic Semiconductor ASA
rgrover1 371:8f7d2137727a 3 * All rights reserved.
rgrover1 371:8f7d2137727a 4 *
rgrover1 371:8f7d2137727a 5 * Redistribution and use in source and binary forms, with or without modification,
rgrover1 371:8f7d2137727a 6 * are permitted provided that the following conditions are met:
rgrover1 371:8f7d2137727a 7 *
rgrover1 371:8f7d2137727a 8 * 1. Redistributions of source code must retain the above copyright notice, this
rgrover1 371:8f7d2137727a 9 * list of conditions and the following disclaimer.
rgrover1 371:8f7d2137727a 10 *
rgrover1 371:8f7d2137727a 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
rgrover1 371:8f7d2137727a 12 * list of conditions and the following disclaimer in the documentation and/or
rgrover1 371:8f7d2137727a 13 * other materials provided with the distribution.
rgrover1 371:8f7d2137727a 14 *
rgrover1 371:8f7d2137727a 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
rgrover1 371:8f7d2137727a 16 * contributors to this software may be used to endorse or promote products
rgrover1 371:8f7d2137727a 17 * derived from this software without specific prior written permission.
rgrover1 371:8f7d2137727a 18 *
rgrover1 371:8f7d2137727a 19 *
rgrover1 371:8f7d2137727a 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
rgrover1 371:8f7d2137727a 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
rgrover1 371:8f7d2137727a 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
rgrover1 371:8f7d2137727a 23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
rgrover1 371:8f7d2137727a 24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
rgrover1 371:8f7d2137727a 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
rgrover1 371:8f7d2137727a 26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
rgrover1 371:8f7d2137727a 27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
rgrover1 371:8f7d2137727a 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
rgrover1 371:8f7d2137727a 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rgrover1 371:8f7d2137727a 30 *
rgrover1 371:8f7d2137727a 31 */
rgrover1 371:8f7d2137727a 32
rgrover1 371:8f7d2137727a 33 /**@file
rgrover1 371:8f7d2137727a 34 *
rgrover1 371:8f7d2137727a 35 * @defgroup persistent_storage Persistent Storage Interface
rgrover1 371:8f7d2137727a 36 * @{
rgrover1 371:8f7d2137727a 37 * @ingroup app_common
rgrover1 371:8f7d2137727a 38 * @brief Abstracted flash interface.
rgrover1 371:8f7d2137727a 39 *
rgrover1 371:8f7d2137727a 40 * @details In order to ensure that the SDK and application be moved to alternate persistent storage
rgrover1 371:8f7d2137727a 41 * options other than the default provided with NRF solution, an abstracted interface is provided
rgrover1 371:8f7d2137727a 42 * by the module to ensure SDK modules and application can be ported to alternate option with ease.
rgrover1 371:8f7d2137727a 43 */
rgrover1 371:8f7d2137727a 44
rgrover1 371:8f7d2137727a 45 #ifndef PSTORAGE_H__
rgrover1 371:8f7d2137727a 46 #define PSTORAGE_H__
rgrover1 371:8f7d2137727a 47
rgrover1 371:8f7d2137727a 48 #include "pstorage_platform.h"
rgrover1 371:8f7d2137727a 49
rgrover1 371:8f7d2137727a 50 #ifdef __cplusplus
rgrover1 371:8f7d2137727a 51 extern "C" {
rgrover1 371:8f7d2137727a 52 #endif /* #ifdef __cplusplus */
rgrover1 371:8f7d2137727a 53
rgrover1 371:8f7d2137727a 54
rgrover1 371:8f7d2137727a 55 /**@defgroup ps_opcode Persistent Storage Access Operation Codes
rgrover1 371:8f7d2137727a 56 * @{
rgrover1 371:8f7d2137727a 57 * @brief Persistent Storage Access Operation Codes. These are used to report any error during
rgrover1 371:8f7d2137727a 58 * a persistent storage access operation or any general error that may occur in the
rgrover1 371:8f7d2137727a 59 * interface.
rgrover1 371:8f7d2137727a 60 *
rgrover1 371:8f7d2137727a 61 * @details Persistent Storage Access Operation Codes used in error notification callback
rgrover1 371:8f7d2137727a 62 * registered with the interface to report any error during an persistent storage access
rgrover1 371:8f7d2137727a 63 * operation or any general error that may occur in the interface.
rgrover1 371:8f7d2137727a 64 */
rgrover1 371:8f7d2137727a 65 #define PSTORAGE_ERROR_OP_CODE 0x01 /**< General Error Code */
rgrover1 371:8f7d2137727a 66 #define PSTORAGE_STORE_OP_CODE 0x02 /**< Error when Store Operation was requested */
rgrover1 371:8f7d2137727a 67 #define PSTORAGE_LOAD_OP_CODE 0x03 /**< Error when Load Operation was requested */
rgrover1 371:8f7d2137727a 68 #define PSTORAGE_CLEAR_OP_CODE 0x04 /**< Error when Clear Operation was requested */
rgrover1 371:8f7d2137727a 69 #define PSTORAGE_UPDATE_OP_CODE 0x05 /**< Update an already touched storage block */
rgrover1 371:8f7d2137727a 70
rgrover1 371:8f7d2137727a 71 /**@} */
rgrover1 371:8f7d2137727a 72
rgrover1 371:8f7d2137727a 73 /**@defgroup pstorage_data_types Persistent Memory Interface Data Types
rgrover1 371:8f7d2137727a 74 * @{
rgrover1 371:8f7d2137727a 75 * @brief Data Types needed for interfacing with persistent memory.
rgrover1 371:8f7d2137727a 76 *
rgrover1 371:8f7d2137727a 77 * @details Data Types needed for interfacing with persistent memory.
rgrover1 371:8f7d2137727a 78 */
rgrover1 371:8f7d2137727a 79
rgrover1 371:8f7d2137727a 80 /**@brief Persistent Storage Error Reporting Callback
rgrover1 371:8f7d2137727a 81 *
rgrover1 371:8f7d2137727a 82 * @details Persistent Storage Error Reporting Callback that is used by the interface to report
rgrover1 371:8f7d2137727a 83 * success or failure of a flash operation. Therefore, for any operations, application
rgrover1 371:8f7d2137727a 84 * can know when the procedure was complete. For store operation, since no data copy
rgrover1 371:8f7d2137727a 85 * is made, receiving a success or failure notification, indicated by the reason
rgrover1 371:8f7d2137727a 86 * parameter of callback is an indication that the resident memory could now be reused
rgrover1 371:8f7d2137727a 87 * or freed, as the case may be.
rgrover1 371:8f7d2137727a 88 *
rgrover1 371:8f7d2137727a 89 * @param[in] handle Identifies module and block for which callback is received.
rgrover1 371:8f7d2137727a 90 * @param[in] op_code Identifies the operation for which the event is notified.
rgrover1 371:8f7d2137727a 91 * @param[in] result Identifies the result of flash access operation.
rgrover1 371:8f7d2137727a 92 * NRF_SUCCESS implies, operation succeeded.
rgrover1 371:8f7d2137727a 93 * @param[in] p_data Identifies the application data pointer. In case of store operation, this
rgrover1 371:8f7d2137727a 94 * points to the resident source of application memory that application can now
rgrover1 371:8f7d2137727a 95 * free or reuse. In case of clear, this is NULL as no application pointer is
rgrover1 371:8f7d2137727a 96 * needed for this operation.
rgrover1 371:8f7d2137727a 97 * @param[in] data_len Length data application had provided for the operation.
rgrover1 371:8f7d2137727a 98 *
rgrover1 371:8f7d2137727a 99 */
rgrover1 371:8f7d2137727a 100 typedef void (*pstorage_ntf_cb_t)(pstorage_handle_t * p_handle,
rgrover1 371:8f7d2137727a 101 uint8_t op_code,
rgrover1 371:8f7d2137727a 102 uint32_t result,
rgrover1 371:8f7d2137727a 103 uint8_t * p_data,
rgrover1 371:8f7d2137727a 104 uint32_t data_len);
rgrover1 371:8f7d2137727a 105
rgrover1 371:8f7d2137727a 106
rgrover1 371:8f7d2137727a 107 typedef struct
rgrover1 371:8f7d2137727a 108 {
rgrover1 371:8f7d2137727a 109 pstorage_ntf_cb_t cb; /**< Callback registered with the module to be notified of any error occurring in persistent memory management */
rgrover1 371:8f7d2137727a 110 pstorage_size_t block_size; /**< Desired block size for persistent memory storage, for example, if a module has a table with 10 entries, each entry is size 64 bytes,
rgrover1 371:8f7d2137727a 111 * it can request 10 blocks with block size 64 bytes. On the other hand, the module can also request one block of size 640 based on
rgrover1 371:8f7d2137727a 112 * how it would like to access or alter memory in persistent memory.
rgrover1 371:8f7d2137727a 113 * First option is preferred when single entries that need to be updated often when having no impact on the other entries.
rgrover1 371:8f7d2137727a 114 * While second option is preferred when entries of table are not changed on individually but have common point of loading and storing
rgrover1 371:8f7d2137727a 115 * data. */
rgrover1 371:8f7d2137727a 116 pstorage_size_t block_count; /** Number of blocks requested by the module, minimum values is 1. */
rgrover1 371:8f7d2137727a 117 } pstorage_module_param_t;
rgrover1 371:8f7d2137727a 118
rgrover1 371:8f7d2137727a 119 /**@} */
rgrover1 371:8f7d2137727a 120
rgrover1 371:8f7d2137727a 121 /**@defgroup pstorage_routines Persistent Storage Access Routines
rgrover1 371:8f7d2137727a 122 * @{
rgrover1 371:8f7d2137727a 123 * @brief Functions/Interface SDK modules use to persistently store data.
rgrover1 371:8f7d2137727a 124 *
rgrover1 371:8f7d2137727a 125 * @details Interface for Application & SDK module to load/store information persistently.
rgrover1 371:8f7d2137727a 126 * Note: that while implementation of each of the persistent storage access function
rgrover1 371:8f7d2137727a 127 * depends on the system and can specific to system/solution, the signature of the
rgrover1 371:8f7d2137727a 128 * interface routines should not be altered.
rgrover1 371:8f7d2137727a 129 */
rgrover1 371:8f7d2137727a 130
rgrover1 371:8f7d2137727a 131 /**@brief Module Initialization Routine.
rgrover1 371:8f7d2137727a 132 *
rgrover1 371:8f7d2137727a 133 * @details Initializes module. To be called once before any other APIs of the module are used.
rgrover1 371:8f7d2137727a 134 *
rgrover1 371:8f7d2137727a 135 * @retval NRF_SUCCESS on success, else an error code indicating reason for failure.
rgrover1 371:8f7d2137727a 136 */
rgrover1 371:8f7d2137727a 137 uint32_t pstorage_init(void);
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__