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