mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_NRF51_DONGLE/TOOLCHAIN_ARM_STD/fstorage.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_TY51822R3/TARGET_NORDIC/TARGET_NRF5x/TARGET_SDK_11/libraries/fstorage/fstorage.h@169:a7c7b631e539 
mbed library. Release version 164

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Kojto 148:fd96258d940d 1 /*
Kojto 148:fd96258d940d 2 * Copyright (c) 2015 Nordic Semiconductor ASA
Kojto 148:fd96258d940d 3 * All rights reserved.
Kojto 148:fd96258d940d 4 *
Kojto 148:fd96258d940d 5 * Redistribution and use in source and binary forms, with or without modification,
Kojto 148:fd96258d940d 6 * are permitted provided that the following conditions are met:
Kojto 148:fd96258d940d 7 *
Kojto 148:fd96258d940d 8 * 1. Redistributions of source code must retain the above copyright notice, this list
Kojto 148:fd96258d940d 9 * of conditions and the following disclaimer.
Kojto 148:fd96258d940d 10 *
Kojto 148:fd96258d940d 11 * 2. Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA
Kojto 148:fd96258d940d 12 * integrated circuit in a product or a software update for such product, must reproduce
Kojto 148:fd96258d940d 13 * the above copyright notice, this list of conditions and the following disclaimer in
Kojto 148:fd96258d940d 14 * the documentation and/or other materials provided with the distribution.
Kojto 148:fd96258d940d 15 *
Kojto 148:fd96258d940d 16 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be
Kojto 148:fd96258d940d 17 * used to endorse or promote products derived from this software without specific prior
Kojto 148:fd96258d940d 18 * written permission.
Kojto 148:fd96258d940d 19 *
Kojto 148:fd96258d940d 20 * 4. This software, with or without modification, must only be used with a
Kojto 148:fd96258d940d 21 * Nordic Semiconductor ASA integrated circuit.
Kojto 148:fd96258d940d 22 *
Kojto 148:fd96258d940d 23 * 5. Any software provided in binary or object form under this license must not be reverse
Kojto 148:fd96258d940d 24 * engineered, decompiled, modified and/or disassembled.
Kojto 148:fd96258d940d 25 *
Kojto 148:fd96258d940d 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
Kojto 148:fd96258d940d 27 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
Kojto 148:fd96258d940d 28 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
Kojto 148:fd96258d940d 29 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
Kojto 148:fd96258d940d 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
Kojto 148:fd96258d940d 31 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
Kojto 148:fd96258d940d 32 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
Kojto 148:fd96258d940d 33 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
Kojto 148:fd96258d940d 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
Kojto 148:fd96258d940d 35 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Kojto 148:fd96258d940d 36 *
Kojto 148:fd96258d940d 37 */
Kojto 148:fd96258d940d 38
Kojto 148:fd96258d940d 39
Kojto 148:fd96258d940d 40 #ifndef FSTORAGE_H__
Kojto 148:fd96258d940d 41 #define FSTORAGE_H__
Kojto 148:fd96258d940d 42
Kojto 148:fd96258d940d 43 /**
Kojto 148:fd96258d940d 44 * @defgroup fstorage fstorage
Kojto 148:fd96258d940d 45 * @ingroup app_common
Kojto 148:fd96258d940d 46 * @{
Kojto 148:fd96258d940d 47 *
Kojto 148:fd96258d940d 48 * @brief Module which provides functionality to store data to flash and erase flash pages.
Kojto 148:fd96258d940d 49 */
Kojto 148:fd96258d940d 50
Kojto 148:fd96258d940d 51 #include <stdint.h>
Kojto 148:fd96258d940d 52 #include "section_vars.h"
Kojto 148:fd96258d940d 53
Kojto 148:fd96258d940d 54
Kojto 148:fd96258d940d 55 /**@brief fstorage return values. */
Kojto 148:fd96258d940d 56 typedef enum
Kojto 148:fd96258d940d 57 {
Kojto 148:fd96258d940d 58 FS_SUCCESS,
Kojto 148:fd96258d940d 59 FS_ERR_NOT_INITIALIZED, //!< Error. The module is not initialized.
Kojto 148:fd96258d940d 60 FS_ERR_INVALID_CFG, //!< Error. Invalid fstorage configuration.
Kojto 148:fd96258d940d 61 FS_ERR_NULL_ARG, //!< Error. Argument is NULL.
Kojto 148:fd96258d940d 62 FS_ERR_INVALID_ARG, //!< Error. Argument contains invalid data.
Kojto 148:fd96258d940d 63 FS_ERR_INVALID_ADDR, //!< Error. Address out of bounds.
Kojto 148:fd96258d940d 64 FS_ERR_UNALIGNED_ADDR, //!< Error. Unaligned address.
Kojto 148:fd96258d940d 65 FS_ERR_QUEUE_FULL, //!< Error. Queue is full.
Kojto 148:fd96258d940d 66 FS_ERR_OPERATION_TIMEOUT, //!< Error. The operation has timed out.
Kojto 148:fd96258d940d 67 FS_ERR_INTERNAL, //!< Error. Internal error.
Kojto 148:fd96258d940d 68 } fs_ret_t;
Kojto 148:fd96258d940d 69
Kojto 148:fd96258d940d 70
Kojto 148:fd96258d940d 71 /**@brief fstorage event IDs. */
Kojto 148:fd96258d940d 72 typedef enum
Kojto 148:fd96258d940d 73 {
Kojto 148:fd96258d940d 74 FS_EVT_STORE, //!< Event for @ref fs_store.
Kojto 148:fd96258d940d 75 FS_EVT_ERASE //!< Event for @ref fs_erase.
Kojto 148:fd96258d940d 76 } fs_evt_id_t;
Kojto 148:fd96258d940d 77
Kojto 148:fd96258d940d 78
Kojto 148:fd96258d940d 79 #if defined(__CC_ARM)
Kojto 148:fd96258d940d 80 #pragma push
Kojto 148:fd96258d940d 81 #pragma anon_unions
Kojto 148:fd96258d940d 82 #elif defined(__ICCARM__)
Kojto 148:fd96258d940d 83 #pragma language=extended
Kojto 148:fd96258d940d 84 #elif defined(__GNUC__)
Kojto 148:fd96258d940d 85 /* anonymous unions are enabled by default */
Kojto 148:fd96258d940d 86 #endif
Kojto 148:fd96258d940d 87
Kojto 148:fd96258d940d 88 /**@brief An fstorage event. */
Kojto 148:fd96258d940d 89 typedef struct
Kojto 148:fd96258d940d 90 {
Kojto 148:fd96258d940d 91 fs_evt_id_t id; //!< The event ID.
Kojto 148:fd96258d940d 92 union
Kojto 148:fd96258d940d 93 {
Kojto 148:fd96258d940d 94 struct
Kojto 148:fd96258d940d 95 {
Kojto 148:fd96258d940d 96 uint32_t const * p_data; //!< Pointer to the data stored in flash.
Kojto 148:fd96258d940d 97 uint16_t length_words; //!< Length of the data, in 4-byte words.
Kojto 148:fd96258d940d 98 } store;
Kojto 148:fd96258d940d 99 struct
Kojto 148:fd96258d940d 100 {
Kojto 148:fd96258d940d 101 uint16_t first_page; //!< First page erased.
Kojto 148:fd96258d940d 102 uint16_t last_page; //!< Last page erased.
Kojto 148:fd96258d940d 103 } erase;
Kojto 148:fd96258d940d 104 };
Kojto 148:fd96258d940d 105 } fs_evt_t;
Kojto 148:fd96258d940d 106
Kojto 148:fd96258d940d 107 #if defined(__CC_ARM)
Kojto 148:fd96258d940d 108 #pragma pop
Kojto 148:fd96258d940d 109 #elif defined(__ICCARM__)
Kojto 148:fd96258d940d 110 /* leave anonymous unions enabled */
Kojto 148:fd96258d940d 111 #elif defined(__GNUC__)
Kojto 148:fd96258d940d 112 /* anonymous unions are enabled by default */
Kojto 148:fd96258d940d 113 #endif
Kojto 148:fd96258d940d 114
Kojto 148:fd96258d940d 115
Kojto 148:fd96258d940d 116 /**@brief fstorage event handler function prototype.
Kojto 148:fd96258d940d 117 *
Kojto 148:fd96258d940d 118 * @param[in] evt The event.
Kojto 148:fd96258d940d 119 * @param[in] result The result of the operation.
Kojto 148:fd96258d940d 120 */
Kojto 148:fd96258d940d 121 typedef void (*fs_cb_t)(fs_evt_t const * const evt, fs_ret_t result);
Kojto 148:fd96258d940d 122
Kojto 148:fd96258d940d 123
Kojto 148:fd96258d940d 124 /**@brief fstorage application-specific configuration.
Kojto 148:fd96258d940d 125 *
Kojto 148:fd96258d940d 126 * @details Specifies the callback to invoke when an operation completes, the number of flash pages
Kojto 148:fd96258d940d 127 * requested by the application and the priority with which these are to be assigned, with
Kojto 148:fd96258d940d 128 * respect to other applications. Additionally, the configuration specifies the boundaries
Kojto 148:fd96258d940d 129 * of the flash space assigned to an application. The configuration must be provided as an
Kojto 148:fd96258d940d 130 * argument when invoking @ref fs_store and @ref fs_erase.
Kojto 148:fd96258d940d 131 *
Kojto 148:fd96258d940d 132 * @note The fields @p p_start_addr and @p p_end_address are set by @ref fs_init, based on the
Kojto 148:fd96258d940d 133 * value of the field @p priority.
Kojto 148:fd96258d940d 134 */
Kojto 148:fd96258d940d 135 typedef struct
Kojto 148:fd96258d940d 136 {
Kojto 148:fd96258d940d 137 /**@brief The beginning of the flash space assigned to the application which registered this
Kojto 148:fd96258d940d 138 * configuration. This field is set by @ref fs_init.
Kojto 148:fd96258d940d 139 */
Kojto 148:fd96258d940d 140 uint32_t const * p_start_addr;
Kojto 148:fd96258d940d 141
Kojto 148:fd96258d940d 142 /**@brief The end of the flash space assigned to the application which registered this
Kojto 148:fd96258d940d 143 * configuration. This field is set by @ref fs_init.
Kojto 148:fd96258d940d 144 */
Kojto 148:fd96258d940d 145 uint32_t const * p_end_addr;
Kojto 148:fd96258d940d 146
Kojto 148:fd96258d940d 147 fs_cb_t const callback; //!< Callback to run when a flash operation has completed.
Kojto 148:fd96258d940d 148 uint8_t const num_pages; //!< The number of flash pages requested.
Kojto 148:fd96258d940d 149
Kojto 148:fd96258d940d 150 /**@brief The priority with which fstorage should assign flash pages to this application,
Kojto 148:fd96258d940d 151 * with respect to other applications. Applications with higher priority will be
Kojto 148:fd96258d940d 152 * assigned flash pages with a higher memory address. The highest priority is
Kojto 148:fd96258d940d 153 * reserved. Must be unique among configurations.
Kojto 148:fd96258d940d 154 */
Kojto 148:fd96258d940d 155 uint8_t const priority;
Kojto 148:fd96258d940d 156 } fs_config_t;
Kojto 148:fd96258d940d 157
Kojto 148:fd96258d940d 158
Kojto 148:fd96258d940d 159 /**@brief Macro for registering with an fstorage configuration.
Kojto 148:fd96258d940d 160 * Applications which use fstorage must register with the module using this macro.
Kojto 148:fd96258d940d 161 * Registering involves defining a variable which holds the configuration of fstorage
Kojto 148:fd96258d940d 162 * specific to the application which invokes the macro.
Kojto 148:fd96258d940d 163 *
Kojto 148:fd96258d940d 164 * @details This macro places the configuration variable in a section named "fs_data" that
Kojto 148:fd96258d940d 165 * fstorage uses during initialization and regular operation.
Kojto 148:fd96258d940d 166 *
Kojto 148:fd96258d940d 167 * @param[in] cfg_var A @e definition of a @ref fs_config_t variable.
Kojto 148:fd96258d940d 168 */
Kojto 148:fd96258d940d 169 #define FS_REGISTER_CFG(cfg_var) NRF_SECTION_VARS_ADD(fs_data, cfg_var)
Kojto 148:fd96258d940d 170
Kojto 148:fd96258d940d 171
Kojto 148:fd96258d940d 172 /**@brief Function for initializing the module.
Kojto 148:fd96258d940d 173 *
Kojto 148:fd96258d940d 174 * @details This functions assigns pages in flash according to all registered configurations.
Kojto 148:fd96258d940d 175 *
Kojto 148:fd96258d940d 176 * @retval FS_SUCCESS If the module was successfully initialized.
Kojto 148:fd96258d940d 177 */
Kojto 148:fd96258d940d 178 fs_ret_t fs_init(void);
Kojto 148:fd96258d940d 179
Kojto 148:fd96258d940d 180
Kojto 148:fd96258d940d 181 /**@brief Function for storing data in flash.
Kojto 148:fd96258d940d 182 *
Kojto 148:fd96258d940d 183 * @details Copies @p length_words words from @p p_src to the location pointed by @p p_dest.
Kojto 148:fd96258d940d 184 * If the length of the data exceeds @ref FS_MAX_WRITE_SIZE_WORDS, the data will be
Kojto 148:fd96258d940d 185 * written down in several chunks, as necessary. Only one event will be sent to the
Kojto 148:fd96258d940d 186 * application upon completion. Both the source and the destination of the data must be
Kojto 148:fd96258d940d 187 * word aligned. This function is asynchronous, completion is reported via an event sent
Kojto 148:fd96258d940d 188 * the the callback function specified in the supplied configuration.
Kojto 148:fd96258d940d 189 *
Kojto 148:fd96258d940d 190 * @warning The data to be written to flash has to be kept in memory until the operation has
Kojto 148:fd96258d940d 191 * terminated, i.e., an event is received.
Kojto 148:fd96258d940d 192 *
Kojto 148:fd96258d940d 193 * @param[in] p_config fstorage configuration registered by the application.
Kojto 148:fd96258d940d 194 * @param[in] p_dest The address in flash memory where to store the data.
Kojto 148:fd96258d940d 195 * @param[in] p_src Pointer to the data to store in flash.
Kojto 148:fd96258d940d 196 * @param[in] length_words Length of the data to store, in words.
Kojto 148:fd96258d940d 197 *
Kojto 148:fd96258d940d 198 * @retval FS_SUCCESS If the operation was queued successfully.
Kojto 148:fd96258d940d 199 * @retval FS_ERR_NOT_INITIALIZED If the module is not initialized.
Kojto 148:fd96258d940d 200 * @retval FS_ERR_INVALID_CFG If @p p_config is NULL or contains invalid data.
Kojto 148:fd96258d940d 201 * @retval FS_ERR_NULL_ARG If @p p_dest or @p p_src are NULL.
Kojto 148:fd96258d940d 202 * @retval FS_ERR_INVALID_ARG If @p length_words is zero.
Kojto 148:fd96258d940d 203 * @retval FS_ERR_INVALID_ADDR If @p p_dest or @p p_src are outside of the flash memory
Kojto 148:fd96258d940d 204 * boundaries specified in @p p_config.
Kojto 148:fd96258d940d 205 * @retval FS_ERR_UNALIGNED_ADDR If @p p_dest or @p p_src are not aligned to a word boundary.
Kojto 148:fd96258d940d 206 * @retval FS_ERR_QUEUE_FULL If the internal operation queue is full.
Kojto 148:fd96258d940d 207 */
Kojto 148:fd96258d940d 208 fs_ret_t fs_store(fs_config_t const * const p_config,
Kojto 148:fd96258d940d 209 uint32_t const * const p_dest,
Kojto 148:fd96258d940d 210 uint32_t const * const p_src,
Kojto 148:fd96258d940d 211 uint16_t length_words);
Kojto 148:fd96258d940d 212
Kojto 148:fd96258d940d 213
Kojto 148:fd96258d940d 214 /**@brief Function for erasing flash pages.
Kojto 148:fd96258d940d 215 *
Kojto 148:fd96258d940d 216 * @details Starting from the page at @p p_page_addr, erases @p num_pages flash pages.
Kojto 148:fd96258d940d 217 * @p p_page_addr must be aligned to a page boundary. All pages to be erased must be
Kojto 148:fd96258d940d 218 * within the bounds specified in the supplied fstorage configuration.
Kojto 148:fd96258d940d 219 * This function is asynchronous. Completion is reported via an event.
Kojto 148:fd96258d940d 220 *
Kojto 148:fd96258d940d 221 * @param[in] p_config fstorage configuration registered by the application.
Kojto 148:fd96258d940d 222 * @param[in] p_page_addr Address of the page to erase. Must be aligned to a page boundary.
Kojto 148:fd96258d940d 223 * @param[in] num_pages Number of pages to erase. May not be zero.
Kojto 148:fd96258d940d 224 *
Kojto 148:fd96258d940d 225 * @retval FS_SUCCESS If the operation was queued successfully.
Kojto 148:fd96258d940d 226 * @retval FS_ERR_NOT_INITIALIZED If the module is not initialized.
Kojto 148:fd96258d940d 227 * @retval FS_ERR_INVALID_CFG If @p p_config is NULL or contains invalid data.
Kojto 148:fd96258d940d 228 * @retval FS_ERR_NULL_ARG If @p p_page_addr is NULL.
Kojto 148:fd96258d940d 229 * @retval FS_ERR_INVALID_ARG If @p num_pages is zero.
Kojto 148:fd96258d940d 230 * @retval FS_ERR_INVALID_ADDR If the operation would go beyond the flash memory boundaries
Kojto 148:fd96258d940d 231 * specified in @p p_config.
Kojto 148:fd96258d940d 232 * @retval FS_ERR_UNALIGNED_ADDR If @p p_page_addr is not aligned to a page boundary.
Kojto 148:fd96258d940d 233 * @retval FS_ERR_QUEUE_FULL If the internal operation queue is full.
Kojto 148:fd96258d940d 234 */
Kojto 148:fd96258d940d 235 fs_ret_t fs_erase(fs_config_t const * const p_config,
Kojto 148:fd96258d940d 236 uint32_t const * const p_page_addr,
Kojto 148:fd96258d940d 237 uint16_t num_pages);
Kojto 148:fd96258d940d 238
Kojto 148:fd96258d940d 239
Kojto 148:fd96258d940d 240 /**@brief Function for retrieving the number of queued flash operations.
Kojto 148:fd96258d940d 241 *
Kojto 148:fd96258d940d 242 * @param[out] p_op_count The number of queued flash operations.
Kojto 148:fd96258d940d 243 *
Kojto 148:fd96258d940d 244 * @retval FS_SUCCESS If the number of queued operations was retrieved successfully.
Kojto 148:fd96258d940d 245 * @retval FS_ERR_NULL_ARG If @p p_op_count is NULL.
Kojto 148:fd96258d940d 246 */
Kojto 148:fd96258d940d 247 fs_ret_t fs_queued_op_count_get(uint32_t * const p_op_count);
Kojto 148:fd96258d940d 248
Kojto 148:fd96258d940d 249
Kojto 148:fd96258d940d 250 /**@brief Function for handling system events from the SoftDevice.
Kojto 148:fd96258d940d 251 *
Kojto 148:fd96258d940d 252 * @details If any of the modules used by the application rely on fstorage, the application should
Kojto 148:fd96258d940d 253 * dispatch system events to fstorage using this function.
Kojto 148:fd96258d940d 254 *
Kojto 148:fd96258d940d 255 * @param[in] sys_evt System event from the SoftDevice.
Kojto 148:fd96258d940d 256 */
Kojto 148:fd96258d940d 257 void fs_sys_event_handler(uint32_t sys_evt);
Kojto 148:fd96258d940d 258
Kojto 148:fd96258d940d 259
Kojto 148:fd96258d940d 260 /** @} */
Kojto 148:fd96258d940d 261
Kojto 148:fd96258d940d 262 #endif // FSTORAGE_H__