mbed official / mbed-dev

Important changes to repositories hosted on mbed.com

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

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

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

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

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

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



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

include paths in your code may need updating accordingly.

Who changed what in which revision?

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