Renato Grottesi
Microbit as a BLE gamepad
Fork of
nrf51-sdk
by 
Lancaster University
Embed:
(wiki syntax)
Show/hide line numbers
fds.h
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 #ifndef FDS_H__ 00034 #define FDS_H__ 00035 00036 /** 00037 * @defgroup flash_data_storage Flash Data Storage 00038 * @ingroup app_common 00039 * @{ 00040 * @brief Flash Data Storage (FDS). 00041 * 00042 * @details Flash Data Storage (FDS) is a minimalistic filesystem for the on-chip flash. 00043 * It can be used to manipulate @e records, which consist of a piece of data, made up 00044 * of one or more chunks, and an associated key pair. 00045 */ 00046 00047 #include <stdint.h> 00048 #include <stdbool.h> 00049 #include "sdk_errors.h " 00050 00051 00052 /**@brief */ 00053 #define SIZEOF_WORDS(val) (sizeof(val) / 4) 00054 00055 /**@brief Reserved type key used to flag cleared records. 00056 * May not be used as a record key by the application. */ 00057 #define FDS_TYPE_ID_INVALID (0x0000) 00058 /**@brief Reserved instance key used to check for missing or corrupted metadata. 00059 * May not be used as a record key by the application. */ 00060 #define FDS_INSTANCE_ID_INVALID (0xFFFF) 00061 00062 00063 typedef uint32_t fds_record_id_t; 00064 typedef uint16_t fds_type_id_t; 00065 typedef uint16_t fds_length_t; 00066 typedef uint16_t fds_instance_id_t; 00067 typedef uint16_t fds_checksum_t; 00068 00069 00070 /**@brief A piece of a record metadata, keeping information about one of its keys (type) and its 00071 * lenght, expressed in 4 byte words. */ 00072 typedef struct 00073 { 00074 fds_type_id_t type; /**< The record type ID. */ 00075 fds_length_t length_words; /**< Length of the record's data, in 4 byte words. */ 00076 } fds_tl_t; 00077 00078 00079 /**@brief A piece of a record metadata, keeping information about one of its keys (instance) and 00080 * its checksum. */ 00081 typedef struct 00082 { 00083 fds_instance_id_t instance; /**< The record instance ID. */ 00084 fds_checksum_t checksum; /**< Checksum of the entire record, including the metadata. */ 00085 } fds_ic_t; 00086 00087 00088 /**@brief The record metadata. */ 00089 typedef struct 00090 { 00091 fds_tl_t tl; /**< See @ref fds_tl_t. */ 00092 fds_ic_t ic; /**< See @ref fds_ic_t. */ 00093 fds_record_id_t id; /**< The unique record ID (32 bits). */ 00094 } fds_header_t; 00095 00096 00097 typedef fds_header_t fds_record_header_t; 00098 00099 /**@brief The record descriptor structure, used to manipulate a record. 00100 * @note This structure is meant to be opaque to the user, who does not need to access 00101 * any of its fields. 00102 * @note This structure does not need special initialization. 00103 * @warning Do not reuse the same descriptor for different records. If you do, be sure to set 00104 * its fields to zero. */ 00105 typedef struct 00106 { 00107 uint32_t record_id; /**< The unique record ID. */ 00108 uint32_t const * p_rec; /**< The last known record address in flash. */ 00109 uint16_t vpage_id; /**< The virtual page ID in which the record is stored. */ 00110 uint16_t gc_magic; /**< Number of times the GC algorithm has been run. */ 00111 uint16_t ptr_magic; /**< Used to verify the validity of p_rec. */ 00112 } fds_record_desc_t; 00113 00114 00115 /**@brief The record key, used to lookup records. 00116 * @note The uniqueness of either field is not enforced by the system. */ 00117 typedef struct 00118 { 00119 uint16_t type; 00120 uint16_t instance; 00121 } fds_record_key_t; 00122 00123 00124 /**@brief Structure used for reading a record back from flash memory. */ 00125 typedef struct 00126 { 00127 // TODO: the header should be a pointer. 00128 fds_header_t header; /**< The record header (metadata), as stored in flash. */ 00129 uint32_t const * p_data; /**< The record data. */ 00130 } fds_record_t; 00131 00132 00133 /**@brief A record chunk, containing a piece of data to be stored in a record. 00134 * 00135 * @note p_data must be aligned on a (4 bytes) word boundary. 00136 */ 00137 typedef struct 00138 { 00139 void const * p_data; /**< Pointer to the data to store. Must be word aligned. */ 00140 fds_length_t length_words; /**< Length of data pointed by p_data, in 4 byte words. */ 00141 } fds_record_chunk_t; 00142 00143 00144 /**@brief A token to a reserved space in flash, created by @ref fds_reserve. 00145 * Use @ref fds_write_reserved to write the record in the reserved space, 00146 * or @ref fds_reserve_cancel to cancel the reservation. 00147 */ 00148 typedef struct 00149 { 00150 uint16_t vpage_id; /**< The virtual ID of the page where space was reserved. */ 00151 fds_length_t length_words; /**< The amount of space reserved, in 4 byte words. */ 00152 } fds_write_token_t; 00153 00154 00155 /**@brief A token to keep information about the progress of @ref fds_find, @ref fds_find_by_type 00156 * and @ref fds_find_by_instance operations. 00157 * @note This structure is meant to be opaque to the user, who does not need to access any of its 00158 * fields. 00159 * @note The token does not need special initialization. 00160 * @warning Do not reuse the same token to search for different records. If you do, be sure to set 00161 * its fields to zero. */ 00162 typedef struct 00163 { 00164 uint32_t const * p_addr; 00165 uint32_t magic; 00166 uint16_t vpage_id; 00167 } fds_find_token_t; 00168 00169 00170 typedef enum 00171 { 00172 FDS_CMD_NONE, /**< No command. */ 00173 FDS_CMD_INIT, /**< Module initialization commnad. Used in @ref fds_init */ 00174 FDS_CMD_WRITE, /**< Write command. Used in @ref fds_write and @ref fds_write_reserved. */ 00175 FDS_CMD_UPDATE, /**< Update command. Used in @ref fds_update. */ 00176 FDS_CMD_CLEAR, /**< Clear record command. Used in @ref fds_clear and @ref fds_update. */ 00177 FDS_CMD_CLEAR_INST, /**< Clear instance command. Used in @ref fds_clear_by_instance. */ 00178 FDS_CMD_GC /**< Garbage collection. Used in @ref fds_gc. */ 00179 } fds_cmd_id_t ; 00180 00181 00182 /**@brief Flash data storage callback function. 00183 * 00184 * @param result Result of the command. 00185 * @param cmd The command associated with the callback. 00186 * @param record_id The unique ID of the record associated with the callback. 00187 * @param record_key The key pair of the record associated with the callback. 00188 */ 00189 typedef void (*fds_cb_t)(ret_code_t result, 00190 fds_cmd_id_t cmd, 00191 fds_record_id_t record_id, 00192 fds_record_key_t record_key); 00193 00194 00195 /**@brief Function to register a callback for the module events. 00196 * @details The maximum amount of callback which can be registered can be configured by 00197 * changing the FDS_MAX_USERS macro in fds_config.h. 00198 * 00199 * @param[in] cb The callback function. 00200 * 00201 * 00202 * @retval NRF_SUCCESS Success. 00203 * @retval NRF_ERROR_NO_MEM Error. Maximum number of registered callbacks reached. 00204 */ 00205 ret_code_t fds_register(fds_cb_t cb); 00206 00207 00208 /**@brief Function to initialize the module. 00209 * 00210 * @details This function initializes the module and installs the filesystem, if it is not 00211 * installed yet. 00212 * 00213 * @note This function is asynchronous. Completion is reported with a callback through the 00214 * registered event handler. To be able to receive such callback, be sure to call 00215 * @ref fds_register before calling @ref fds_init. 00216 * 00217 * @retval NRF_SUCCESS Success. The command was queued. 00218 * @retval NRF_ERROR_INVALID_STATE Error. The module is currently undergoing initialization. 00219 * @retval NRF_ERROR_NO_MEM Error. Insufficient space to install the filesystem, or 00220 * insufficient resources to perform the installation. 00221 */ 00222 ret_code_t fds_init(void); 00223 00224 00225 /**@brief Function to write a record to flash. 00226 * 00227 * @details This function can be used to write a record to flash. A record data consists of 00228 * multiple chunks and is supplied to the function as an array of fds_record_chunk_t 00229 * structures. The maximum lenght of a record data may not exceed the size of one flash 00230 * page minus FDS_HEADER_SIZE words. 00231 * 00232 * @note This function is asynchronous, therefore, completion is reported with a callback 00233 * through the registered event handler. 00234 * 00235 * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered 00236 * internally, it must be kept in memory by the application until the callback for the 00237 * command has been received, i.e., the command completed. 00238 * 00239 * @param[out] p_desc The record descriptor. It may be NULL. 00240 * @param[in] key The record key pair. 00241 * @param[in] num_chunks The number of elements in the chunks array. 00242 * @param[in] chunks An array of chunks making up the record data. 00243 * 00244 * @retval NRF_SUCCESS Success. The command was queued. 00245 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00246 * @retval NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance. 00247 * @retval NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary. 00248 * @retval NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght. 00249 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation. 00250 * @retval NRF_ERROR_NO_MEM Error. No flash space available to store the record. 00251 */ 00252 ret_code_t fds_write(fds_record_desc_t * const p_desc, 00253 fds_record_key_t key, 00254 uint8_t num_chunks, 00255 fds_record_chunk_t chunks[]); 00256 00257 00258 /**@brief Function to reserve space for a record. 00259 * 00260 * @details This function can be used to reserve flash space to store a record, which can be 00261 * later written down using @ref fds_write_reserved. It is possible to cancel a 00262 * reservation by using @ref fds_reserve_cancel. 00263 * 00264 * @param[out] p_tok A token which can be used to write a record in the reserved space 00265 * using @ref fds_write_reserved. 00266 * @param[in] length_words The lenght of the record data, in 4 byte words. 00267 * 00268 * @retval NRF_SUCCESS Success. Flash space was successfully reserved. 00269 * @retval NRF_ERROR_NULL Error. p_tok is NULL. 00270 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00271 * @retval NRF_ERROR_NO_MEM Error. Insufficient space. 00272 */ 00273 ret_code_t fds_reserve(fds_write_token_t * const p_tok, uint16_t length_words); 00274 00275 00276 /**@brief Function to cancel a space reservation. 00277 * 00278 * @param[in] p_tok The token produced by @ref fds_reserve, identifying the reservation to cancel. 00279 * 00280 * @retval NRF_SUCCESS Success. The reservation was canceled. 00281 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00282 * @retval NRF_ERROR_NULL Error. p_tok is NULL. 00283 * @retval NRF_ERROR_INVALID_DATA Error. p_tok contains invalid data. 00284 */ 00285 ret_code_t fds_reserve_cancel(fds_write_token_t * const p_tok); 00286 00287 00288 /**@brief Function to write a record to flash, the space for which has been previously reserved 00289 * using @ref fds_reserve. 00290 * 00291 * @details This function behaves similarly to @ref fds_write, with the exception that it never 00292 * fails with NRF_ERROR_NO_MEM. 00293 * 00294 * @note This function is asynchronous, therefore, completion is reported with a callback 00295 * through the registered event handler. 00296 * 00297 * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered 00298 * internally, it must be kept in memory by the application until the callback for the 00299 * command has been received, i.e., the command completed. 00300 * 00301 * @param[in] p_tok The token return by @ref fds_reserve. 00302 * @param[out] p_desc The record descriptor. It may be NULL. 00303 * @param[in] key The record key pair. 00304 * @param[in] num_chunks The number of elements in the chunks array. 00305 * @param[in] chunks An array of chunks making up the record data. 00306 * 00307 * @retval NRF_SUCCESS Success. The command was queued. 00308 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00309 * @retval NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance. 00310 * @retval NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary. 00311 * @retval NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght. 00312 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation. 00313 */ 00314 ret_code_t fds_write_reserved(fds_write_token_t const * const p_tok, 00315 fds_record_desc_t * const p_desc, 00316 fds_record_key_t key, 00317 uint8_t num_chunks, 00318 fds_record_chunk_t chunks[]); 00319 00320 00321 /**@brief Function to clear a record. 00322 * 00323 * @details Clearing a record has the effect of preventing the system from retrieving the record 00324 * descriptor using the @ref fds_find, @ref fds_find_by_type and @ref fds_find_by_instance 00325 * functions. Additionally, @ref fds_open calls shall fail when supplied a descritpor for 00326 * a record which has been cleared. Clearing a record does not free the space it occupies 00327 * in flash. The reclaim flash space used by cleared records, use @ref fds_gc. 00328 * 00329 * @note This function is asynchronous, therefore, completion is reported with a callback 00330 * through the registered event handler. 00331 * 00332 * @param[in] p_desc The descriptor of the record to clear. 00333 * 00334 * @retval NRF_SUCCESS Success. The command was queued. 00335 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00336 * @retval NRF_ERROR_NULL Error. p_desc is NULL. 00337 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation. 00338 */ 00339 ret_code_t fds_clear(fds_record_desc_t * const p_desc); 00340 00341 00342 /**@brief Function to clear all records with a given instance. 00343 * 00344 * @details Clearing a record has the effect of preventing the system from retrieving the record 00345 * descriptor using the @ref fds_find, @ref fds_find_by_type and @ref fds_find_by_instance 00346 * functions. Additionally, @ref fds_open calls shall fail when supplied a descritpor for 00347 * a record which has been cleared. Clearing a record does not free the space it occupies 00348 * in flash. The reclaim flash space used by cleared records, use @ref fds_gc. 00349 * 00350 * @note This function is asynchronous, therefore, completion is reported with a callback 00351 * through the registered event handler. Only one callback will be issued. The record 00352 * instance ID in the key parameter of the callback will contain the instance ID passed as 00353 * parameter to this function. The record ID parameter will be zero, and the type ID equal 00354 * to FDS_TYPE_ID_INVALID. 00355 * 00356 * @param[in] instance The instance ID of the records to clear. 00357 * 00358 * @retval NRF_SUCCESS Success. The command was queued. 00359 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00360 * @retval NRF_ERROR_NULL Error. p_desc is NULL. 00361 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation. 00362 */ 00363 ret_code_t fds_clear_by_instance(fds_instance_id_t instance); 00364 00365 00366 /**@brief Function to update an existing record. 00367 * 00368 * @details Updating a record writes a new record with the given key and data in flash, and then 00369 * clears the old record. 00370 * 00371 * @note This function is asynchronous, therefore, completion is reported with a callback 00372 * through the registered event handler. Two callbacks will be issued, one to signal that 00373 * the updated record has been written down, and another to signal that the old one has been 00374 * cleared. 00375 * 00376 * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered 00377 * internally, it must be kept in memory by the application until the callback for the 00378 * command has been received, i.e., the command completed. 00379 * 00380 * @param[in, out] p_desc The descriptor of the record to update. The descriptor of the updated 00381 * record, after the function has returned with NRF_SUCCESS. 00382 * @param[in] key The record new key pair. 00383 * @param[in] num_chunks The number of elements in the chunks array. 00384 * @param[in] chunks An array of chunks making up the record new data. 00385 * 00386 * @retval NRF_SUCCESS Success. The command was queued. 00387 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00388 * @retval NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance. 00389 * @retval NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary. 00390 * @retval NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght. 00391 * @retval NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation. 00392 * @retval NRF_ERROR_NO_MEM Error. No flash space available to store the record. 00393 */ 00394 ret_code_t fds_update(fds_record_desc_t * const p_desc, 00395 fds_record_key_t key, 00396 uint8_t num_chunks, 00397 fds_record_chunk_t chunks[]); 00398 00399 00400 /**@brief Function to search for records with a given key pair. 00401 * 00402 * @details Because types are not unique, to search for the next record with the given key call 00403 * the function again and supply the same fds_find_token_t structure to resume searching 00404 * from the last record found. 00405 * 00406 * @param[in] type The record type ID. 00407 * @param[in] instance The record instance ID. 00408 * @param[out] p_desc The descriptor of the record found. 00409 * @param[out] p_token A token containing information about the progress of the operation. 00410 * 00411 * @retval NRF_SUCCESS Success. A record was found. 00412 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00413 * @retval NRF_ERROR_NULL Error. Either p_desc or p_token are NULL. 00414 * @retval NRF_ERROR_NOT_FOUND Error. No record with the given key pair was found. 00415 */ 00416 ret_code_t fds_find(fds_type_id_t type, 00417 fds_instance_id_t instance, 00418 fds_record_desc_t * const p_desc, 00419 fds_find_token_t * const p_token); 00420 00421 00422 /**@brief Function to search for records with a given type. 00423 * 00424 * @details Because types are not unique, to search for the next record with the given key call 00425 * the function again and supply the same fds_find_token_t structure to resume searching 00426 * from the last record found. 00427 * 00428 * @param[in] type The type ID in the record key. 00429 * @param[out] p_desc The descriptor of the record found. 00430 * @param[out] p_token A token containing information about the progress of the operation. 00431 * 00432 * @retval NRF_SUCCESS Success. A record was found. 00433 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00434 * @retval NRF_ERROR_NULL Error. Either p_desc or p_token are NULL. 00435 * @retval NRF_ERROR_NOT_FOUND Error. No record with the given type was found. 00436 */ 00437 ret_code_t fds_find_by_type(fds_type_id_t type, 00438 fds_record_desc_t * const p_desc, 00439 fds_find_token_t * const p_token); 00440 00441 00442 /**@brief Function to search for records with a given instance. 00443 * 00444 * @details Because types are not unique, to search for the next record with the given key call 00445 * the function again and supply the same fds_find_token_t structure to resume searching 00446 * from the last record found. 00447 * 00448 * @param[in] instance The instance ID in the record key. 00449 * @param[out] p_desc The descriptor of the record found. 00450 * @param[out] p_token A token containing information about the progress of the operation. 00451 * 00452 * @retval NRF_SUCCESS Success. A record was found. 00453 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00454 * @retval NRF_ERROR_NULL Error. Either p_desc or p_token are NULL. 00455 * @retval NRF_ERROR_NOT_FOUND Error. No record with the given instance was found. 00456 */ 00457 ret_code_t fds_find_by_instance(fds_instance_id_t instance, 00458 fds_record_desc_t * const p_desc, 00459 fds_find_token_t * const p_token); 00460 00461 00462 /**@brief Function to open a record for reading. 00463 * 00464 * @details Function to read a record which has been written to flash. This function initializes 00465 * a fds_record_t structure which can be used to access the record data as well as 00466 * its associated metadata. The pointers provided in the fds_record_t structure are 00467 * pointers to flash memory. Opening a record with @ref fds_open prevents the garbage 00468 * collection to run on the flash page in which record is stored, therefore the contents 00469 * of the memory pointed by the fds_record_t p_data field is guaranteed to remain 00470 * unmodified, as long as the record is kept open. 00471 * 00472 * @note When you are done reading a record, close it using @ref fds_close so that successive 00473 * garbage collections can reclaim space on the page where the record is stored, if necessary. 00474 * 00475 * @param[in] p_desc The descriptor of the record to open. 00476 * @param[out] p_record The record data and metadata, as stored in flash. 00477 * 00478 * @retval NRF_SUCCESS Success. The record was opened. 00479 * @retval NRF_ERROR_NOT_FOUND Error. The record was not found. It may have been cleared, or it 00480 * may have not been written yet. 00481 * @retval NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data. 00482 * @retval NRF_ERROR_NULL Error. Either p_desc or p_record are NULL. 00483 */ 00484 ret_code_t fds_open(fds_record_desc_t * const p_desc, 00485 fds_record_t * const p_record); 00486 00487 00488 /**@brief Function to close a record, after its contents have been read. 00489 * 00490 * @details Closing a record allows garbage collection to be run on the page in which the 00491 * record being closed is stored (if no other records remain open on that page). 00492 * 00493 * @note Closing a record, does NOT invalidate its descriptor, which can be safely supplied to 00494 * all functions which accept a descriptor as a parameter. 00495 * 00496 * @param[in] p_desc The descriptor of the record to close. 00497 * 00498 * @retval NRF_SUCCESS Success. The record was closed. 00499 * @retval NRF_ERROR_NULL Error. p_desc is NULL. 00500 * @retval NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data. 00501 */ 00502 ret_code_t fds_close(fds_record_desc_t const * const p_desc); 00503 00504 00505 /**@brief Function to perform a garbage collection. 00506 * 00507 * @details Garbage collection reclaims the flash space occupied by records which have been cleared 00508 * using @ref fds_clear. 00509 * 00510 * @note This function is asynchronous, therefore, completion is reported with a callback 00511 * through the registered event handler. 00512 */ 00513 ret_code_t fds_gc(void); 00514 00515 00516 /**@brief Function to compare two record descriptors. 00517 * 00518 * @param[in] p_desc_one First descriptor. 00519 * @param[in] p_desc_two Second descriptor. 00520 * 00521 * @retval true If the descriptors identify the same record. 00522 * @retval false Otherwise. 00523 */ 00524 bool fds_descriptor_match(fds_record_desc_t const * const p_desc_one, 00525 fds_record_desc_t const * const p_desc_two); 00526 00527 00528 /**@brief Function to obtain a descriptor from a record ID. 00529 * 00530 * @details This function can be used to reconstruct a descriptor from a record ID, such as the 00531 * one passed to the callback function. 00532 * 00533 * @warning This function does not check if a record with the given record ID exists or not. If a 00534 * non-existing record ID is supplied, the resulting descriptor will cause other functions 00535 * to fail when used as parameter. 00536 * 00537 * @param[out] p_desc The descriptor of the record with given record ID. 00538 * @param[in] record_id The record ID for which to provide a descriptor. 00539 * 00540 * @retval NRF_SUCCESS Success. 00541 * @retval NRF_ERROR_NULL Error. p_desc is NULL. 00542 */ 00543 ret_code_t fds_descriptor_from_rec_id(fds_record_desc_t * const p_desc, 00544 fds_record_id_t record_id); 00545 00546 /**@brief Function to obtain a record ID from a record descriptor. 00547 * 00548 * @details This function can be used to extract a record ID from a descriptor. It may be used 00549 * in the callback function to determine which record the callback is associated to, if 00550 * you have its descriptor. 00551 * 00552 * @warning This function does not check the record descriptor sanity. If the descriptor is 00553 * uninitialized, or has been tampered with, the resulting record ID may be invalid. 00554 * 00555 * @param[in] p_desc The descriptor from which to extract the record ID. 00556 * @param[out] p_record_id The record ID contained in the given descriptor. 00557 * 00558 * @retval NRF_SUCCESS Success. 00559 * @retval NRF_ERROR_NULL Error. Either p_desc is NULL or p_record_id is NULL. 00560 */ 00561 ret_code_t fds_record_id_from_desc(fds_record_desc_t const * const p_desc, 00562 fds_record_id_t * const p_record_id); 00563 00564 /** @} */ 00565 00566 #endif // FDS_H__
Generated on Tue Jul 12 2022 18:07:42 by
1.7.2