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.

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc
mbed library release version 165

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AnnaBridge 143:86740a56073b 1 /*
AnnaBridge 143:86740a56073b 2 * Copyright (c) 2015 Nordic Semiconductor ASA
AnnaBridge 143:86740a56073b 3 * All rights reserved.
AnnaBridge 143:86740a56073b 4 *
AnnaBridge 143:86740a56073b 5 * Redistribution and use in source and binary forms, with or without modification,
AnnaBridge 143:86740a56073b 6 * are permitted provided that the following conditions are met:
AnnaBridge 143:86740a56073b 7 *
AnnaBridge 143:86740a56073b 8 * 1. Redistributions of source code must retain the above copyright notice, this list
AnnaBridge 143:86740a56073b 9 * of conditions and the following disclaimer.
AnnaBridge 143:86740a56073b 10 *
AnnaBridge 143:86740a56073b 11 * 2. Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA
AnnaBridge 143:86740a56073b 12 * integrated circuit in a product or a software update for such product, must reproduce
AnnaBridge 143:86740a56073b 13 * the above copyright notice, this list of conditions and the following disclaimer in
AnnaBridge 143:86740a56073b 14 * the documentation and/or other materials provided with the distribution.
AnnaBridge 143:86740a56073b 15 *
AnnaBridge 143:86740a56073b 16 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be
AnnaBridge 143:86740a56073b 17 * used to endorse or promote products derived from this software without specific prior
AnnaBridge 143:86740a56073b 18 * written permission.
AnnaBridge 143:86740a56073b 19 *
AnnaBridge 143:86740a56073b 20 * 4. This software, with or without modification, must only be used with a
AnnaBridge 143:86740a56073b 21 * Nordic Semiconductor ASA integrated circuit.
AnnaBridge 143:86740a56073b 22 *
AnnaBridge 143:86740a56073b 23 * 5. Any software provided in binary or object form under this license must not be reverse
AnnaBridge 143:86740a56073b 24 * engineered, decompiled, modified and/or disassembled.
AnnaBridge 143:86740a56073b 25 *
AnnaBridge 143:86740a56073b 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
AnnaBridge 143:86740a56073b 27 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
AnnaBridge 143:86740a56073b 28 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
AnnaBridge 143:86740a56073b 29 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
AnnaBridge 143:86740a56073b 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
AnnaBridge 143:86740a56073b 31 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
AnnaBridge 143:86740a56073b 32 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
AnnaBridge 143:86740a56073b 33 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
AnnaBridge 143:86740a56073b 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
AnnaBridge 143:86740a56073b 35 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AnnaBridge 143:86740a56073b 36 *
AnnaBridge 143:86740a56073b 37 */
AnnaBridge 143:86740a56073b 38
AnnaBridge 143:86740a56073b 39
AnnaBridge 143:86740a56073b 40 #ifndef FDS_H__
AnnaBridge 143:86740a56073b 41 #define FDS_H__
AnnaBridge 143:86740a56073b 42
AnnaBridge 143:86740a56073b 43 /**
AnnaBridge 143:86740a56073b 44 * @defgroup flash_data_storage Flash Data Storage
AnnaBridge 143:86740a56073b 45 * @ingroup app_common
AnnaBridge 143:86740a56073b 46 * @{
AnnaBridge 143:86740a56073b 47 *
AnnaBridge 143:86740a56073b 48 * @brief Flash Data Storage (FDS).
AnnaBridge 143:86740a56073b 49 *
AnnaBridge 143:86740a56073b 50 * @details Flash Data Storage is a minimalistic, record-oriented file system for the on-chip
AnnaBridge 143:86740a56073b 51 * flash. Files are stored as a collection of records of variable length. FDS supports
AnnaBridge 143:86740a56073b 52 * synchronous read operations and asynchronous write operations (write, update,
AnnaBridge 143:86740a56073b 53 * and delete). FDS can be used from multiple threads.
AnnaBridge 143:86740a56073b 54 */
AnnaBridge 143:86740a56073b 55
AnnaBridge 143:86740a56073b 56 #include <stdint.h>
AnnaBridge 143:86740a56073b 57 #include <stdbool.h>
AnnaBridge 143:86740a56073b 58 #include "sdk_errors.h"
AnnaBridge 143:86740a56073b 59
AnnaBridge 143:86740a56073b 60
AnnaBridge 143:86740a56073b 61 /**@brief Invalid file ID.
AnnaBridge 143:86740a56073b 62 *
AnnaBridge 143:86740a56073b 63 * This value must not be used as a file ID by the application.
AnnaBridge 143:86740a56073b 64 */
AnnaBridge 143:86740a56073b 65 #define FDS_FILE_ID_INVALID (0xFFFF)
AnnaBridge 143:86740a56073b 66
AnnaBridge 143:86740a56073b 67
AnnaBridge 143:86740a56073b 68 /**@brief Record key for deleted records.
AnnaBridge 143:86740a56073b 69 *
AnnaBridge 143:86740a56073b 70 * This key is used to flag a record as "dirty", which means that it should be removed during
AnnaBridge 143:86740a56073b 71 * the next garbage collection. This value must not be used as a record key by the application.
AnnaBridge 143:86740a56073b 72 */
AnnaBridge 143:86740a56073b 73 #define FDS_RECORD_KEY_DIRTY (0x0000)
AnnaBridge 143:86740a56073b 74
AnnaBridge 143:86740a56073b 75
AnnaBridge 143:86740a56073b 76 /**@brief FDS return values.
AnnaBridge 143:86740a56073b 77 */
AnnaBridge 143:86740a56073b 78 enum
AnnaBridge 143:86740a56073b 79 {
AnnaBridge 143:86740a56073b 80 FDS_SUCCESS = NRF_SUCCESS, //!< The operation completed successfully.
AnnaBridge 143:86740a56073b 81 FDS_ERR_OPERATION_TIMEOUT, //!< Error. The operation timed out.
AnnaBridge 143:86740a56073b 82 FDS_ERR_NOT_INITIALIZED, //!< Error. The module has not been initialized.
AnnaBridge 143:86740a56073b 83 FDS_ERR_UNALIGNED_ADDR, //!< Error. The input data is not aligned to a word boundary.
AnnaBridge 143:86740a56073b 84 FDS_ERR_INVALID_ARG, //!< Error. The parameter contains invalid data.
AnnaBridge 143:86740a56073b 85 FDS_ERR_NULL_ARG, //!< Error. The parameter is NULL.
AnnaBridge 143:86740a56073b 86 FDS_ERR_NO_OPEN_RECORDS, //!< Error. The record is not open, so it cannot be closed.
AnnaBridge 143:86740a56073b 87 FDS_ERR_NO_SPACE_IN_FLASH, //!< Error. There is no space in flash memory.
AnnaBridge 143:86740a56073b 88 FDS_ERR_NO_SPACE_IN_QUEUES, //!< Error. There is no space in the internal queues.
AnnaBridge 143:86740a56073b 89 FDS_ERR_RECORD_TOO_LARGE, //!< Error. The record exceeds the maximum allowed size.
AnnaBridge 143:86740a56073b 90 FDS_ERR_NOT_FOUND, //!< Error. The record was not found.
AnnaBridge 143:86740a56073b 91 FDS_ERR_NO_PAGES, //!< Error. No flash pages are available.
AnnaBridge 143:86740a56073b 92 FDS_ERR_USER_LIMIT_REACHED, //!< Error. The maximum number of users has been reached.
AnnaBridge 143:86740a56073b 93 FDS_ERR_CRC_CHECK_FAILED, //!< Error. The CRC check failed.
AnnaBridge 143:86740a56073b 94 FDS_ERR_BUSY, //!< Error. The underlying flash subsystem was busy.
AnnaBridge 143:86740a56073b 95 FDS_ERR_INTERNAL, //!< Error. An internal error occurred.
AnnaBridge 143:86740a56073b 96 };
AnnaBridge 143:86740a56073b 97
AnnaBridge 143:86740a56073b 98
AnnaBridge 143:86740a56073b 99 /**@brief Part of the record metadata.
AnnaBridge 143:86740a56073b 100 *
AnnaBridge 143:86740a56073b 101 * Contains the record key and the length of the record data.
AnnaBridge 143:86740a56073b 102 */
AnnaBridge 143:86740a56073b 103 typedef struct
AnnaBridge 143:86740a56073b 104 {
AnnaBridge 143:86740a56073b 105 uint16_t record_key; //!< The record key (must be in the range 0x0001 - 0xBFFF).
AnnaBridge 143:86740a56073b 106 uint16_t length_words; //!< The length of the record data (in 4-byte words).
AnnaBridge 143:86740a56073b 107 } fds_tl_t;
AnnaBridge 143:86740a56073b 108
AnnaBridge 143:86740a56073b 109
AnnaBridge 143:86740a56073b 110 /**@brief Part of the record metadata.
AnnaBridge 143:86740a56073b 111 *
AnnaBridge 143:86740a56073b 112 * Contains the ID of the file that the record belongs to and the CRC16 check value of the record.
AnnaBridge 143:86740a56073b 113 */
AnnaBridge 143:86740a56073b 114 typedef struct
AnnaBridge 143:86740a56073b 115 {
AnnaBridge 143:86740a56073b 116 uint16_t file_id; //!< The ID of the file that the record belongs to.
AnnaBridge 143:86740a56073b 117
AnnaBridge 143:86740a56073b 118 /**@brief CRC16 check value.
AnnaBridge 143:86740a56073b 119 *
AnnaBridge 143:86740a56073b 120 * The CRC is calculated over the entire record as stored in flash (including the record
AnnaBridge 143:86740a56073b 121 * metadata except the CRC field itself). The CRC standard employed is CRC-16-CCITT.
AnnaBridge 143:86740a56073b 122 */
AnnaBridge 143:86740a56073b 123 uint16_t crc16;
AnnaBridge 143:86740a56073b 124 } fds_ic_t;
AnnaBridge 143:86740a56073b 125
AnnaBridge 143:86740a56073b 126
AnnaBridge 143:86740a56073b 127 /**@brief The record metadata as stored in flash.
AnnaBridge 143:86740a56073b 128 */
AnnaBridge 143:86740a56073b 129 typedef struct
AnnaBridge 143:86740a56073b 130 {
AnnaBridge 143:86740a56073b 131 fds_tl_t tl; //!< See @ref fds_tl_t.
AnnaBridge 143:86740a56073b 132 fds_ic_t ic; //!< See @ref fds_ic_t.
AnnaBridge 143:86740a56073b 133 uint32_t record_id; //!< The unique record ID (32 bits).
AnnaBridge 143:86740a56073b 134 } fds_header_t;
AnnaBridge 143:86740a56073b 135
AnnaBridge 143:86740a56073b 136
AnnaBridge 143:86740a56073b 137 /**@brief The record descriptor structure that is used to manipulate records.
AnnaBridge 143:86740a56073b 138 *
AnnaBridge 143:86740a56073b 139 * This structure is used by the FDS module. You must provide the descriptor to the module when
AnnaBridge 143:86740a56073b 140 * you manipulate existing records. However, you should never modify it or use any of its fields.
AnnaBridge 143:86740a56073b 141 *
AnnaBridge 143:86740a56073b 142 * @note Never reuse the same descriptor for different records.
AnnaBridge 143:86740a56073b 143 */
AnnaBridge 143:86740a56073b 144 typedef struct
AnnaBridge 143:86740a56073b 145 {
AnnaBridge 143:86740a56073b 146 uint32_t record_id; //!< The unique record ID.
AnnaBridge 143:86740a56073b 147 uint32_t const * p_record; //!< The last known location of the record in flash.
AnnaBridge 143:86740a56073b 148 uint16_t gc_run_count; //!< Number of times garbage collection has been run.
AnnaBridge 143:86740a56073b 149 bool record_is_open; //!< Whether the record is currently open.
AnnaBridge 143:86740a56073b 150 } fds_record_desc_t;
AnnaBridge 143:86740a56073b 151
AnnaBridge 143:86740a56073b 152
AnnaBridge 143:86740a56073b 153 /**@brief Structure that can be used to read the contents of a record stored in flash.
AnnaBridge 143:86740a56073b 154 *
AnnaBridge 143:86740a56073b 155 * This structure does not reflect the physical layout of a record in flash, but it points
AnnaBridge 143:86740a56073b 156 * to the locations where the record header (metadata) and the record data are stored.
AnnaBridge 143:86740a56073b 157 */
AnnaBridge 143:86740a56073b 158 typedef struct
AnnaBridge 143:86740a56073b 159 {
AnnaBridge 143:86740a56073b 160 fds_header_t const * p_header; //!< Location of the record header in flash.
AnnaBridge 143:86740a56073b 161 void const * p_data; //!< Location of the record data in flash.
AnnaBridge 143:86740a56073b 162 } fds_flash_record_t;
AnnaBridge 143:86740a56073b 163
AnnaBridge 143:86740a56073b 164
AnnaBridge 143:86740a56073b 165 /**@brief A chunk of record data to be written to flash.
AnnaBridge 143:86740a56073b 166 *
AnnaBridge 143:86740a56073b 167 * @p p_data must be aligned to a word boundary. Make sure to keep it in
AnnaBridge 143:86740a56073b 168 * memory until the operation has completed, which is indicated by the respective FDS event.
AnnaBridge 143:86740a56073b 169 */
AnnaBridge 143:86740a56073b 170 typedef struct
AnnaBridge 143:86740a56073b 171 {
AnnaBridge 143:86740a56073b 172 void const * p_data; //!< Pointer to the data to store. Must be word-aligned.
AnnaBridge 143:86740a56073b 173 uint16_t length_words; //!< Length of data pointed to by @p p_data (in 4-byte words).
AnnaBridge 143:86740a56073b 174 } fds_record_chunk_t;
AnnaBridge 143:86740a56073b 175
AnnaBridge 143:86740a56073b 176
AnnaBridge 143:86740a56073b 177 /**@brief A record to be written to flash.
AnnaBridge 143:86740a56073b 178 */
AnnaBridge 143:86740a56073b 179 typedef struct
AnnaBridge 143:86740a56073b 180 {
AnnaBridge 143:86740a56073b 181 uint16_t file_id; //!< The ID of the file that the record belongs to.
AnnaBridge 143:86740a56073b 182 uint16_t key; //!< The record key.
AnnaBridge 143:86740a56073b 183 struct
AnnaBridge 143:86740a56073b 184 {
AnnaBridge 143:86740a56073b 185 fds_record_chunk_t const * p_chunks; //!< The chunks that make up the record data.
AnnaBridge 143:86740a56073b 186 uint16_t num_chunks; //!< The number of chunks that make up the data.
AnnaBridge 143:86740a56073b 187 } data;
AnnaBridge 143:86740a56073b 188 } fds_record_t;
AnnaBridge 143:86740a56073b 189
AnnaBridge 143:86740a56073b 190
AnnaBridge 143:86740a56073b 191 /**@brief A token to a reserved space in flash, created by @ref fds_reserve.
AnnaBridge 143:86740a56073b 192 *
AnnaBridge 143:86740a56073b 193 * This token can be used to write the record in the reserved space (@ref fds_record_write_reserved)
AnnaBridge 143:86740a56073b 194 * or to cancel the reservation (@ref fds_reserve_cancel).
AnnaBridge 143:86740a56073b 195 */
AnnaBridge 143:86740a56073b 196 typedef struct
AnnaBridge 143:86740a56073b 197 {
AnnaBridge 143:86740a56073b 198 uint16_t page; //!< The logical ID of the page where space was reserved.
AnnaBridge 143:86740a56073b 199 uint16_t length_words; //!< The amount of space reserved (in 4-byte words).
AnnaBridge 143:86740a56073b 200 } fds_reserve_token_t;
AnnaBridge 143:86740a56073b 201
AnnaBridge 143:86740a56073b 202
AnnaBridge 143:86740a56073b 203 /**@brief A token to keep information about the progress of @ref fds_record_find,
AnnaBridge 143:86740a56073b 204 * @ref fds_record_find_by_key, and @ref fds_record_find_in_file.
AnnaBridge 143:86740a56073b 205 *
AnnaBridge 143:86740a56073b 206 * @note Always zero-initialize the token before using it for the first time.
AnnaBridge 143:86740a56073b 207 * @note Never reuse the same token to search for different records.
AnnaBridge 143:86740a56073b 208 */
AnnaBridge 143:86740a56073b 209 typedef struct
AnnaBridge 143:86740a56073b 210 {
AnnaBridge 143:86740a56073b 211 uint32_t const * p_addr;
AnnaBridge 143:86740a56073b 212 uint16_t page;
AnnaBridge 143:86740a56073b 213 } fds_find_token_t;
AnnaBridge 143:86740a56073b 214
AnnaBridge 143:86740a56073b 215
AnnaBridge 143:86740a56073b 216 /**@brief FDS event IDs.
AnnaBridge 143:86740a56073b 217 */
AnnaBridge 143:86740a56073b 218 typedef enum
AnnaBridge 143:86740a56073b 219 {
AnnaBridge 143:86740a56073b 220 FDS_EVT_INIT, //!< Event for @ref fds_init.
AnnaBridge 143:86740a56073b 221 FDS_EVT_WRITE, //!< Event for @ref fds_record_write and @ref fds_record_write_reserved.
AnnaBridge 143:86740a56073b 222 FDS_EVT_UPDATE, //!< Event for @ref fds_record_update.
AnnaBridge 143:86740a56073b 223 FDS_EVT_DEL_RECORD, //!< Event for @ref fds_record_delete.
AnnaBridge 143:86740a56073b 224 FDS_EVT_DEL_FILE, //!< Event for @ref fds_file_delete.
AnnaBridge 143:86740a56073b 225 FDS_EVT_GC //!< Event for @ref fds_gc.
AnnaBridge 143:86740a56073b 226 } fds_evt_id_t;
AnnaBridge 143:86740a56073b 227
AnnaBridge 143:86740a56073b 228
AnnaBridge 143:86740a56073b 229 #if defined(__CC_ARM)
AnnaBridge 143:86740a56073b 230 #pragma push
AnnaBridge 143:86740a56073b 231 #pragma anon_unions
AnnaBridge 143:86740a56073b 232 #elif defined(__ICCARM__)
AnnaBridge 143:86740a56073b 233 #pragma language=extended
AnnaBridge 143:86740a56073b 234 #elif defined(__GNUC__)
AnnaBridge 143:86740a56073b 235 /* anonymous unions are enabled by default */
AnnaBridge 143:86740a56073b 236 #endif
AnnaBridge 143:86740a56073b 237
AnnaBridge 143:86740a56073b 238 /**@brief An FDS event.
AnnaBridge 143:86740a56073b 239 */
AnnaBridge 143:86740a56073b 240 typedef struct
AnnaBridge 143:86740a56073b 241 {
AnnaBridge 143:86740a56073b 242 fds_evt_id_t id; //!< The event ID. See @ref fds_evt_id_t.
AnnaBridge 143:86740a56073b 243 ret_code_t result; //!< The result of the operation related to this event.
AnnaBridge 143:86740a56073b 244 union
AnnaBridge 143:86740a56073b 245 {
AnnaBridge 143:86740a56073b 246 struct
AnnaBridge 143:86740a56073b 247 {
AnnaBridge 143:86740a56073b 248 /* Currently not used. */
AnnaBridge 143:86740a56073b 249 uint16_t pages_not_mounted;
AnnaBridge 143:86740a56073b 250 } init;
AnnaBridge 143:86740a56073b 251 struct
AnnaBridge 143:86740a56073b 252 {
AnnaBridge 143:86740a56073b 253 uint32_t record_id;
AnnaBridge 143:86740a56073b 254 uint16_t file_id;
AnnaBridge 143:86740a56073b 255 uint16_t record_key;
AnnaBridge 143:86740a56073b 256 bool is_record_updated;
AnnaBridge 143:86740a56073b 257 } write; //!< Information for @ref FDS_EVT_WRITE and @ref FDS_EVT_UPDATE events.
AnnaBridge 143:86740a56073b 258 struct
AnnaBridge 143:86740a56073b 259 {
AnnaBridge 143:86740a56073b 260 uint32_t record_id;
AnnaBridge 143:86740a56073b 261 uint16_t file_id;
AnnaBridge 143:86740a56073b 262 uint16_t record_key;
AnnaBridge 143:86740a56073b 263 uint16_t records_deleted_count;
AnnaBridge 143:86740a56073b 264 } del; //!< Information for @ref FDS_EVT_DEL_RECORD and @ref FDS_EVT_DEL_FILE events.
AnnaBridge 143:86740a56073b 265 struct
AnnaBridge 143:86740a56073b 266 {
AnnaBridge 143:86740a56073b 267 /* Currently not used. */
AnnaBridge 143:86740a56073b 268 uint16_t pages_skipped;
AnnaBridge 143:86740a56073b 269 uint16_t space_reclaimed;
AnnaBridge 143:86740a56073b 270 } gc;
AnnaBridge 143:86740a56073b 271 };
AnnaBridge 143:86740a56073b 272 } fds_evt_t;
AnnaBridge 143:86740a56073b 273
AnnaBridge 143:86740a56073b 274 #if defined(__CC_ARM)
AnnaBridge 143:86740a56073b 275 #pragma pop
AnnaBridge 143:86740a56073b 276 #elif defined(__ICCARM__)
AnnaBridge 143:86740a56073b 277 /* leave anonymous unions enabled */
AnnaBridge 143:86740a56073b 278 #elif defined(__GNUC__)
AnnaBridge 143:86740a56073b 279 /* anonymous unions are enabled by default */
AnnaBridge 143:86740a56073b 280 #endif
AnnaBridge 143:86740a56073b 281
AnnaBridge 143:86740a56073b 282
AnnaBridge 143:86740a56073b 283 /**@brief File system statistics. */
AnnaBridge 143:86740a56073b 284 typedef struct
AnnaBridge 143:86740a56073b 285 {
AnnaBridge 143:86740a56073b 286 uint16_t open_records; //!< The number of open records.
AnnaBridge 143:86740a56073b 287 uint16_t valid_records; //!< The number of valid records.
AnnaBridge 143:86740a56073b 288 uint16_t dirty_records; //!< The number of deleted ("dirty") records.
AnnaBridge 143:86740a56073b 289 uint16_t words_reserved; //!< The number of words reserved by @ref fds_reserve().
AnnaBridge 143:86740a56073b 290
AnnaBridge 143:86740a56073b 291 /**@brief The number of words written to flash, including those reserved for future writes.
AnnaBridge 143:86740a56073b 292 */
AnnaBridge 143:86740a56073b 293 uint16_t words_used;
AnnaBridge 143:86740a56073b 294
AnnaBridge 143:86740a56073b 295 /**@brief The largest number of free contiguous words in the file system.
AnnaBridge 143:86740a56073b 296 *
AnnaBridge 143:86740a56073b 297 * This number determines the largest record that can be stored by FDS.
AnnaBridge 143:86740a56073b 298 * It takes into account all reservations for future writes.
AnnaBridge 143:86740a56073b 299 */
AnnaBridge 143:86740a56073b 300 uint16_t largest_contig;
AnnaBridge 143:86740a56073b 301
AnnaBridge 143:86740a56073b 302 /**@brief The largest number of words that can be reclaimed by garbage collection.
AnnaBridge 143:86740a56073b 303 *
AnnaBridge 143:86740a56073b 304 * The actual amount of space freed by garbage collection might be less than this value if
AnnaBridge 143:86740a56073b 305 * records are open while garbage collection is run.
AnnaBridge 143:86740a56073b 306 */
AnnaBridge 143:86740a56073b 307 uint16_t freeable_words;
AnnaBridge 143:86740a56073b 308 } fds_stat_t;
AnnaBridge 143:86740a56073b 309
AnnaBridge 143:86740a56073b 310
AnnaBridge 143:86740a56073b 311 /**@brief FDS event handler function prototype.
AnnaBridge 143:86740a56073b 312 *
AnnaBridge 143:86740a56073b 313 * @param p_evt The event.
AnnaBridge 143:86740a56073b 314 */
AnnaBridge 143:86740a56073b 315 typedef void (*fds_cb_t)(fds_evt_t const * const p_evt);
AnnaBridge 143:86740a56073b 316
AnnaBridge 143:86740a56073b 317
AnnaBridge 143:86740a56073b 318 /**@brief Function for registering an FDS event handler.
AnnaBridge 143:86740a56073b 319 *
AnnaBridge 143:86740a56073b 320 * The maximum amount of handlers that can be registered can be configured by changing the value
AnnaBridge 143:86740a56073b 321 * of @ref FDS_MAX_USERS in fds_config.h.
AnnaBridge 143:86740a56073b 322 *
AnnaBridge 143:86740a56073b 323 * @param[in] cb The event handler function.
AnnaBridge 143:86740a56073b 324 *
AnnaBridge 143:86740a56073b 325 * @retval FDS_SUCCESS If the event handler was registered successfully.
AnnaBridge 143:86740a56073b 326 * @retval FDS_ERR_USER_LIMIT_REACHED If the maximum number of registered callbacks is reached.
AnnaBridge 143:86740a56073b 327 */
AnnaBridge 143:86740a56073b 328 ret_code_t fds_register(fds_cb_t cb);
AnnaBridge 143:86740a56073b 329
AnnaBridge 143:86740a56073b 330
AnnaBridge 143:86740a56073b 331 /**@brief Function for initializing the module.
AnnaBridge 143:86740a56073b 332 *
AnnaBridge 143:86740a56073b 333 * This function initializes the module and installs the file system (unless it is installed
AnnaBridge 143:86740a56073b 334 * already).
AnnaBridge 143:86740a56073b 335 *
AnnaBridge 143:86740a56073b 336 * This function is asynchronous. Completion is reported through an event. Make sure to call
AnnaBridge 143:86740a56073b 337 * @ref fds_register before calling @ref fds_init so that you receive the completion event.
AnnaBridge 143:86740a56073b 338 *
AnnaBridge 143:86740a56073b 339 * @retval FDS_SUCCESS If the operation was queued successfully.
AnnaBridge 143:86740a56073b 340 * @retval FDS_ERR_NO_PAGES If there is no space available in flash memory to install the
AnnaBridge 143:86740a56073b 341 * file system.
AnnaBridge 143:86740a56073b 342 */
AnnaBridge 143:86740a56073b 343 ret_code_t fds_init(void);
AnnaBridge 143:86740a56073b 344
AnnaBridge 143:86740a56073b 345
AnnaBridge 143:86740a56073b 346 /**@brief Function for writing a record to flash.
AnnaBridge 143:86740a56073b 347 *
AnnaBridge 143:86740a56073b 348 * There are no restrictions on the file ID and the record key, except that the record key must be
AnnaBridge 143:86740a56073b 349 * different from @ref FDS_RECORD_KEY_DIRTY and the file ID must be different from
AnnaBridge 143:86740a56073b 350 * @ref FDS_FILE_ID_INVALID. In particular, no restrictions are made regarding the uniqueness of
AnnaBridge 143:86740a56073b 351 * the file ID or the record key. All records with the same file ID are grouped into one file.
AnnaBridge 143:86740a56073b 352 * If no file with the specified ID exists, it is created. There can be multiple records with the
AnnaBridge 143:86740a56073b 353 * same record key in a file.
AnnaBridge 143:86740a56073b 354 *
AnnaBridge 143:86740a56073b 355 * Record data can consist of multiple chunks. The data must be aligned to a 4 byte boundary, and
AnnaBridge 143:86740a56073b 356 * because it is not buffered internally, it must be kept in memory until the callback for the
AnnaBridge 143:86740a56073b 357 * operation has been received. The length of the data must not exceed @ref FDS_VIRTUAL_PAGE_SIZE
AnnaBridge 143:86740a56073b 358 * words minus 14 bytes.
AnnaBridge 143:86740a56073b 359 *
AnnaBridge 143:86740a56073b 360 * This function is asynchronous. Completion is reported through an event that is sent to
AnnaBridge 143:86740a56073b 361 * the registered event handler function.
AnnaBridge 143:86740a56073b 362 *
AnnaBridge 143:86740a56073b 363 * @param[out] p_desc The descriptor of the record that was written. Pass NULL if you do not
AnnaBridge 143:86740a56073b 364 * need the descriptor.
AnnaBridge 143:86740a56073b 365 * @param[in] p_record The record to be written to flash.
AnnaBridge 143:86740a56073b 366 *
AnnaBridge 143:86740a56073b 367 * @retval FDS_SUCCESS If the operation was queued successfully.
AnnaBridge 143:86740a56073b 368 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 369 * @retval FDS_ERR_NULL_ARG If @p p_record is NULL.
AnnaBridge 143:86740a56073b 370 * @retval FDS_ERR_INVALID_ARG If the file ID or the record key is invalid.
AnnaBridge 143:86740a56073b 371 * @retval FDS_ERR_UNALIGNED_ADDR If the record data is not aligned to a 4 byte boundary.
AnnaBridge 143:86740a56073b 372 * @retval FDS_ERR_RECORD_TOO_LARGE If the record data exceeds the maximum length.
AnnaBridge 143:86740a56073b 373 * @retval FDS_ERR_NO_SPACE_IN_QUEUES If the operation queue is full or there are more record
AnnaBridge 143:86740a56073b 374 * chunks than can be buffered.
AnnaBridge 143:86740a56073b 375 * @retval FDS_ERR_NO_SPACE_IN_FLASH If there is not enough free space in flash to store the
AnnaBridge 143:86740a56073b 376 * record.
AnnaBridge 143:86740a56073b 377 */
AnnaBridge 143:86740a56073b 378 ret_code_t fds_record_write(fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 379 fds_record_t const * const p_record);
AnnaBridge 143:86740a56073b 380
AnnaBridge 143:86740a56073b 381
AnnaBridge 143:86740a56073b 382 /**@brief Function for reserving space in flash.
AnnaBridge 143:86740a56073b 383 *
AnnaBridge 143:86740a56073b 384 * This function can be used to reserve space in flash memory. To write a record into the reserved
AnnaBridge 143:86740a56073b 385 * space, use @ref fds_record_write_reserved. Alternatively, use @ref fds_reserve_cancel to cancel
AnnaBridge 143:86740a56073b 386 * a reservation.
AnnaBridge 143:86740a56073b 387 *
AnnaBridge 143:86740a56073b 388 * Note that this function does not write any data to flash.
AnnaBridge 143:86740a56073b 389 *
AnnaBridge 143:86740a56073b 390 * @param[out] p_token A token that can be used to write a record in the reserved space or
AnnaBridge 143:86740a56073b 391 * cancel the reservation.
AnnaBridge 143:86740a56073b 392 * @param[in] length_words The length of the record data (in 4-byte words).
AnnaBridge 143:86740a56073b 393 *
AnnaBridge 143:86740a56073b 394 * @retval FDS_SUCCESS If the flash space was reserved successfully.
AnnaBridge 143:86740a56073b 395 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 396 * @retval FDS_ERR_NULL_ARG If @p p_token is NULL instead of a valid token address.
AnnaBridge 143:86740a56073b 397 * @retval FDS_ERR_RECORD_TOO_LARGE If the record length exceeds the maximum length.
AnnaBridge 143:86740a56073b 398 * @retval FDS_ERR_NO_SPACE_IN_FLASH If there is not enough free space in flash to store the
AnnaBridge 143:86740a56073b 399 * record.
AnnaBridge 143:86740a56073b 400 */
AnnaBridge 143:86740a56073b 401 ret_code_t fds_reserve(fds_reserve_token_t * const p_token, uint16_t length_words);
AnnaBridge 143:86740a56073b 402
AnnaBridge 143:86740a56073b 403
AnnaBridge 143:86740a56073b 404 /**@brief Function for canceling an @ref fds_reserve operation.
AnnaBridge 143:86740a56073b 405 *
AnnaBridge 143:86740a56073b 406 * @param[in] p_token The token that identifies the reservation, produced by @ref fds_reserve.
AnnaBridge 143:86740a56073b 407 *
AnnaBridge 143:86740a56073b 408 * @retval FDS_SUCCESS If the reservation was canceled.
AnnaBridge 143:86740a56073b 409 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 410 * @retval FDS_ERR_NULL_ARG If @p p_token is NULL instead of a valid token address.
AnnaBridge 143:86740a56073b 411 * @retval FDS_ERR_INVALID_ARG If @p p_token contains invalid data.
AnnaBridge 143:86740a56073b 412 */
AnnaBridge 143:86740a56073b 413 ret_code_t fds_reserve_cancel(fds_reserve_token_t * const p_token);
AnnaBridge 143:86740a56073b 414
AnnaBridge 143:86740a56073b 415
AnnaBridge 143:86740a56073b 416 /**@brief Function for writing a record to a space in flash that was reserved using
AnnaBridge 143:86740a56073b 417 * @ref fds_reserve.
AnnaBridge 143:86740a56073b 418 *
AnnaBridge 143:86740a56073b 419 * There are no restrictions on the file ID and the record key, except that the record key must be
AnnaBridge 143:86740a56073b 420 * different from @ref FDS_RECORD_KEY_DIRTY and the file ID must be different from
AnnaBridge 143:86740a56073b 421 * @ref FDS_FILE_ID_INVALID. In particular, no restrictions are made regarding the uniqueness of
AnnaBridge 143:86740a56073b 422 * the file ID or the record key. All records with the same file ID are grouped into one file.
AnnaBridge 143:86740a56073b 423 * If no file with the specified ID exists, it is created. There can be multiple records with the
AnnaBridge 143:86740a56073b 424 * same record key in a file.
AnnaBridge 143:86740a56073b 425 *
AnnaBridge 143:86740a56073b 426 * Record data can consist of multiple chunks. The data must be aligned to a 4 byte boundary, and
AnnaBridge 143:86740a56073b 427 * because it is not buffered internally, it must be kept in memory until the callback for the
AnnaBridge 143:86740a56073b 428 * operation has been received. The length of the data must not exceed @ref FDS_VIRTUAL_PAGE_SIZE
AnnaBridge 143:86740a56073b 429 * words minus 14 bytes.
AnnaBridge 143:86740a56073b 430 *
AnnaBridge 143:86740a56073b 431 * This function is asynchronous. Completion is reported through an event that is sent to the
AnnaBridge 143:86740a56073b 432 * registered event handler function.
AnnaBridge 143:86740a56073b 433 *
AnnaBridge 143:86740a56073b 434 * @note
AnnaBridge 143:86740a56073b 435 * This function behaves similarly to @ref fds_record_write, with the exception that it never
AnnaBridge 143:86740a56073b 436 * fails with the error @ref FDS_ERR_NO_SPACE_IN_FLASH.
AnnaBridge 143:86740a56073b 437 *
AnnaBridge 143:86740a56073b 438 * @param[out] p_desc The descriptor of the record that was written. Pass NULL if you do not
AnnaBridge 143:86740a56073b 439 * need the descriptor.
AnnaBridge 143:86740a56073b 440 * @param[in] p_record The record to be written to flash.
AnnaBridge 143:86740a56073b 441 * @param[in] p_token The token that identifies the space reserved in flash.
AnnaBridge 143:86740a56073b 442 *
AnnaBridge 143:86740a56073b 443 * @retval FDS_SUCCESS If the operation was queued successfully.
AnnaBridge 143:86740a56073b 444 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 445 * @retval FDS_ERR_NULL_ARG If @p p_token is NULL instead of a valid token address.
AnnaBridge 143:86740a56073b 446 * @retval FDS_ERR_INVALID_ARG If the file ID or the record key is invalid.
AnnaBridge 143:86740a56073b 447 * @retval FDS_ERR_UNALIGNED_ADDR If the record data is not aligned to a 4 byte boundary.
AnnaBridge 143:86740a56073b 448 * @retval FDS_ERR_RECORD_TOO_LARGE If the record data exceeds the maximum length.
AnnaBridge 143:86740a56073b 449 * @retval FDS_ERR_NO_SPACE_IN_QUEUES If the operation queue is full or there are more record
AnnaBridge 143:86740a56073b 450 * chunks than can be buffered.
AnnaBridge 143:86740a56073b 451 */
AnnaBridge 143:86740a56073b 452 ret_code_t fds_record_write_reserved(fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 453 fds_record_t const * const p_record,
AnnaBridge 143:86740a56073b 454 fds_reserve_token_t const * const p_token);
AnnaBridge 143:86740a56073b 455
AnnaBridge 143:86740a56073b 456
AnnaBridge 143:86740a56073b 457 /**@brief Function for deleting a record.
AnnaBridge 143:86740a56073b 458 *
AnnaBridge 143:86740a56073b 459 * Deleted records cannot be located using @ref fds_record_find, @ref fds_record_find_by_key, or
AnnaBridge 143:86740a56073b 460 * @ref fds_record_find_in_file. Additionally, they can no longer be opened using
AnnaBridge 143:86740a56073b 461 * @ref fds_record_open.
AnnaBridge 143:86740a56073b 462 *
AnnaBridge 143:86740a56073b 463 * Note that deleting a record does not free the space it occupies in flash memory.
AnnaBridge 143:86740a56073b 464 * To reclaim flash space used by deleted records, call @ref fds_gc to run garbage collection.
AnnaBridge 143:86740a56073b 465 *
AnnaBridge 143:86740a56073b 466 * This function is asynchronous. Completion is reported through an event that is sent to the
AnnaBridge 143:86740a56073b 467 * registered event handler function.
AnnaBridge 143:86740a56073b 468 *
AnnaBridge 143:86740a56073b 469 * @param[in] p_desc The descriptor of the record that should be deleted.
AnnaBridge 143:86740a56073b 470 *
AnnaBridge 143:86740a56073b 471 * @retval FDS_SUCCESS If the operation was queued successfully.
AnnaBridge 143:86740a56073b 472 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 473 * @retval FDS_ERR_NULL_ARG If the specified record descriptor @p p_desc is NULL.
AnnaBridge 143:86740a56073b 474 * @retval FDS_ERR_NO_SPACE_IN_QUEUES If the operation queue is full.
AnnaBridge 143:86740a56073b 475 */
AnnaBridge 143:86740a56073b 476 ret_code_t fds_record_delete(fds_record_desc_t * const p_desc);
AnnaBridge 143:86740a56073b 477
AnnaBridge 143:86740a56073b 478
AnnaBridge 143:86740a56073b 479 /**@brief Function for deleting all records in a file.
AnnaBridge 143:86740a56073b 480 *
AnnaBridge 143:86740a56073b 481 * This function deletes a file, including all its records. Deleted records cannot be located
AnnaBridge 143:86740a56073b 482 * using @ref fds_record_find, @ref fds_record_find_by_key, or @ref fds_record_find_in_file.
AnnaBridge 143:86740a56073b 483 * Additionally, they can no longer be opened using @ref fds_record_open.
AnnaBridge 143:86740a56073b 484 *
AnnaBridge 143:86740a56073b 485 * Note that deleting records does not free the space they occupy in flash memory.
AnnaBridge 143:86740a56073b 486 * To reclaim flash space used by deleted records, call @ref fds_gc to run garbage collection.
AnnaBridge 143:86740a56073b 487 *
AnnaBridge 143:86740a56073b 488 * This function is asynchronous. Completion is reported through an event that is sent to the
AnnaBridge 143:86740a56073b 489 * registered event handler function.
AnnaBridge 143:86740a56073b 490 *
AnnaBridge 143:86740a56073b 491 * @param[in] file_id The ID of the file to be deleted.
AnnaBridge 143:86740a56073b 492 *
AnnaBridge 143:86740a56073b 493 * @retval FDS_SUCCESS If the operation was queued successfully.
AnnaBridge 143:86740a56073b 494 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 495 * @retval FDS_ERR_INVALID_ARG If the specified @p file_id is invalid.
AnnaBridge 143:86740a56073b 496 * @retval FDS_ERR_NO_SPACE_IN_QUEUES If the operation queue is full.
AnnaBridge 143:86740a56073b 497 */
AnnaBridge 143:86740a56073b 498 ret_code_t fds_file_delete(uint16_t file_id);
AnnaBridge 143:86740a56073b 499
AnnaBridge 143:86740a56073b 500
AnnaBridge 143:86740a56073b 501 /**@brief Function for updating a record.
AnnaBridge 143:86740a56073b 502 *
AnnaBridge 143:86740a56073b 503 * Updating a record first writes a new record (@p p_record) to flash and then deletes the
AnnaBridge 143:86740a56073b 504 * old record (identified by @p p_desc).
AnnaBridge 143:86740a56073b 505 *
AnnaBridge 143:86740a56073b 506 * There are no restrictions on the file ID and the record key, except that the record key must be
AnnaBridge 143:86740a56073b 507 * different from @ref FDS_RECORD_KEY_DIRTY and the file ID must be different from
AnnaBridge 143:86740a56073b 508 * @ref FDS_FILE_ID_INVALID. In particular, no restrictions are made regarding the uniqueness of
AnnaBridge 143:86740a56073b 509 * the file ID or the record key. All records with the same file ID are grouped into one file.
AnnaBridge 143:86740a56073b 510 * If no file with the specified ID exists, it is created. There can be multiple records with the
AnnaBridge 143:86740a56073b 511 * same record key in a file.
AnnaBridge 143:86740a56073b 512 *
AnnaBridge 143:86740a56073b 513 * Record data can consist of multiple chunks. The data must be aligned to a 4 byte boundary, and
AnnaBridge 143:86740a56073b 514 * because it is not buffered internally, it must be kept in memory until the callback for the
AnnaBridge 143:86740a56073b 515 * operation has been received. The length of the data must not exceed @ref FDS_VIRTUAL_PAGE_SIZE
AnnaBridge 143:86740a56073b 516 * words minus 14 bytes.
AnnaBridge 143:86740a56073b 517 *
AnnaBridge 143:86740a56073b 518 * This function is asynchronous. Completion is reported through an event that is sent to the
AnnaBridge 143:86740a56073b 519 * registered event handler function.
AnnaBridge 143:86740a56073b 520 *
AnnaBridge 143:86740a56073b 521 * @param[in, out] p_desc The descriptor of the record to update. When the function
AnnaBridge 143:86740a56073b 522 * returns with FDS_SUCCESS, this parameter contains the
AnnaBridge 143:86740a56073b 523 * descriptor of the newly written record.
AnnaBridge 143:86740a56073b 524 * @param[in] p_record The updated record to be written to flash.
AnnaBridge 143:86740a56073b 525 *
AnnaBridge 143:86740a56073b 526 * @retval FDS_SUCCESS If the operation was queued successfully.
AnnaBridge 143:86740a56073b 527 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 528 * @retval FDS_ERR_INVALID_ARG If the file ID or the record key is invalid.
AnnaBridge 143:86740a56073b 529 * @retval FDS_ERR_UNALIGNED_ADDR If the record data is not aligned to a 4 byte boundary.
AnnaBridge 143:86740a56073b 530 * @retval FDS_ERR_RECORD_TOO_LARGE If the record data exceeds the maximum length.
AnnaBridge 143:86740a56073b 531 * @retval FDS_ERR_NO_SPACE_IN_QUEUES If the operation queue is full or there are more record
AnnaBridge 143:86740a56073b 532 * chunks than can be buffered.
AnnaBridge 143:86740a56073b 533 * @retval FDS_ERR_NO_SPACE_IN_FLASH If there is not enough free space in flash to store the
AnnaBridge 143:86740a56073b 534 * updated record.
AnnaBridge 143:86740a56073b 535 */
AnnaBridge 143:86740a56073b 536 ret_code_t fds_record_update(fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 537 fds_record_t const * const p_record);
AnnaBridge 143:86740a56073b 538
AnnaBridge 143:86740a56073b 539
AnnaBridge 143:86740a56073b 540 /**@brief Function for iterating through all records in flash.
AnnaBridge 143:86740a56073b 541 *
AnnaBridge 143:86740a56073b 542 * To search for the next record, call the function again and supply the same @ref fds_find_token_t
AnnaBridge 143:86740a56073b 543 * structure to resume searching from the last record that was found.
AnnaBridge 143:86740a56073b 544 *
AnnaBridge 143:86740a56073b 545 * Note that the order with which records are iterated is not defined.
AnnaBridge 143:86740a56073b 546 *
AnnaBridge 143:86740a56073b 547 * @param[out] p_desc The descriptor of the record that was found.
AnnaBridge 143:86740a56073b 548 * @param[out] p_token A token containing information about the progress of the operation.
AnnaBridge 143:86740a56073b 549 *
AnnaBridge 143:86740a56073b 550 * @retval FDS_SUCCESS If a record was found.
AnnaBridge 143:86740a56073b 551 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 552 * @retval FDS_ERR_NULL_ARG If @p p_desc or @p p_token is NULL.
AnnaBridge 143:86740a56073b 553 * @retval FDS_ERR_NOT_FOUND If no matching record was found.
AnnaBridge 143:86740a56073b 554 */
AnnaBridge 143:86740a56073b 555 ret_code_t fds_record_iterate(fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 556 fds_find_token_t * const p_token);
AnnaBridge 143:86740a56073b 557
AnnaBridge 143:86740a56073b 558
AnnaBridge 143:86740a56073b 559 /**@brief Function for searching for records with a given record key in a file.
AnnaBridge 143:86740a56073b 560 *
AnnaBridge 143:86740a56073b 561 * This function finds the first record in a file that has the given record key. To search for the
AnnaBridge 143:86740a56073b 562 * next record with the same key in the file, call the function again and supply the same
AnnaBridge 143:86740a56073b 563 * @ref fds_find_token_t structure to resume searching from the last record that was found.
AnnaBridge 143:86740a56073b 564 *
AnnaBridge 143:86740a56073b 565 * @param[in] file_id The file ID.
AnnaBridge 143:86740a56073b 566 * @param[in] record_key The record key.
AnnaBridge 143:86740a56073b 567 * @param[out] p_desc The descriptor of the record that was found.
AnnaBridge 143:86740a56073b 568 * @param[out] p_token A token containing information about the progress of the operation.
AnnaBridge 143:86740a56073b 569 *
AnnaBridge 143:86740a56073b 570 * @retval FDS_SUCCESS If a record was found.
AnnaBridge 143:86740a56073b 571 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 572 * @retval FDS_ERR_NULL_ARG If @p p_desc or @p p_token is NULL.
AnnaBridge 143:86740a56073b 573 * @retval FDS_ERR_NOT_FOUND If no matching record was found.
AnnaBridge 143:86740a56073b 574 */
AnnaBridge 143:86740a56073b 575 ret_code_t fds_record_find(uint16_t file_id,
AnnaBridge 143:86740a56073b 576 uint16_t record_key,
AnnaBridge 143:86740a56073b 577 fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 578 fds_find_token_t * const p_token);
AnnaBridge 143:86740a56073b 579
AnnaBridge 143:86740a56073b 580
AnnaBridge 143:86740a56073b 581 /**@brief Function for searching for records with a given record key.
AnnaBridge 143:86740a56073b 582 *
AnnaBridge 143:86740a56073b 583 * This function finds the first record with a given record key, independent of the file it
AnnaBridge 143:86740a56073b 584 * belongs to. To search for the next record with the same key, call the function again and supply
AnnaBridge 143:86740a56073b 585 * the same @ref fds_find_token_t structure to resume searching from the last record that was found.
AnnaBridge 143:86740a56073b 586 *
AnnaBridge 143:86740a56073b 587 * @param[in] record_key The record key.
AnnaBridge 143:86740a56073b 588 * @param[out] p_desc The descriptor of the record that was found.
AnnaBridge 143:86740a56073b 589 * @param[out] p_token A token containing information about the progress of the operation.
AnnaBridge 143:86740a56073b 590 *
AnnaBridge 143:86740a56073b 591 * @retval FDS_SUCCESS If a record was found.
AnnaBridge 143:86740a56073b 592 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 593 * @retval FDS_ERR_NULL_ARG If @p p_desc or @p p_token is NULL.
AnnaBridge 143:86740a56073b 594 * @retval FDS_ERR_NOT_FOUND If no record with the given key was found.
AnnaBridge 143:86740a56073b 595 */
AnnaBridge 143:86740a56073b 596 ret_code_t fds_record_find_by_key(uint16_t record_key,
AnnaBridge 143:86740a56073b 597 fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 598 fds_find_token_t * const p_token);
AnnaBridge 143:86740a56073b 599
AnnaBridge 143:86740a56073b 600
AnnaBridge 143:86740a56073b 601 /**@brief Function for searching for any record in a file.
AnnaBridge 143:86740a56073b 602 *
AnnaBridge 143:86740a56073b 603 * This function finds the first record in a file, independent of its record key.
AnnaBridge 143:86740a56073b 604 * To search for the next record in the same file, call the function again and supply the same
AnnaBridge 143:86740a56073b 605 * @ref fds_find_token_t structure to resume searching from the last record that was found.
AnnaBridge 143:86740a56073b 606 *
AnnaBridge 143:86740a56073b 607 * @param[in] file_id The file ID.
AnnaBridge 143:86740a56073b 608 * @param[out] p_desc The descriptor of the record that was found.
AnnaBridge 143:86740a56073b 609 * @param[out] p_token A token containing information about the progress of the operation.
AnnaBridge 143:86740a56073b 610 *
AnnaBridge 143:86740a56073b 611 * @retval FDS_SUCCESS If a record was found.
AnnaBridge 143:86740a56073b 612 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 613 * @retval FDS_ERR_NULL_ARG If @p p_desc or @p p_token is NULL.
AnnaBridge 143:86740a56073b 614 * @retval FDS_ERR_NOT_FOUND If no matching record was found.
AnnaBridge 143:86740a56073b 615 */
AnnaBridge 143:86740a56073b 616 ret_code_t fds_record_find_in_file(uint16_t file_id,
AnnaBridge 143:86740a56073b 617 fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 618 fds_find_token_t * const p_token);
AnnaBridge 143:86740a56073b 619
AnnaBridge 143:86740a56073b 620
AnnaBridge 143:86740a56073b 621 /**@brief Function for opening a record for reading.
AnnaBridge 143:86740a56073b 622 *
AnnaBridge 143:86740a56073b 623 * This function opens a record that is stored in flash, so that it can be read. The function
AnnaBridge 143:86740a56073b 624 * initializes an @ref fds_flash_record_t structure, which can be used to access the record data as
AnnaBridge 143:86740a56073b 625 * well as its associated metadata. The pointers provided in the @ref fds_flash_record_t structure
AnnaBridge 143:86740a56073b 626 * are pointers to flash memory.
AnnaBridge 143:86740a56073b 627 *
AnnaBridge 143:86740a56073b 628 * Opening a record with @ref fds_record_open prevents garbage collection to run on the virtual
AnnaBridge 143:86740a56073b 629 * flash page in which record is stored, so that the contents of the memory pointed by fields in
AnnaBridge 143:86740a56073b 630 * @ref fds_flash_record_t are guaranteed to remain unmodified as long as the record is kept open.
AnnaBridge 143:86740a56073b 631 *
AnnaBridge 143:86740a56073b 632 * When you are done reading a record, call @ref fds_record_close to close it. Garbage collection
AnnaBridge 143:86740a56073b 633 * can then reclaim space on the virtual page where the record is stored. Note that you must
AnnaBridge 143:86740a56073b 634 * provide the same descriptor for @ref fds_record_close as you did for this function.
AnnaBridge 143:86740a56073b 635 *
AnnaBridge 143:86740a56073b 636 * @param[in] p_desc The descriptor of the record to open.
AnnaBridge 143:86740a56073b 637 * @param[out] p_flash_record The record, as stored in flash.
AnnaBridge 143:86740a56073b 638 *
AnnaBridge 143:86740a56073b 639 * @retval FDS_SUCCESS If the record was opened successfully.
AnnaBridge 143:86740a56073b 640 * @retval FDS_ERR_NULL_ARG If @p p_desc or @p p_flash_record is NULL.
AnnaBridge 143:86740a56073b 641 * @retval FDS_ERR_NOT_FOUND If the record was not found. It might have been deleted, or
AnnaBridge 143:86740a56073b 642 * it might not have been written yet.
AnnaBridge 143:86740a56073b 643 * @retval FDS_ERR_CRC_CHECK_FAILED If the CRC check for the record failed.
AnnaBridge 143:86740a56073b 644 */
AnnaBridge 143:86740a56073b 645 ret_code_t fds_record_open(fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 646 fds_flash_record_t * const p_flash_record);
AnnaBridge 143:86740a56073b 647
AnnaBridge 143:86740a56073b 648
AnnaBridge 143:86740a56073b 649 /**@brief Function for closing a record.
AnnaBridge 143:86740a56073b 650 *
AnnaBridge 143:86740a56073b 651 * Closing a record allows garbage collection to run on the virtual page in which the record is
AnnaBridge 143:86740a56073b 652 * stored (if no other records remain open on that page). The descriptor passed as an argument
AnnaBridge 143:86740a56073b 653 * must be the same as the one used to open the record using @ref fds_record_open.
AnnaBridge 143:86740a56073b 654 *
AnnaBridge 143:86740a56073b 655 * Note that closing a record does not invalidate its descriptor. You can still supply the
AnnaBridge 143:86740a56073b 656 * descriptor to all functions that accept a record descriptor as a parameter.
AnnaBridge 143:86740a56073b 657 *
AnnaBridge 143:86740a56073b 658 * @param[in] p_desc The descriptor of the record to close.
AnnaBridge 143:86740a56073b 659 *
AnnaBridge 143:86740a56073b 660 * @retval FDS_SUCCESS If the record was closed successfully.
AnnaBridge 143:86740a56073b 661 * @retval FDS_ERR_NULL_ARG If @p p_desc is NULL.
AnnaBridge 143:86740a56073b 662 * @retval FDS_ERR_NO_OPEN_RECORDS If the record is not open.
AnnaBridge 143:86740a56073b 663 * @retval FDS_ERR_NOT_FOUND If the record could not be found.
AnnaBridge 143:86740a56073b 664 */
AnnaBridge 143:86740a56073b 665 ret_code_t fds_record_close(fds_record_desc_t * const p_desc);
AnnaBridge 143:86740a56073b 666
AnnaBridge 143:86740a56073b 667
AnnaBridge 143:86740a56073b 668 /**@brief Function for running garbage collection.
AnnaBridge 143:86740a56073b 669 *
AnnaBridge 143:86740a56073b 670 * Garbage collection reclaims the flash space that is occupied by records that have been deleted,
AnnaBridge 143:86740a56073b 671 * or that failed to be completely written due to, for example, a power loss.
AnnaBridge 143:86740a56073b 672 *
AnnaBridge 143:86740a56073b 673 * This function is asynchronous. Completion is reported through an event that is sent to the
AnnaBridge 143:86740a56073b 674 * registered event handler function.
AnnaBridge 143:86740a56073b 675 *
AnnaBridge 143:86740a56073b 676 * @retval FDS_SUCCESS If the operation was queued successfully.
AnnaBridge 143:86740a56073b 677 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 678 * @retval FDS_ERR_NO_SPACE_IN_QUEUES If the operation queue is full.
AnnaBridge 143:86740a56073b 679 */
AnnaBridge 143:86740a56073b 680 ret_code_t fds_gc(void);
AnnaBridge 143:86740a56073b 681
AnnaBridge 143:86740a56073b 682
AnnaBridge 143:86740a56073b 683 /**@brief Function for obtaining a descriptor from a record ID.
AnnaBridge 143:86740a56073b 684 *
AnnaBridge 143:86740a56073b 685 * This function can be used to reconstruct a descriptor from a record ID, like the one that is
AnnaBridge 143:86740a56073b 686 * passed to the callback function.
AnnaBridge 143:86740a56073b 687 *
AnnaBridge 143:86740a56073b 688 * @note
AnnaBridge 143:86740a56073b 689 * This function does not check whether a record with the given record ID exists.
AnnaBridge 143:86740a56073b 690 * If a non-existing record ID is supplied, the resulting descriptor is invalid and will cause
AnnaBridge 143:86740a56073b 691 * other functions to fail when it is supplied as parameter.
AnnaBridge 143:86740a56073b 692 *
AnnaBridge 143:86740a56073b 693 * @param[out] p_desc The descriptor of the record with the given record ID.
AnnaBridge 143:86740a56073b 694 * @param[in] record_id The record ID for which a descriptor should be returned.
AnnaBridge 143:86740a56073b 695 *
AnnaBridge 143:86740a56073b 696 * @retval FDS_SUCCESS If a descriptor was returned.
AnnaBridge 143:86740a56073b 697 * @retval FDS_ERR_NULL_ARG If @p p_desc is NULL.
AnnaBridge 143:86740a56073b 698 */
AnnaBridge 143:86740a56073b 699 ret_code_t fds_descriptor_from_rec_id(fds_record_desc_t * const p_desc,
AnnaBridge 143:86740a56073b 700 uint32_t record_id);
AnnaBridge 143:86740a56073b 701
AnnaBridge 143:86740a56073b 702
AnnaBridge 143:86740a56073b 703 /**@brief Function for obtaining a record ID from a record descriptor.
AnnaBridge 143:86740a56073b 704 *
AnnaBridge 143:86740a56073b 705 * This function can be used to extract a record ID from a descriptor. For example, you could use
AnnaBridge 143:86740a56073b 706 * it in the callback function to compare the record ID of an event to the record IDs of the
AnnaBridge 143:86740a56073b 707 * records for which you have a descriptor.
AnnaBridge 143:86740a56073b 708 *
AnnaBridge 143:86740a56073b 709 * @warning
AnnaBridge 143:86740a56073b 710 * This function does not check whether the record descriptor is valid. If the descriptor is not
AnnaBridge 143:86740a56073b 711 * initialized or has been tampered with, the resulting record ID might be invalid.
AnnaBridge 143:86740a56073b 712 *
AnnaBridge 143:86740a56073b 713 * @param[in] p_desc The descriptor from which the record ID should be extracted.
AnnaBridge 143:86740a56073b 714 * @param[out] p_record_id The record ID that is contained in the given descriptor.
AnnaBridge 143:86740a56073b 715 *
AnnaBridge 143:86740a56073b 716 * @retval FDS_SUCCESS If a record ID was returned.
AnnaBridge 143:86740a56073b 717 * @retval FDS_ERR_NULL_ARG If @p p_desc or @p p_record_id is NULL.
AnnaBridge 143:86740a56073b 718 */
AnnaBridge 143:86740a56073b 719 ret_code_t fds_record_id_from_desc(fds_record_desc_t const * const p_desc,
AnnaBridge 143:86740a56073b 720 uint32_t * const p_record_id);
AnnaBridge 143:86740a56073b 721
AnnaBridge 143:86740a56073b 722
AnnaBridge 143:86740a56073b 723 /**@brief Function for retrieving file system statistics.
AnnaBridge 143:86740a56073b 724 *
AnnaBridge 143:86740a56073b 725 * This function retrieves file system statistics, such as the number of open records, the space
AnnaBridge 143:86740a56073b 726 * that can be reclaimed by garbage collection, and others.
AnnaBridge 143:86740a56073b 727 *
AnnaBridge 143:86740a56073b 728 * @param[out] p_stat File system statistics.
AnnaBridge 143:86740a56073b 729 *
AnnaBridge 143:86740a56073b 730 * @retval FDS_SUCCESS If the statistics were returned successfully.
AnnaBridge 143:86740a56073b 731 * @retval FDS_ERR_NOT_INITIALIZED If the module is not initialized.
AnnaBridge 143:86740a56073b 732 * @retval FDS_ERR_NULL_ARG If @p p_stat is NULL.
AnnaBridge 143:86740a56073b 733 */
AnnaBridge 143:86740a56073b 734 ret_code_t fds_stat(fds_stat_t * const p_stat);
AnnaBridge 143:86740a56073b 735
AnnaBridge 143:86740a56073b 736
AnnaBridge 143:86740a56073b 737 #if defined(FDS_CRC_ENABLED)
AnnaBridge 143:86740a56073b 738
AnnaBridge 143:86740a56073b 739 /**@brief Function for enabling and disabling CRC verification for write operations.
AnnaBridge 143:86740a56073b 740 *
AnnaBridge 143:86740a56073b 741 * CRC verification ensures that data that is queued for writing does not change before the write
AnnaBridge 143:86740a56073b 742 * actually happens. Use this function to enable or disable CRC verification. If verification is
AnnaBridge 143:86740a56073b 743 * enabled, the error @ref FDS_ERR_CRC_CHECK_FAILED is returned in the event for
AnnaBridge 143:86740a56073b 744 * @ref fds_record_write, @ref fds_record_write_reserved, or @ref fds_record_update if
AnnaBridge 143:86740a56073b 745 * verification fails.
AnnaBridge 143:86740a56073b 746 *
AnnaBridge 143:86740a56073b 747 * @note
AnnaBridge 143:86740a56073b 748 * CRC verification is enabled or disabled globally, thus for all users of the FDS module.
AnnaBridge 143:86740a56073b 749 *
AnnaBridge 143:86740a56073b 750 * @param[in] enabled 1 to enable CRC verification. 0 to disable CRC verification.
AnnaBridge 143:86740a56073b 751 *
AnnaBridge 143:86740a56073b 752 * @retval FDS_SUCCESS If CRC verification was enabled or disabled successfully.
AnnaBridge 143:86740a56073b 753 */
AnnaBridge 143:86740a56073b 754 ret_code_t fds_verify_crc_on_writes(bool enabled);
AnnaBridge 143:86740a56073b 755
AnnaBridge 143:86740a56073b 756 #endif
AnnaBridge 143:86740a56073b 757
AnnaBridge 143:86740a56073b 758 /** @} */
AnnaBridge 143:86740a56073b 759
AnnaBridge 143:86740a56073b 760 #endif // FDS_H__