Nordic Semiconductor / nRF51822

Nordic stack and drivers for the mbed BLE API

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate writable_gatt ... more

TARGET_MCU_NRF51822/sdk/source/libraries/fds/fds.h@638:c90ae1400bf2, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:39:43 2016 +0100
Revision:
638:c90ae1400bf2
Sync with bdab10dc0f90748b6989c8b577771bb403ca6bd8 from ARMmbed/mbed-os.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Vincent Coubard 638:c90ae1400bf2 1 /*
Vincent Coubard 638:c90ae1400bf2 2 * Copyright (c) Nordic Semiconductor ASA
Vincent Coubard 638:c90ae1400bf2 3 * All rights reserved.
Vincent Coubard 638:c90ae1400bf2 4 *
Vincent Coubard 638:c90ae1400bf2 5 * Redistribution and use in source and binary forms, with or without modification,
Vincent Coubard 638:c90ae1400bf2 6 * are permitted provided that the following conditions are met:
Vincent Coubard 638:c90ae1400bf2 7 *
Vincent Coubard 638:c90ae1400bf2 8 * 1. Redistributions of source code must retain the above copyright notice, this
Vincent Coubard 638:c90ae1400bf2 9 * list of conditions and the following disclaimer.
Vincent Coubard 638:c90ae1400bf2 10 *
Vincent Coubard 638:c90ae1400bf2 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
Vincent Coubard 638:c90ae1400bf2 12 * list of conditions and the following disclaimer in the documentation and/or
Vincent Coubard 638:c90ae1400bf2 13 * other materials provided with the distribution.
Vincent Coubard 638:c90ae1400bf2 14 *
Vincent Coubard 638:c90ae1400bf2 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
Vincent Coubard 638:c90ae1400bf2 16 * contributors to this software may be used to endorse or promote products
Vincent Coubard 638:c90ae1400bf2 17 * derived from this software without specific prior written permission.
Vincent Coubard 638:c90ae1400bf2 18 *
Vincent Coubard 638:c90ae1400bf2 19 *
Vincent Coubard 638:c90ae1400bf2 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
Vincent Coubard 638:c90ae1400bf2 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
Vincent Coubard 638:c90ae1400bf2 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
Vincent Coubard 638:c90ae1400bf2 23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
Vincent Coubard 638:c90ae1400bf2 24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
Vincent Coubard 638:c90ae1400bf2 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
Vincent Coubard 638:c90ae1400bf2 26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
Vincent Coubard 638:c90ae1400bf2 27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
Vincent Coubard 638:c90ae1400bf2 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
Vincent Coubard 638:c90ae1400bf2 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Vincent Coubard 638:c90ae1400bf2 30 *
Vincent Coubard 638:c90ae1400bf2 31 */
Vincent Coubard 638:c90ae1400bf2 32
Vincent Coubard 638:c90ae1400bf2 33 #ifndef FDS_H__
Vincent Coubard 638:c90ae1400bf2 34 #define FDS_H__
Vincent Coubard 638:c90ae1400bf2 35
Vincent Coubard 638:c90ae1400bf2 36 /**
Vincent Coubard 638:c90ae1400bf2 37 * @defgroup flash_data_storage Flash Data Storage
Vincent Coubard 638:c90ae1400bf2 38 * @ingroup app_common
Vincent Coubard 638:c90ae1400bf2 39 * @{
Vincent Coubard 638:c90ae1400bf2 40 * @brief Flash Data Storage (FDS).
Vincent Coubard 638:c90ae1400bf2 41 *
Vincent Coubard 638:c90ae1400bf2 42 * @details Flash Data Storage (FDS) is a minimalistic filesystem for the on-chip flash.
Vincent Coubard 638:c90ae1400bf2 43 * It can be used to manipulate @e records, which consist of a piece of data, made up
Vincent Coubard 638:c90ae1400bf2 44 * of one or more chunks, and an associated key pair.
Vincent Coubard 638:c90ae1400bf2 45 */
Vincent Coubard 638:c90ae1400bf2 46
Vincent Coubard 638:c90ae1400bf2 47 #include <stdint.h>
Vincent Coubard 638:c90ae1400bf2 48 #include <stdbool.h>
Vincent Coubard 638:c90ae1400bf2 49 #include "sdk_errors.h"
Vincent Coubard 638:c90ae1400bf2 50
Vincent Coubard 638:c90ae1400bf2 51
Vincent Coubard 638:c90ae1400bf2 52 /**@brief */
Vincent Coubard 638:c90ae1400bf2 53 #define SIZEOF_WORDS(val) (sizeof(val) / 4)
Vincent Coubard 638:c90ae1400bf2 54
Vincent Coubard 638:c90ae1400bf2 55 /**@brief Reserved type key used to flag cleared records.
Vincent Coubard 638:c90ae1400bf2 56 * May not be used as a record key by the application. */
Vincent Coubard 638:c90ae1400bf2 57 #define FDS_TYPE_ID_INVALID (0x0000)
Vincent Coubard 638:c90ae1400bf2 58 /**@brief Reserved instance key used to check for missing or corrupted metadata.
Vincent Coubard 638:c90ae1400bf2 59 * May not be used as a record key by the application. */
Vincent Coubard 638:c90ae1400bf2 60 #define FDS_INSTANCE_ID_INVALID (0xFFFF)
Vincent Coubard 638:c90ae1400bf2 61
Vincent Coubard 638:c90ae1400bf2 62
Vincent Coubard 638:c90ae1400bf2 63 typedef uint32_t fds_record_id_t;
Vincent Coubard 638:c90ae1400bf2 64 typedef uint16_t fds_type_id_t;
Vincent Coubard 638:c90ae1400bf2 65 typedef uint16_t fds_length_t;
Vincent Coubard 638:c90ae1400bf2 66 typedef uint16_t fds_instance_id_t;
Vincent Coubard 638:c90ae1400bf2 67 typedef uint16_t fds_checksum_t;
Vincent Coubard 638:c90ae1400bf2 68
Vincent Coubard 638:c90ae1400bf2 69
Vincent Coubard 638:c90ae1400bf2 70 /**@brief A piece of a record metadata, keeping information about one of its keys (type) and its
Vincent Coubard 638:c90ae1400bf2 71 * lenght, expressed in 4 byte words. */
Vincent Coubard 638:c90ae1400bf2 72 typedef struct
Vincent Coubard 638:c90ae1400bf2 73 {
Vincent Coubard 638:c90ae1400bf2 74 fds_type_id_t type; /**< The record type ID. */
Vincent Coubard 638:c90ae1400bf2 75 fds_length_t length_words; /**< Length of the record's data, in 4 byte words. */
Vincent Coubard 638:c90ae1400bf2 76 } fds_tl_t;
Vincent Coubard 638:c90ae1400bf2 77
Vincent Coubard 638:c90ae1400bf2 78
Vincent Coubard 638:c90ae1400bf2 79 /**@brief A piece of a record metadata, keeping information about one of its keys (instance) and
Vincent Coubard 638:c90ae1400bf2 80 * its checksum. */
Vincent Coubard 638:c90ae1400bf2 81 typedef struct
Vincent Coubard 638:c90ae1400bf2 82 {
Vincent Coubard 638:c90ae1400bf2 83 fds_instance_id_t instance; /**< The record instance ID. */
Vincent Coubard 638:c90ae1400bf2 84 fds_checksum_t checksum; /**< Checksum of the entire record, including the metadata. */
Vincent Coubard 638:c90ae1400bf2 85 } fds_ic_t;
Vincent Coubard 638:c90ae1400bf2 86
Vincent Coubard 638:c90ae1400bf2 87
Vincent Coubard 638:c90ae1400bf2 88 /**@brief The record metadata. */
Vincent Coubard 638:c90ae1400bf2 89 typedef struct
Vincent Coubard 638:c90ae1400bf2 90 {
Vincent Coubard 638:c90ae1400bf2 91 fds_tl_t tl; /**< See @ref fds_tl_t. */
Vincent Coubard 638:c90ae1400bf2 92 fds_ic_t ic; /**< See @ref fds_ic_t. */
Vincent Coubard 638:c90ae1400bf2 93 fds_record_id_t id; /**< The unique record ID (32 bits). */
Vincent Coubard 638:c90ae1400bf2 94 } fds_header_t;
Vincent Coubard 638:c90ae1400bf2 95
Vincent Coubard 638:c90ae1400bf2 96
Vincent Coubard 638:c90ae1400bf2 97 typedef fds_header_t fds_record_header_t;
Vincent Coubard 638:c90ae1400bf2 98
Vincent Coubard 638:c90ae1400bf2 99 /**@brief The record descriptor structure, used to manipulate a record.
Vincent Coubard 638:c90ae1400bf2 100 * @note This structure is meant to be opaque to the user, who does not need to access
Vincent Coubard 638:c90ae1400bf2 101 * any of its fields.
Vincent Coubard 638:c90ae1400bf2 102 * @note This structure does not need special initialization.
Vincent Coubard 638:c90ae1400bf2 103 * @warning Do not reuse the same descriptor for different records. If you do, be sure to set
Vincent Coubard 638:c90ae1400bf2 104 * its fields to zero. */
Vincent Coubard 638:c90ae1400bf2 105 typedef struct
Vincent Coubard 638:c90ae1400bf2 106 {
Vincent Coubard 638:c90ae1400bf2 107 uint32_t record_id; /**< The unique record ID. */
Vincent Coubard 638:c90ae1400bf2 108 uint32_t const * p_rec; /**< The last known record address in flash. */
Vincent Coubard 638:c90ae1400bf2 109 uint16_t vpage_id; /**< The virtual page ID in which the record is stored. */
Vincent Coubard 638:c90ae1400bf2 110 uint16_t gc_magic; /**< Number of times the GC algorithm has been run. */
Vincent Coubard 638:c90ae1400bf2 111 uint16_t ptr_magic; /**< Used to verify the validity of p_rec. */
Vincent Coubard 638:c90ae1400bf2 112 } fds_record_desc_t;
Vincent Coubard 638:c90ae1400bf2 113
Vincent Coubard 638:c90ae1400bf2 114
Vincent Coubard 638:c90ae1400bf2 115 /**@brief The record key, used to lookup records.
Vincent Coubard 638:c90ae1400bf2 116 * @note The uniqueness of either field is not enforced by the system. */
Vincent Coubard 638:c90ae1400bf2 117 typedef struct
Vincent Coubard 638:c90ae1400bf2 118 {
Vincent Coubard 638:c90ae1400bf2 119 uint16_t type;
Vincent Coubard 638:c90ae1400bf2 120 uint16_t instance;
Vincent Coubard 638:c90ae1400bf2 121 } fds_record_key_t;
Vincent Coubard 638:c90ae1400bf2 122
Vincent Coubard 638:c90ae1400bf2 123
Vincent Coubard 638:c90ae1400bf2 124 /**@brief Structure used for reading a record back from flash memory. */
Vincent Coubard 638:c90ae1400bf2 125 typedef struct
Vincent Coubard 638:c90ae1400bf2 126 {
Vincent Coubard 638:c90ae1400bf2 127 // TODO: the header should be a pointer.
Vincent Coubard 638:c90ae1400bf2 128 fds_header_t header; /**< The record header (metadata), as stored in flash. */
Vincent Coubard 638:c90ae1400bf2 129 uint32_t const * p_data; /**< The record data. */
Vincent Coubard 638:c90ae1400bf2 130 } fds_record_t;
Vincent Coubard 638:c90ae1400bf2 131
Vincent Coubard 638:c90ae1400bf2 132
Vincent Coubard 638:c90ae1400bf2 133 /**@brief A record chunk, containing a piece of data to be stored in a record.
Vincent Coubard 638:c90ae1400bf2 134 *
Vincent Coubard 638:c90ae1400bf2 135 * @note p_data must be aligned on a (4 bytes) word boundary.
Vincent Coubard 638:c90ae1400bf2 136 */
Vincent Coubard 638:c90ae1400bf2 137 typedef struct
Vincent Coubard 638:c90ae1400bf2 138 {
Vincent Coubard 638:c90ae1400bf2 139 void const * p_data; /**< Pointer to the data to store. Must be word aligned. */
Vincent Coubard 638:c90ae1400bf2 140 fds_length_t length_words; /**< Length of data pointed by p_data, in 4 byte words. */
Vincent Coubard 638:c90ae1400bf2 141 } fds_record_chunk_t;
Vincent Coubard 638:c90ae1400bf2 142
Vincent Coubard 638:c90ae1400bf2 143
Vincent Coubard 638:c90ae1400bf2 144 /**@brief A token to a reserved space in flash, created by @ref fds_reserve.
Vincent Coubard 638:c90ae1400bf2 145 * Use @ref fds_write_reserved to write the record in the reserved space,
Vincent Coubard 638:c90ae1400bf2 146 * or @ref fds_reserve_cancel to cancel the reservation.
Vincent Coubard 638:c90ae1400bf2 147 */
Vincent Coubard 638:c90ae1400bf2 148 typedef struct
Vincent Coubard 638:c90ae1400bf2 149 {
Vincent Coubard 638:c90ae1400bf2 150 uint16_t vpage_id; /**< The virtual ID of the page where space was reserved. */
Vincent Coubard 638:c90ae1400bf2 151 fds_length_t length_words; /**< The amount of space reserved, in 4 byte words. */
Vincent Coubard 638:c90ae1400bf2 152 } fds_write_token_t;
Vincent Coubard 638:c90ae1400bf2 153
Vincent Coubard 638:c90ae1400bf2 154
Vincent Coubard 638:c90ae1400bf2 155 /**@brief A token to keep information about the progress of @ref fds_find, @ref fds_find_by_type
Vincent Coubard 638:c90ae1400bf2 156 * and @ref fds_find_by_instance operations.
Vincent Coubard 638:c90ae1400bf2 157 * @note This structure is meant to be opaque to the user, who does not need to access any of its
Vincent Coubard 638:c90ae1400bf2 158 * fields.
Vincent Coubard 638:c90ae1400bf2 159 * @note The token does not need special initialization.
Vincent Coubard 638:c90ae1400bf2 160 * @warning Do not reuse the same token to search for different records. If you do, be sure to set
Vincent Coubard 638:c90ae1400bf2 161 * its fields to zero. */
Vincent Coubard 638:c90ae1400bf2 162 typedef struct
Vincent Coubard 638:c90ae1400bf2 163 {
Vincent Coubard 638:c90ae1400bf2 164 uint32_t const * p_addr;
Vincent Coubard 638:c90ae1400bf2 165 uint32_t magic;
Vincent Coubard 638:c90ae1400bf2 166 uint16_t vpage_id;
Vincent Coubard 638:c90ae1400bf2 167 } fds_find_token_t;
Vincent Coubard 638:c90ae1400bf2 168
Vincent Coubard 638:c90ae1400bf2 169
Vincent Coubard 638:c90ae1400bf2 170 typedef enum
Vincent Coubard 638:c90ae1400bf2 171 {
Vincent Coubard 638:c90ae1400bf2 172 FDS_CMD_NONE, /**< No command. */
Vincent Coubard 638:c90ae1400bf2 173 FDS_CMD_INIT, /**< Module initialization commnad. Used in @ref fds_init */
Vincent Coubard 638:c90ae1400bf2 174 FDS_CMD_WRITE, /**< Write command. Used in @ref fds_write and @ref fds_write_reserved. */
Vincent Coubard 638:c90ae1400bf2 175 FDS_CMD_UPDATE, /**< Update command. Used in @ref fds_update. */
Vincent Coubard 638:c90ae1400bf2 176 FDS_CMD_CLEAR, /**< Clear record command. Used in @ref fds_clear and @ref fds_update. */
Vincent Coubard 638:c90ae1400bf2 177 FDS_CMD_CLEAR_INST, /**< Clear instance command. Used in @ref fds_clear_by_instance. */
Vincent Coubard 638:c90ae1400bf2 178 FDS_CMD_GC /**< Garbage collection. Used in @ref fds_gc. */
Vincent Coubard 638:c90ae1400bf2 179 } fds_cmd_id_t;
Vincent Coubard 638:c90ae1400bf2 180
Vincent Coubard 638:c90ae1400bf2 181
Vincent Coubard 638:c90ae1400bf2 182 /**@brief Flash data storage callback function.
Vincent Coubard 638:c90ae1400bf2 183 *
Vincent Coubard 638:c90ae1400bf2 184 * @param result Result of the command.
Vincent Coubard 638:c90ae1400bf2 185 * @param cmd The command associated with the callback.
Vincent Coubard 638:c90ae1400bf2 186 * @param record_id The unique ID of the record associated with the callback.
Vincent Coubard 638:c90ae1400bf2 187 * @param record_key The key pair of the record associated with the callback.
Vincent Coubard 638:c90ae1400bf2 188 */
Vincent Coubard 638:c90ae1400bf2 189 typedef void (*fds_cb_t)(ret_code_t result,
Vincent Coubard 638:c90ae1400bf2 190 fds_cmd_id_t cmd,
Vincent Coubard 638:c90ae1400bf2 191 fds_record_id_t record_id,
Vincent Coubard 638:c90ae1400bf2 192 fds_record_key_t record_key);
Vincent Coubard 638:c90ae1400bf2 193
Vincent Coubard 638:c90ae1400bf2 194
Vincent Coubard 638:c90ae1400bf2 195 /**@brief Function to register a callback for the module events.
Vincent Coubard 638:c90ae1400bf2 196 * @details The maximum amount of callback which can be registered can be configured by
Vincent Coubard 638:c90ae1400bf2 197 * changing the FDS_MAX_USERS macro in fds_config.h.
Vincent Coubard 638:c90ae1400bf2 198 *
Vincent Coubard 638:c90ae1400bf2 199 * @param[in] cb The callback function.
Vincent Coubard 638:c90ae1400bf2 200 *
Vincent Coubard 638:c90ae1400bf2 201 *
Vincent Coubard 638:c90ae1400bf2 202 * @retval NRF_SUCCESS Success.
Vincent Coubard 638:c90ae1400bf2 203 * @retval NRF_ERROR_NO_MEM Error. Maximum number of registered callbacks reached.
Vincent Coubard 638:c90ae1400bf2 204 */
Vincent Coubard 638:c90ae1400bf2 205 ret_code_t fds_register(fds_cb_t cb);
Vincent Coubard 638:c90ae1400bf2 206
Vincent Coubard 638:c90ae1400bf2 207
Vincent Coubard 638:c90ae1400bf2 208 /**@brief Function to initialize the module.
Vincent Coubard 638:c90ae1400bf2 209 *
Vincent Coubard 638:c90ae1400bf2 210 * @details This function initializes the module and installs the filesystem, if it is not
Vincent Coubard 638:c90ae1400bf2 211 * installed yet.
Vincent Coubard 638:c90ae1400bf2 212 *
Vincent Coubard 638:c90ae1400bf2 213 * @note This function is asynchronous. Completion is reported with a callback through the
Vincent Coubard 638:c90ae1400bf2 214 * registered event handler. To be able to receive such callback, be sure to call
Vincent Coubard 638:c90ae1400bf2 215 * @ref fds_register before calling @ref fds_init.
Vincent Coubard 638:c90ae1400bf2 216 *
Vincent Coubard 638:c90ae1400bf2 217 * @retval NRF_SUCCESS Success. The command was queued.
Vincent Coubard 638:c90ae1400bf2 218 * @retval NRF_ERROR_INVALID_STATE Error. The module is currently undergoing initialization.
Vincent Coubard 638:c90ae1400bf2 219 * @retval NRF_ERROR_NO_MEM Error. Insufficient space to install the filesystem, or
Vincent Coubard 638:c90ae1400bf2 220 * insufficient resources to perform the installation.
Vincent Coubard 638:c90ae1400bf2 221 */
Vincent Coubard 638:c90ae1400bf2 222 ret_code_t fds_init(void);
Vincent Coubard 638:c90ae1400bf2 223
Vincent Coubard 638:c90ae1400bf2 224
Vincent Coubard 638:c90ae1400bf2 225 /**@brief Function to write a record to flash.
Vincent Coubard 638:c90ae1400bf2 226 *
Vincent Coubard 638:c90ae1400bf2 227 * @details This function can be used to write a record to flash. A record data consists of
Vincent Coubard 638:c90ae1400bf2 228 * multiple chunks and is supplied to the function as an array of fds_record_chunk_t
Vincent Coubard 638:c90ae1400bf2 229 * structures. The maximum lenght of a record data may not exceed the size of one flash
Vincent Coubard 638:c90ae1400bf2 230 * page minus FDS_HEADER_SIZE words.
Vincent Coubard 638:c90ae1400bf2 231 *
Vincent Coubard 638:c90ae1400bf2 232 * @note This function is asynchronous, therefore, completion is reported with a callback
Vincent Coubard 638:c90ae1400bf2 233 * through the registered event handler.
Vincent Coubard 638:c90ae1400bf2 234 *
Vincent Coubard 638:c90ae1400bf2 235 * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered
Vincent Coubard 638:c90ae1400bf2 236 * internally, it must be kept in memory by the application until the callback for the
Vincent Coubard 638:c90ae1400bf2 237 * command has been received, i.e., the command completed.
Vincent Coubard 638:c90ae1400bf2 238 *
Vincent Coubard 638:c90ae1400bf2 239 * @param[out] p_desc The record descriptor. It may be NULL.
Vincent Coubard 638:c90ae1400bf2 240 * @param[in] key The record key pair.
Vincent Coubard 638:c90ae1400bf2 241 * @param[in] num_chunks The number of elements in the chunks array.
Vincent Coubard 638:c90ae1400bf2 242 * @param[in] chunks An array of chunks making up the record data.
Vincent Coubard 638:c90ae1400bf2 243 *
Vincent Coubard 638:c90ae1400bf2 244 * @retval NRF_SUCCESS Success. The command was queued.
Vincent Coubard 638:c90ae1400bf2 245 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 246 * @retval NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance.
Vincent Coubard 638:c90ae1400bf2 247 * @retval NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary.
Vincent Coubard 638:c90ae1400bf2 248 * @retval NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght.
Vincent Coubard 638:c90ae1400bf2 249 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
Vincent Coubard 638:c90ae1400bf2 250 * @retval NRF_ERROR_NO_MEM Error. No flash space available to store the record.
Vincent Coubard 638:c90ae1400bf2 251 */
Vincent Coubard 638:c90ae1400bf2 252 ret_code_t fds_write(fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 253 fds_record_key_t key,
Vincent Coubard 638:c90ae1400bf2 254 uint8_t num_chunks,
Vincent Coubard 638:c90ae1400bf2 255 fds_record_chunk_t chunks[]);
Vincent Coubard 638:c90ae1400bf2 256
Vincent Coubard 638:c90ae1400bf2 257
Vincent Coubard 638:c90ae1400bf2 258 /**@brief Function to reserve space for a record.
Vincent Coubard 638:c90ae1400bf2 259 *
Vincent Coubard 638:c90ae1400bf2 260 * @details This function can be used to reserve flash space to store a record, which can be
Vincent Coubard 638:c90ae1400bf2 261 * later written down using @ref fds_write_reserved. It is possible to cancel a
Vincent Coubard 638:c90ae1400bf2 262 * reservation by using @ref fds_reserve_cancel.
Vincent Coubard 638:c90ae1400bf2 263 *
Vincent Coubard 638:c90ae1400bf2 264 * @param[out] p_tok A token which can be used to write a record in the reserved space
Vincent Coubard 638:c90ae1400bf2 265 * using @ref fds_write_reserved.
Vincent Coubard 638:c90ae1400bf2 266 * @param[in] length_words The lenght of the record data, in 4 byte words.
Vincent Coubard 638:c90ae1400bf2 267 *
Vincent Coubard 638:c90ae1400bf2 268 * @retval NRF_SUCCESS Success. Flash space was successfully reserved.
Vincent Coubard 638:c90ae1400bf2 269 * @retval NRF_ERROR_NULL Error. p_tok is NULL.
Vincent Coubard 638:c90ae1400bf2 270 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 271 * @retval NRF_ERROR_NO_MEM Error. Insufficient space.
Vincent Coubard 638:c90ae1400bf2 272 */
Vincent Coubard 638:c90ae1400bf2 273 ret_code_t fds_reserve(fds_write_token_t * const p_tok, uint16_t length_words);
Vincent Coubard 638:c90ae1400bf2 274
Vincent Coubard 638:c90ae1400bf2 275
Vincent Coubard 638:c90ae1400bf2 276 /**@brief Function to cancel a space reservation.
Vincent Coubard 638:c90ae1400bf2 277 *
Vincent Coubard 638:c90ae1400bf2 278 * @param[in] p_tok The token produced by @ref fds_reserve, identifying the reservation to cancel.
Vincent Coubard 638:c90ae1400bf2 279 *
Vincent Coubard 638:c90ae1400bf2 280 * @retval NRF_SUCCESS Success. The reservation was canceled.
Vincent Coubard 638:c90ae1400bf2 281 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 282 * @retval NRF_ERROR_NULL Error. p_tok is NULL.
Vincent Coubard 638:c90ae1400bf2 283 * @retval NRF_ERROR_INVALID_DATA Error. p_tok contains invalid data.
Vincent Coubard 638:c90ae1400bf2 284 */
Vincent Coubard 638:c90ae1400bf2 285 ret_code_t fds_reserve_cancel(fds_write_token_t * const p_tok);
Vincent Coubard 638:c90ae1400bf2 286
Vincent Coubard 638:c90ae1400bf2 287
Vincent Coubard 638:c90ae1400bf2 288 /**@brief Function to write a record to flash, the space for which has been previously reserved
Vincent Coubard 638:c90ae1400bf2 289 * using @ref fds_reserve.
Vincent Coubard 638:c90ae1400bf2 290 *
Vincent Coubard 638:c90ae1400bf2 291 * @details This function behaves similarly to @ref fds_write, with the exception that it never
Vincent Coubard 638:c90ae1400bf2 292 * fails with NRF_ERROR_NO_MEM.
Vincent Coubard 638:c90ae1400bf2 293 *
Vincent Coubard 638:c90ae1400bf2 294 * @note This function is asynchronous, therefore, completion is reported with a callback
Vincent Coubard 638:c90ae1400bf2 295 * through the registered event handler.
Vincent Coubard 638:c90ae1400bf2 296 *
Vincent Coubard 638:c90ae1400bf2 297 * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered
Vincent Coubard 638:c90ae1400bf2 298 * internally, it must be kept in memory by the application until the callback for the
Vincent Coubard 638:c90ae1400bf2 299 * command has been received, i.e., the command completed.
Vincent Coubard 638:c90ae1400bf2 300 *
Vincent Coubard 638:c90ae1400bf2 301 * @param[in] p_tok The token return by @ref fds_reserve.
Vincent Coubard 638:c90ae1400bf2 302 * @param[out] p_desc The record descriptor. It may be NULL.
Vincent Coubard 638:c90ae1400bf2 303 * @param[in] key The record key pair.
Vincent Coubard 638:c90ae1400bf2 304 * @param[in] num_chunks The number of elements in the chunks array.
Vincent Coubard 638:c90ae1400bf2 305 * @param[in] chunks An array of chunks making up the record data.
Vincent Coubard 638:c90ae1400bf2 306 *
Vincent Coubard 638:c90ae1400bf2 307 * @retval NRF_SUCCESS Success. The command was queued.
Vincent Coubard 638:c90ae1400bf2 308 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 309 * @retval NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance.
Vincent Coubard 638:c90ae1400bf2 310 * @retval NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary.
Vincent Coubard 638:c90ae1400bf2 311 * @retval NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght.
Vincent Coubard 638:c90ae1400bf2 312 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
Vincent Coubard 638:c90ae1400bf2 313 */
Vincent Coubard 638:c90ae1400bf2 314 ret_code_t fds_write_reserved(fds_write_token_t const * const p_tok,
Vincent Coubard 638:c90ae1400bf2 315 fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 316 fds_record_key_t key,
Vincent Coubard 638:c90ae1400bf2 317 uint8_t num_chunks,
Vincent Coubard 638:c90ae1400bf2 318 fds_record_chunk_t chunks[]);
Vincent Coubard 638:c90ae1400bf2 319
Vincent Coubard 638:c90ae1400bf2 320
Vincent Coubard 638:c90ae1400bf2 321 /**@brief Function to clear a record.
Vincent Coubard 638:c90ae1400bf2 322 *
Vincent Coubard 638:c90ae1400bf2 323 * @details Clearing a record has the effect of preventing the system from retrieving the record
Vincent Coubard 638:c90ae1400bf2 324 * descriptor using the @ref fds_find, @ref fds_find_by_type and @ref fds_find_by_instance
Vincent Coubard 638:c90ae1400bf2 325 * functions. Additionally, @ref fds_open calls shall fail when supplied a descritpor for
Vincent Coubard 638:c90ae1400bf2 326 * a record which has been cleared. Clearing a record does not free the space it occupies
Vincent Coubard 638:c90ae1400bf2 327 * in flash. The reclaim flash space used by cleared records, use @ref fds_gc.
Vincent Coubard 638:c90ae1400bf2 328 *
Vincent Coubard 638:c90ae1400bf2 329 * @note This function is asynchronous, therefore, completion is reported with a callback
Vincent Coubard 638:c90ae1400bf2 330 * through the registered event handler.
Vincent Coubard 638:c90ae1400bf2 331 *
Vincent Coubard 638:c90ae1400bf2 332 * @param[in] p_desc The descriptor of the record to clear.
Vincent Coubard 638:c90ae1400bf2 333 *
Vincent Coubard 638:c90ae1400bf2 334 * @retval NRF_SUCCESS Success. The command was queued.
Vincent Coubard 638:c90ae1400bf2 335 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 336 * @retval NRF_ERROR_NULL Error. p_desc is NULL.
Vincent Coubard 638:c90ae1400bf2 337 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
Vincent Coubard 638:c90ae1400bf2 338 */
Vincent Coubard 638:c90ae1400bf2 339 ret_code_t fds_clear(fds_record_desc_t * const p_desc);
Vincent Coubard 638:c90ae1400bf2 340
Vincent Coubard 638:c90ae1400bf2 341
Vincent Coubard 638:c90ae1400bf2 342 /**@brief Function to clear all records with a given instance.
Vincent Coubard 638:c90ae1400bf2 343 *
Vincent Coubard 638:c90ae1400bf2 344 * @details Clearing a record has the effect of preventing the system from retrieving the record
Vincent Coubard 638:c90ae1400bf2 345 * descriptor using the @ref fds_find, @ref fds_find_by_type and @ref fds_find_by_instance
Vincent Coubard 638:c90ae1400bf2 346 * functions. Additionally, @ref fds_open calls shall fail when supplied a descritpor for
Vincent Coubard 638:c90ae1400bf2 347 * a record which has been cleared. Clearing a record does not free the space it occupies
Vincent Coubard 638:c90ae1400bf2 348 * in flash. The reclaim flash space used by cleared records, use @ref fds_gc.
Vincent Coubard 638:c90ae1400bf2 349 *
Vincent Coubard 638:c90ae1400bf2 350 * @note This function is asynchronous, therefore, completion is reported with a callback
Vincent Coubard 638:c90ae1400bf2 351 * through the registered event handler. Only one callback will be issued. The record
Vincent Coubard 638:c90ae1400bf2 352 * instance ID in the key parameter of the callback will contain the instance ID passed as
Vincent Coubard 638:c90ae1400bf2 353 * parameter to this function. The record ID parameter will be zero, and the type ID equal
Vincent Coubard 638:c90ae1400bf2 354 * to FDS_TYPE_ID_INVALID.
Vincent Coubard 638:c90ae1400bf2 355 *
Vincent Coubard 638:c90ae1400bf2 356 * @param[in] instance The instance ID of the records to clear.
Vincent Coubard 638:c90ae1400bf2 357 *
Vincent Coubard 638:c90ae1400bf2 358 * @retval NRF_SUCCESS Success. The command was queued.
Vincent Coubard 638:c90ae1400bf2 359 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 360 * @retval NRF_ERROR_NULL Error. p_desc is NULL.
Vincent Coubard 638:c90ae1400bf2 361 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
Vincent Coubard 638:c90ae1400bf2 362 */
Vincent Coubard 638:c90ae1400bf2 363 ret_code_t fds_clear_by_instance(fds_instance_id_t instance);
Vincent Coubard 638:c90ae1400bf2 364
Vincent Coubard 638:c90ae1400bf2 365
Vincent Coubard 638:c90ae1400bf2 366 /**@brief Function to update an existing record.
Vincent Coubard 638:c90ae1400bf2 367 *
Vincent Coubard 638:c90ae1400bf2 368 * @details Updating a record writes a new record with the given key and data in flash, and then
Vincent Coubard 638:c90ae1400bf2 369 * clears the old record.
Vincent Coubard 638:c90ae1400bf2 370 *
Vincent Coubard 638:c90ae1400bf2 371 * @note This function is asynchronous, therefore, completion is reported with a callback
Vincent Coubard 638:c90ae1400bf2 372 * through the registered event handler. Two callbacks will be issued, one to signal that
Vincent Coubard 638:c90ae1400bf2 373 * the updated record has been written down, and another to signal that the old one has been
Vincent Coubard 638:c90ae1400bf2 374 * cleared.
Vincent Coubard 638:c90ae1400bf2 375 *
Vincent Coubard 638:c90ae1400bf2 376 * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered
Vincent Coubard 638:c90ae1400bf2 377 * internally, it must be kept in memory by the application until the callback for the
Vincent Coubard 638:c90ae1400bf2 378 * command has been received, i.e., the command completed.
Vincent Coubard 638:c90ae1400bf2 379 *
Vincent Coubard 638:c90ae1400bf2 380 * @param[in, out] p_desc The descriptor of the record to update. The descriptor of the updated
Vincent Coubard 638:c90ae1400bf2 381 * record, after the function has returned with NRF_SUCCESS.
Vincent Coubard 638:c90ae1400bf2 382 * @param[in] key The record new key pair.
Vincent Coubard 638:c90ae1400bf2 383 * @param[in] num_chunks The number of elements in the chunks array.
Vincent Coubard 638:c90ae1400bf2 384 * @param[in] chunks An array of chunks making up the record new data.
Vincent Coubard 638:c90ae1400bf2 385 *
Vincent Coubard 638:c90ae1400bf2 386 * @retval NRF_SUCCESS Success. The command was queued.
Vincent Coubard 638:c90ae1400bf2 387 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 388 * @retval NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance.
Vincent Coubard 638:c90ae1400bf2 389 * @retval NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary.
Vincent Coubard 638:c90ae1400bf2 390 * @retval NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght.
Vincent Coubard 638:c90ae1400bf2 391 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
Vincent Coubard 638:c90ae1400bf2 392 * @retval NRF_ERROR_NO_MEM Error. No flash space available to store the record.
Vincent Coubard 638:c90ae1400bf2 393 */
Vincent Coubard 638:c90ae1400bf2 394 ret_code_t fds_update(fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 395 fds_record_key_t key,
Vincent Coubard 638:c90ae1400bf2 396 uint8_t num_chunks,
Vincent Coubard 638:c90ae1400bf2 397 fds_record_chunk_t chunks[]);
Vincent Coubard 638:c90ae1400bf2 398
Vincent Coubard 638:c90ae1400bf2 399
Vincent Coubard 638:c90ae1400bf2 400 /**@brief Function to search for records with a given key pair.
Vincent Coubard 638:c90ae1400bf2 401 *
Vincent Coubard 638:c90ae1400bf2 402 * @details Because types are not unique, to search for the next record with the given key call
Vincent Coubard 638:c90ae1400bf2 403 * the function again and supply the same fds_find_token_t structure to resume searching
Vincent Coubard 638:c90ae1400bf2 404 * from the last record found.
Vincent Coubard 638:c90ae1400bf2 405 *
Vincent Coubard 638:c90ae1400bf2 406 * @param[in] type The record type ID.
Vincent Coubard 638:c90ae1400bf2 407 * @param[in] instance The record instance ID.
Vincent Coubard 638:c90ae1400bf2 408 * @param[out] p_desc The descriptor of the record found.
Vincent Coubard 638:c90ae1400bf2 409 * @param[out] p_token A token containing information about the progress of the operation.
Vincent Coubard 638:c90ae1400bf2 410 *
Vincent Coubard 638:c90ae1400bf2 411 * @retval NRF_SUCCESS Success. A record was found.
Vincent Coubard 638:c90ae1400bf2 412 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 413 * @retval NRF_ERROR_NULL Error. Either p_desc or p_token are NULL.
Vincent Coubard 638:c90ae1400bf2 414 * @retval NRF_ERROR_NOT_FOUND Error. No record with the given key pair was found.
Vincent Coubard 638:c90ae1400bf2 415 */
Vincent Coubard 638:c90ae1400bf2 416 ret_code_t fds_find(fds_type_id_t type,
Vincent Coubard 638:c90ae1400bf2 417 fds_instance_id_t instance,
Vincent Coubard 638:c90ae1400bf2 418 fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 419 fds_find_token_t * const p_token);
Vincent Coubard 638:c90ae1400bf2 420
Vincent Coubard 638:c90ae1400bf2 421
Vincent Coubard 638:c90ae1400bf2 422 /**@brief Function to search for records with a given type.
Vincent Coubard 638:c90ae1400bf2 423 *
Vincent Coubard 638:c90ae1400bf2 424 * @details Because types are not unique, to search for the next record with the given key call
Vincent Coubard 638:c90ae1400bf2 425 * the function again and supply the same fds_find_token_t structure to resume searching
Vincent Coubard 638:c90ae1400bf2 426 * from the last record found.
Vincent Coubard 638:c90ae1400bf2 427 *
Vincent Coubard 638:c90ae1400bf2 428 * @param[in] type The type ID in the record key.
Vincent Coubard 638:c90ae1400bf2 429 * @param[out] p_desc The descriptor of the record found.
Vincent Coubard 638:c90ae1400bf2 430 * @param[out] p_token A token containing information about the progress of the operation.
Vincent Coubard 638:c90ae1400bf2 431 *
Vincent Coubard 638:c90ae1400bf2 432 * @retval NRF_SUCCESS Success. A record was found.
Vincent Coubard 638:c90ae1400bf2 433 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 434 * @retval NRF_ERROR_NULL Error. Either p_desc or p_token are NULL.
Vincent Coubard 638:c90ae1400bf2 435 * @retval NRF_ERROR_NOT_FOUND Error. No record with the given type was found.
Vincent Coubard 638:c90ae1400bf2 436 */
Vincent Coubard 638:c90ae1400bf2 437 ret_code_t fds_find_by_type(fds_type_id_t type,
Vincent Coubard 638:c90ae1400bf2 438 fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 439 fds_find_token_t * const p_token);
Vincent Coubard 638:c90ae1400bf2 440
Vincent Coubard 638:c90ae1400bf2 441
Vincent Coubard 638:c90ae1400bf2 442 /**@brief Function to search for records with a given instance.
Vincent Coubard 638:c90ae1400bf2 443 *
Vincent Coubard 638:c90ae1400bf2 444 * @details Because types are not unique, to search for the next record with the given key call
Vincent Coubard 638:c90ae1400bf2 445 * the function again and supply the same fds_find_token_t structure to resume searching
Vincent Coubard 638:c90ae1400bf2 446 * from the last record found.
Vincent Coubard 638:c90ae1400bf2 447 *
Vincent Coubard 638:c90ae1400bf2 448 * @param[in] instance The instance ID in the record key.
Vincent Coubard 638:c90ae1400bf2 449 * @param[out] p_desc The descriptor of the record found.
Vincent Coubard 638:c90ae1400bf2 450 * @param[out] p_token A token containing information about the progress of the operation.
Vincent Coubard 638:c90ae1400bf2 451 *
Vincent Coubard 638:c90ae1400bf2 452 * @retval NRF_SUCCESS Success. A record was found.
Vincent Coubard 638:c90ae1400bf2 453 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
Vincent Coubard 638:c90ae1400bf2 454 * @retval NRF_ERROR_NULL Error. Either p_desc or p_token are NULL.
Vincent Coubard 638:c90ae1400bf2 455 * @retval NRF_ERROR_NOT_FOUND Error. No record with the given instance was found.
Vincent Coubard 638:c90ae1400bf2 456 */
Vincent Coubard 638:c90ae1400bf2 457 ret_code_t fds_find_by_instance(fds_instance_id_t instance,
Vincent Coubard 638:c90ae1400bf2 458 fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 459 fds_find_token_t * const p_token);
Vincent Coubard 638:c90ae1400bf2 460
Vincent Coubard 638:c90ae1400bf2 461
Vincent Coubard 638:c90ae1400bf2 462 /**@brief Function to open a record for reading.
Vincent Coubard 638:c90ae1400bf2 463 *
Vincent Coubard 638:c90ae1400bf2 464 * @details Function to read a record which has been written to flash. This function initializes
Vincent Coubard 638:c90ae1400bf2 465 * a fds_record_t structure which can be used to access the record data as well as
Vincent Coubard 638:c90ae1400bf2 466 * its associated metadata. The pointers provided in the fds_record_t structure are
Vincent Coubard 638:c90ae1400bf2 467 * pointers to flash memory. Opening a record with @ref fds_open prevents the garbage
Vincent Coubard 638:c90ae1400bf2 468 * collection to run on the flash page in which record is stored, therefore the contents
Vincent Coubard 638:c90ae1400bf2 469 * of the memory pointed by the fds_record_t p_data field is guaranteed to remain
Vincent Coubard 638:c90ae1400bf2 470 * unmodified, as long as the record is kept open.
Vincent Coubard 638:c90ae1400bf2 471 *
Vincent Coubard 638:c90ae1400bf2 472 * @note When you are done reading a record, close it using @ref fds_close so that successive
Vincent Coubard 638:c90ae1400bf2 473 * garbage collections can reclaim space on the page where the record is stored, if necessary.
Vincent Coubard 638:c90ae1400bf2 474 *
Vincent Coubard 638:c90ae1400bf2 475 * @param[in] p_desc The descriptor of the record to open.
Vincent Coubard 638:c90ae1400bf2 476 * @param[out] p_record The record data and metadata, as stored in flash.
Vincent Coubard 638:c90ae1400bf2 477 *
Vincent Coubard 638:c90ae1400bf2 478 * @retval NRF_SUCCESS Success. The record was opened.
Vincent Coubard 638:c90ae1400bf2 479 * @retval NRF_ERROR_NOT_FOUND Error. The record was not found. It may have been cleared, or it
Vincent Coubard 638:c90ae1400bf2 480 * may have not been written yet.
Vincent Coubard 638:c90ae1400bf2 481 * @retval NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data.
Vincent Coubard 638:c90ae1400bf2 482 * @retval NRF_ERROR_NULL Error. Either p_desc or p_record are NULL.
Vincent Coubard 638:c90ae1400bf2 483 */
Vincent Coubard 638:c90ae1400bf2 484 ret_code_t fds_open(fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 485 fds_record_t * const p_record);
Vincent Coubard 638:c90ae1400bf2 486
Vincent Coubard 638:c90ae1400bf2 487
Vincent Coubard 638:c90ae1400bf2 488 /**@brief Function to close a record, after its contents have been read.
Vincent Coubard 638:c90ae1400bf2 489 *
Vincent Coubard 638:c90ae1400bf2 490 * @details Closing a record allows garbage collection to be run on the page in which the
Vincent Coubard 638:c90ae1400bf2 491 * record being closed is stored (if no other records remain open on that page).
Vincent Coubard 638:c90ae1400bf2 492 *
Vincent Coubard 638:c90ae1400bf2 493 * @note Closing a record, does NOT invalidate its descriptor, which can be safely supplied to
Vincent Coubard 638:c90ae1400bf2 494 * all functions which accept a descriptor as a parameter.
Vincent Coubard 638:c90ae1400bf2 495 *
Vincent Coubard 638:c90ae1400bf2 496 * @param[in] p_desc The descriptor of the record to close.
Vincent Coubard 638:c90ae1400bf2 497 *
Vincent Coubard 638:c90ae1400bf2 498 * @retval NRF_SUCCESS Success. The record was closed.
Vincent Coubard 638:c90ae1400bf2 499 * @retval NRF_ERROR_NULL Error. p_desc is NULL.
Vincent Coubard 638:c90ae1400bf2 500 * @retval NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data.
Vincent Coubard 638:c90ae1400bf2 501 */
Vincent Coubard 638:c90ae1400bf2 502 ret_code_t fds_close(fds_record_desc_t const * const p_desc);
Vincent Coubard 638:c90ae1400bf2 503
Vincent Coubard 638:c90ae1400bf2 504
Vincent Coubard 638:c90ae1400bf2 505 /**@brief Function to perform a garbage collection.
Vincent Coubard 638:c90ae1400bf2 506 *
Vincent Coubard 638:c90ae1400bf2 507 * @details Garbage collection reclaims the flash space occupied by records which have been cleared
Vincent Coubard 638:c90ae1400bf2 508 * using @ref fds_clear.
Vincent Coubard 638:c90ae1400bf2 509 *
Vincent Coubard 638:c90ae1400bf2 510 * @note This function is asynchronous, therefore, completion is reported with a callback
Vincent Coubard 638:c90ae1400bf2 511 * through the registered event handler.
Vincent Coubard 638:c90ae1400bf2 512 */
Vincent Coubard 638:c90ae1400bf2 513 ret_code_t fds_gc(void);
Vincent Coubard 638:c90ae1400bf2 514
Vincent Coubard 638:c90ae1400bf2 515
Vincent Coubard 638:c90ae1400bf2 516 /**@brief Function to compare two record descriptors.
Vincent Coubard 638:c90ae1400bf2 517 *
Vincent Coubard 638:c90ae1400bf2 518 * @param[in] p_desc_one First descriptor.
Vincent Coubard 638:c90ae1400bf2 519 * @param[in] p_desc_two Second descriptor.
Vincent Coubard 638:c90ae1400bf2 520 *
Vincent Coubard 638:c90ae1400bf2 521 * @retval true If the descriptors identify the same record.
Vincent Coubard 638:c90ae1400bf2 522 * @retval false Otherwise.
Vincent Coubard 638:c90ae1400bf2 523 */
Vincent Coubard 638:c90ae1400bf2 524 bool fds_descriptor_match(fds_record_desc_t const * const p_desc_one,
Vincent Coubard 638:c90ae1400bf2 525 fds_record_desc_t const * const p_desc_two);
Vincent Coubard 638:c90ae1400bf2 526
Vincent Coubard 638:c90ae1400bf2 527
Vincent Coubard 638:c90ae1400bf2 528 /**@brief Function to obtain a descriptor from a record ID.
Vincent Coubard 638:c90ae1400bf2 529 *
Vincent Coubard 638:c90ae1400bf2 530 * @details This function can be used to reconstruct a descriptor from a record ID, such as the
Vincent Coubard 638:c90ae1400bf2 531 * one passed to the callback function.
Vincent Coubard 638:c90ae1400bf2 532 *
Vincent Coubard 638:c90ae1400bf2 533 * @warning This function does not check if a record with the given record ID exists or not. If a
Vincent Coubard 638:c90ae1400bf2 534 * non-existing record ID is supplied, the resulting descriptor will cause other functions
Vincent Coubard 638:c90ae1400bf2 535 * to fail when used as parameter.
Vincent Coubard 638:c90ae1400bf2 536 *
Vincent Coubard 638:c90ae1400bf2 537 * @param[out] p_desc The descriptor of the record with given record ID.
Vincent Coubard 638:c90ae1400bf2 538 * @param[in] record_id The record ID for which to provide a descriptor.
Vincent Coubard 638:c90ae1400bf2 539 *
Vincent Coubard 638:c90ae1400bf2 540 * @retval NRF_SUCCESS Success.
Vincent Coubard 638:c90ae1400bf2 541 * @retval NRF_ERROR_NULL Error. p_desc is NULL.
Vincent Coubard 638:c90ae1400bf2 542 */
Vincent Coubard 638:c90ae1400bf2 543 ret_code_t fds_descriptor_from_rec_id(fds_record_desc_t * const p_desc,
Vincent Coubard 638:c90ae1400bf2 544 fds_record_id_t record_id);
Vincent Coubard 638:c90ae1400bf2 545
Vincent Coubard 638:c90ae1400bf2 546 /**@brief Function to obtain a record ID from a record descriptor.
Vincent Coubard 638:c90ae1400bf2 547 *
Vincent Coubard 638:c90ae1400bf2 548 * @details This function can be used to extract a record ID from a descriptor. It may be used
Vincent Coubard 638:c90ae1400bf2 549 * in the callback function to determine which record the callback is associated to, if
Vincent Coubard 638:c90ae1400bf2 550 * you have its descriptor.
Vincent Coubard 638:c90ae1400bf2 551 *
Vincent Coubard 638:c90ae1400bf2 552 * @warning This function does not check the record descriptor sanity. If the descriptor is
Vincent Coubard 638:c90ae1400bf2 553 * uninitialized, or has been tampered with, the resulting record ID may be invalid.
Vincent Coubard 638:c90ae1400bf2 554 *
Vincent Coubard 638:c90ae1400bf2 555 * @param[in] p_desc The descriptor from which to extract the record ID.
Vincent Coubard 638:c90ae1400bf2 556 * @param[out] p_record_id The record ID contained in the given descriptor.
Vincent Coubard 638:c90ae1400bf2 557 *
Vincent Coubard 638:c90ae1400bf2 558 * @retval NRF_SUCCESS Success.
Vincent Coubard 638:c90ae1400bf2 559 * @retval NRF_ERROR_NULL Error. Either p_desc is NULL or p_record_id is NULL.
Vincent Coubard 638:c90ae1400bf2 560 */
Vincent Coubard 638:c90ae1400bf2 561 ret_code_t fds_record_id_from_desc(fds_record_desc_t const * const p_desc,
Vincent Coubard 638:c90ae1400bf2 562 fds_record_id_t * const p_record_id);
Vincent Coubard 638:c90ae1400bf2 563
Vincent Coubard 638:c90ae1400bf2 564 /** @} */
Vincent Coubard 638:c90ae1400bf2 565
Vincent Coubard 638:c90ae1400bf2 566 #endif // FDS_H__