1
0

fds.h 33 KB

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