Flash Data Storage (FDS). More...
Modules | |
| Flash data storage module configuration | |
Data Structures | |
| struct | fds_header_t |
| The record metadata as stored in flash. More... | |
| struct | fds_record_desc_t |
| The record descriptor structure that is used to manipulate records. More... | |
| struct | fds_flash_record_t |
| Structure that can be used to read the contents of a record stored in flash. More... | |
| struct | fds_record_t |
| A record to be written to flash. More... | |
| struct | fds_reserve_token_t |
| A token to a reserved space in flash, created by fds_reserve. More... | |
| struct | fds_find_token_t |
| A token to keep information about the progress of fds_record_find, fds_record_find_by_key, and fds_record_find_in_file. More... | |
| struct | fds_evt_t |
| An FDS event. More... | |
| struct | fds_stat_t |
| File system statistics. More... | |
Macros | |
| #define | FDS_FILE_ID_INVALID (0xFFFF) |
| Invalid file ID. More... | |
| #define | FDS_RECORD_KEY_DIRTY (0x0000) |
| Record key for deleted records. More... | |
Typedefs | |
| typedef void(* | fds_cb_t )(fds_evt_t const *p_evt) |
| FDS event handler function prototype. More... | |
Enumerations | |
| enum | { FDS_SUCCESS = NRF_SUCCESS, FDS_ERR_OPERATION_TIMEOUT, FDS_ERR_NOT_INITIALIZED, FDS_ERR_UNALIGNED_ADDR, FDS_ERR_INVALID_ARG, FDS_ERR_NULL_ARG, FDS_ERR_NO_OPEN_RECORDS, FDS_ERR_NO_SPACE_IN_FLASH, FDS_ERR_NO_SPACE_IN_QUEUES, FDS_ERR_RECORD_TOO_LARGE, FDS_ERR_NOT_FOUND, FDS_ERR_NO_PAGES, FDS_ERR_USER_LIMIT_REACHED, FDS_ERR_CRC_CHECK_FAILED, FDS_ERR_BUSY, FDS_ERR_INTERNAL } |
| FDS return values. More... | |
| enum | fds_evt_id_t { FDS_EVT_INIT, FDS_EVT_WRITE, FDS_EVT_UPDATE, FDS_EVT_DEL_RECORD, FDS_EVT_DEL_FILE, FDS_EVT_GC } |
| FDS event IDs. More... | |
Functions | |
| ret_code_t | fds_register (fds_cb_t cb) |
| Function for registering an FDS event handler. More... | |
| ret_code_t | fds_init (void) |
| Function for initializing the module. More... | |
| ret_code_t | fds_record_write (fds_record_desc_t *p_desc, fds_record_t const *p_record) |
| Function for writing a record to flash. More... | |
| ret_code_t | fds_reserve (fds_reserve_token_t *p_token, uint16_t length_words) |
| Function for reserving space in flash. More... | |
| ret_code_t | fds_reserve_cancel (fds_reserve_token_t *p_token) |
| Function for canceling an fds_reserve operation. More... | |
| ret_code_t | fds_record_write_reserved (fds_record_desc_t *p_desc, fds_record_t const *p_record, fds_reserve_token_t const *p_token) |
| Function for writing a record to a space in flash that was reserved using fds_reserve. More... | |
| ret_code_t | fds_record_delete (fds_record_desc_t *p_desc) |
| Function for deleting a record. More... | |
| ret_code_t | fds_file_delete (uint16_t file_id) |
| Function for deleting all records in a file. More... | |
| ret_code_t | fds_record_update (fds_record_desc_t *p_desc, fds_record_t const *p_record) |
| Function for updating a record. More... | |
| ret_code_t | fds_record_iterate (fds_record_desc_t *p_desc, fds_find_token_t *p_token) |
| Function for iterating through all records in flash. More... | |
| ret_code_t | fds_record_find (uint16_t file_id, uint16_t record_key, fds_record_desc_t *p_desc, fds_find_token_t *p_token) |
| Function for searching for records with a given record key in a file. More... | |
| ret_code_t | fds_record_find_by_key (uint16_t record_key, fds_record_desc_t *p_desc, fds_find_token_t *p_token) |
| Function for searching for records with a given record key. More... | |
| ret_code_t | fds_record_find_in_file (uint16_t file_id, fds_record_desc_t *p_desc, fds_find_token_t *p_token) |
| Function for searching for any record in a file. More... | |
| ret_code_t | fds_record_open (fds_record_desc_t *p_desc, fds_flash_record_t *p_flash_record) |
| Function for opening a record for reading. More... | |
| ret_code_t | fds_record_close (fds_record_desc_t *p_desc) |
| Function for closing a record. More... | |
| ret_code_t | fds_gc (void) |
| Function for running garbage collection. More... | |
| ret_code_t | fds_descriptor_from_rec_id (fds_record_desc_t *p_desc, uint32_t record_id) |
| Function for obtaining a descriptor from a record ID. More... | |
| ret_code_t | fds_record_id_from_desc (fds_record_desc_t const *p_desc, uint32_t *p_record_id) |
| Function for obtaining a record ID from a record descriptor. More... | |
| ret_code_t | fds_stat (fds_stat_t *p_stat) |
| Function for retrieving file system statistics. More... | |
Variables | |
| ANON_UNIONS_ENABLE | |
| ANON_UNIONS_DISABLE | |
Flash Data Storage (FDS).
Flash Data Storage is a minimalistic, record-oriented file system for the on-chip flash. Files are stored as a collection of records of variable length. FDS supports synchronous read operations and asynchronous write operations (write, update, and delete). FDS can be used from multiple threads.
| #define FDS_FILE_ID_INVALID (0xFFFF) |
Invalid file ID.
This value must not be used as a file ID by the application.
| #define FDS_RECORD_KEY_DIRTY (0x0000) |
Record key for deleted records.
This key is used to flag a record as "dirty", which means that it should be removed during the next garbage collection. This value must not be used as a record key by the application.
| typedef void(* fds_cb_t)(fds_evt_t const *p_evt) |
FDS event handler function prototype.
| p_evt | The event. |
| anonymous enum |
FDS return values.
| enum fds_evt_id_t |
FDS event IDs.
| Enumerator | |
|---|---|
| FDS_EVT_INIT |
Event for fds_init. |
| FDS_EVT_WRITE |
Event for fds_record_write and fds_record_write_reserved. |
| FDS_EVT_UPDATE |
Event for fds_record_update. |
| FDS_EVT_DEL_RECORD |
Event for fds_record_delete. |
| FDS_EVT_DEL_FILE |
Event for fds_file_delete. |
| FDS_EVT_GC |
Event for fds_gc. |
| ret_code_t fds_descriptor_from_rec_id | ( | fds_record_desc_t * | p_desc, |
| uint32_t | record_id | ||
| ) |
Function for obtaining a descriptor from a record ID.
This function can be used to reconstruct a descriptor from a record ID, like the one that is passed to the callback function.
| [out] | p_desc | The descriptor of the record with the given record ID. |
| [in] | record_id | The record ID for which a descriptor should be returned. |
| FDS_SUCCESS | If a descriptor was returned. |
| FDS_ERR_NULL_ARG | If p_desc is NULL. |
| ret_code_t fds_file_delete | ( | uint16_t | file_id | ) |
Function for deleting all records in a file.
This function deletes a file, including all its records. Deleted records cannot be located using fds_record_find, fds_record_find_by_key, or fds_record_find_in_file. Additionally, they can no longer be opened using fds_record_open.
Note that deleting records does not free the space they occupy in flash memory. To reclaim flash space used by deleted records, call fds_gc to run garbage collection.
This function is asynchronous. Completion is reported through an event that is sent to the registered event handler function.
| [in] | file_id | The ID of the file to be deleted. |
| FDS_SUCCESS | If the operation was queued successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_INVALID_ARG | If the specified file_id is invalid. |
| FDS_ERR_NO_SPACE_IN_QUEUES | If the operation queue is full. |
| ret_code_t fds_gc | ( | void | ) |
Function for running garbage collection.
Garbage collection reclaims the flash space that is occupied by records that have been deleted, or that failed to be completely written due to, for example, a power loss.
This function is asynchronous. Completion is reported through an event that is sent to the registered event handler function.
| FDS_SUCCESS | If the operation was queued successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NO_SPACE_IN_QUEUES | If the operation queue is full. |
| ret_code_t fds_init | ( | void | ) |
Function for initializing the module.
This function initializes the module and installs the file system (unless it is installed already).
This function is asynchronous. Completion is reported through an event. Make sure to call fds_register before calling fds_init so that you receive the completion event.
| FDS_SUCCESS | If the operation was queued successfully. |
| FDS_ERR_NO_PAGES | If there is no space available in flash memory to install the file system. |
| ret_code_t fds_record_close | ( | fds_record_desc_t * | p_desc | ) |
Function for closing a record.
Closing a record allows garbage collection to run on the virtual page in which the record is stored (if no other records remain open on that page). The descriptor passed as an argument must be the same as the one used to open the record using fds_record_open.
Note that closing a record does not invalidate its descriptor. You can still supply the descriptor to all functions that accept a record descriptor as a parameter.
| [in] | p_desc | The descriptor of the record to close. |
| FDS_SUCCESS | If the record was closed successfully. |
| FDS_ERR_NULL_ARG | If p_desc is NULL. |
| FDS_ERR_NO_OPEN_RECORDS | If the record is not open. |
| FDS_ERR_NOT_FOUND | If the record could not be found. |
| ret_code_t fds_record_delete | ( | fds_record_desc_t * | p_desc | ) |
Function for deleting a record.
Deleted records cannot be located using fds_record_find, fds_record_find_by_key, or fds_record_find_in_file. Additionally, they can no longer be opened using fds_record_open.
Note that deleting a record does not free the space it occupies in flash memory. To reclaim flash space used by deleted records, call fds_gc to run garbage collection.
This function is asynchronous. Completion is reported through an event that is sent to the registered event handler function.
| [in] | p_desc | The descriptor of the record that should be deleted. |
| FDS_SUCCESS | If the operation was queued successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If the specified record descriptor p_desc is NULL. |
| FDS_ERR_NO_SPACE_IN_QUEUES | If the operation queue is full. |
| ret_code_t fds_record_find | ( | uint16_t | file_id, |
| uint16_t | record_key, | ||
| fds_record_desc_t * | p_desc, | ||
| fds_find_token_t * | p_token | ||
| ) |
Function for searching for records with a given record key in a file.
This function finds the first record in a file that has the given record key. To search for the next record with the same key in the file, call the function again and supply the same fds_find_token_t structure to resume searching from the last record that was found.
| [in] | file_id | The file ID. |
| [in] | record_key | The record key. |
| [out] | p_desc | The descriptor of the record that was found. |
| [out] | p_token | A token containing information about the progress of the operation. |
| FDS_SUCCESS | If a record was found. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_desc or p_token is NULL. |
| FDS_ERR_NOT_FOUND | If no matching record was found. |
| ret_code_t fds_record_find_by_key | ( | uint16_t | record_key, |
| fds_record_desc_t * | p_desc, | ||
| fds_find_token_t * | p_token | ||
| ) |
Function for searching for records with a given record key.
This function finds the first record with a given record key, independent of the file it belongs to. To search for the next record with the same key, call the function again and supply the same fds_find_token_t structure to resume searching from the last record that was found.
| [in] | record_key | The record key. |
| [out] | p_desc | The descriptor of the record that was found. |
| [out] | p_token | A token containing information about the progress of the operation. |
| FDS_SUCCESS | If a record was found. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_desc or p_token is NULL. |
| FDS_ERR_NOT_FOUND | If no record with the given key was found. |
| ret_code_t fds_record_find_in_file | ( | uint16_t | file_id, |
| fds_record_desc_t * | p_desc, | ||
| fds_find_token_t * | p_token | ||
| ) |
Function for searching for any record in a file.
This function finds the first record in a file, independent of its record key. To search for the next record in the same file, call the function again and supply the same fds_find_token_t structure to resume searching from the last record that was found.
| [in] | file_id | The file ID. |
| [out] | p_desc | The descriptor of the record that was found. |
| [out] | p_token | A token containing information about the progress of the operation. |
| FDS_SUCCESS | If a record was found. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_desc or p_token is NULL. |
| FDS_ERR_NOT_FOUND | If no matching record was found. |
| ret_code_t fds_record_id_from_desc | ( | fds_record_desc_t const * | p_desc, |
| uint32_t * | p_record_id | ||
| ) |
Function for obtaining a record ID from a record descriptor.
This function can be used to extract a record ID from a descriptor. For example, you could use it in the callback function to compare the record ID of an event to the record IDs of the records for which you have a descriptor.
| [in] | p_desc | The descriptor from which the record ID should be extracted. |
| [out] | p_record_id | The record ID that is contained in the given descriptor. |
| FDS_SUCCESS | If a record ID was returned. |
| FDS_ERR_NULL_ARG | If p_desc or p_record_id is NULL. |
| ret_code_t fds_record_iterate | ( | fds_record_desc_t * | p_desc, |
| fds_find_token_t * | p_token | ||
| ) |
Function for iterating through all records in flash.
To search for the next record, call the function again and supply the same fds_find_token_t structure to resume searching from the last record that was found.
Note that the order with which records are iterated is not defined.
| [out] | p_desc | The descriptor of the record that was found. |
| [out] | p_token | A token containing information about the progress of the operation. |
| FDS_SUCCESS | If a record was found. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_desc or p_token is NULL. |
| FDS_ERR_NOT_FOUND | If no matching record was found. |
| ret_code_t fds_record_open | ( | fds_record_desc_t * | p_desc, |
| fds_flash_record_t * | p_flash_record | ||
| ) |
Function for opening a record for reading.
This function opens a record that is stored in flash, so that it can be read. The function initializes an fds_flash_record_t structure, which can be used to access the record data as well as its associated metadata. The pointers provided in the fds_flash_record_t structure are pointers to flash memory.
Opening a record with fds_record_open prevents garbage collection to run on the virtual flash page in which record is stored, so that the contents of the memory pointed by fields in fds_flash_record_t are guaranteed to remain unmodified as long as the record is kept open.
When you are done reading a record, call fds_record_close to close it. Garbage collection can then reclaim space on the virtual page where the record is stored. Note that you must provide the same descriptor for fds_record_close as you did for this function.
| [in] | p_desc | The descriptor of the record to open. |
| [out] | p_flash_record | The record, as stored in flash. |
| FDS_SUCCESS | If the record was opened successfully. |
| FDS_ERR_NULL_ARG | If p_desc or p_flash_record is NULL. |
| FDS_ERR_NOT_FOUND | If the record was not found. It might have been deleted, or it might not have been written yet. |
| FDS_ERR_CRC_CHECK_FAILED | If the CRC check for the record failed. |
| ret_code_t fds_record_update | ( | fds_record_desc_t * | p_desc, |
| fds_record_t const * | p_record | ||
| ) |
Function for updating a record.
Updating a record first writes a new record (p_record) to flash and then deletes the old record (identified by p_desc).
There are no restrictions on the file ID and the record key, except that the record key must be different from FDS_RECORD_KEY_DIRTY and the file ID must be different from FDS_FILE_ID_INVALID. In particular, no restrictions are made regarding the uniqueness of the file ID or the record key. All records with the same file ID are grouped into one file. If no file with the specified ID exists, it is created. There can be multiple records with the same record key in a file.
Record data can consist of multiple chunks. The data must be aligned to a 4 byte boundary, and because it is not buffered internally, it must be kept in memory until the callback for the operation has been received. The length of the data must not exceed FDS_VIRTUAL_PAGE_SIZE words minus 14 bytes.
This function is asynchronous. Completion is reported through an event that is sent to the registered event handler function.
| [in,out] | p_desc | The descriptor of the record to update. When the function returns with FDS_SUCCESS, this parameter contains the descriptor of the newly written record. |
| [in] | p_record | The updated record to be written to flash. |
| FDS_SUCCESS | If the operation was queued successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_INVALID_ARG | If the file ID or the record key is invalid. |
| FDS_ERR_UNALIGNED_ADDR | If the record data is not aligned to a 4 byte boundary. |
| FDS_ERR_RECORD_TOO_LARGE | If the record data exceeds the maximum length. |
| FDS_ERR_NO_SPACE_IN_QUEUES | If the operation queue is full or there are more record chunks than can be buffered. |
| FDS_ERR_NO_SPACE_IN_FLASH | If there is not enough free space in flash to store the updated record. |
| ret_code_t fds_record_write | ( | fds_record_desc_t * | p_desc, |
| fds_record_t const * | p_record | ||
| ) |
Function for writing a record to flash.
There are no restrictions on the file ID and the record key, except that the record key must be different from FDS_RECORD_KEY_DIRTY and the file ID must be different from FDS_FILE_ID_INVALID. In particular, no restrictions are made regarding the uniqueness of the file ID or the record key. All records with the same file ID are grouped into one file. If no file with the specified ID exists, it is created. There can be multiple records with the same record key in a file.
Some modules need exclusive use of certain file IDs and record keys. See Restrictions on keys and IDs for details.
Record data can consist of multiple chunks. The data must be aligned to a 4 byte boundary, and because it is not buffered internally, it must be kept in memory until the callback for the operation has been received. The length of the data must not exceed FDS_VIRTUAL_PAGE_SIZE words minus 14 bytes.
This function is asynchronous. Completion is reported through an event that is sent to the registered event handler function.
| [out] | p_desc | The descriptor of the record that was written. Pass NULL if you do not need the descriptor. |
| [in] | p_record | The record to be written to flash. |
| FDS_SUCCESS | If the operation was queued successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_record is NULL. |
| FDS_ERR_INVALID_ARG | If the file ID or the record key is invalid. |
| FDS_ERR_UNALIGNED_ADDR | If the record data is not aligned to a 4 byte boundary. |
| FDS_ERR_RECORD_TOO_LARGE | If the record data exceeds the maximum length. |
| FDS_ERR_NO_SPACE_IN_QUEUES | If the operation queue is full or there are more record chunks than can be buffered. |
| FDS_ERR_NO_SPACE_IN_FLASH | If there is not enough free space in flash to store the record. |
| ret_code_t fds_record_write_reserved | ( | fds_record_desc_t * | p_desc, |
| fds_record_t const * | p_record, | ||
| fds_reserve_token_t const * | p_token | ||
| ) |
Function for writing a record to a space in flash that was reserved using fds_reserve.
There are no restrictions on the file ID and the record key, except that the record key must be different from FDS_RECORD_KEY_DIRTY and the file ID must be different from FDS_FILE_ID_INVALID. In particular, no restrictions are made regarding the uniqueness of the file ID or the record key. All records with the same file ID are grouped into one file. If no file with the specified ID exists, it is created. There can be multiple records with the same record key in a file.
Record data can consist of multiple chunks. The data must be aligned to a 4 byte boundary, and because it is not buffered internally, it must be kept in memory until the callback for the operation has been received. The length of the data must not exceed FDS_VIRTUAL_PAGE_SIZE words minus 14 bytes.
This function is asynchronous. Completion is reported through an event that is sent to the registered event handler function.
| [out] | p_desc | The descriptor of the record that was written. Pass NULL if you do not need the descriptor. |
| [in] | p_record | The record to be written to flash. |
| [in] | p_token | The token that identifies the space reserved in flash. |
| FDS_SUCCESS | If the operation was queued successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_token is NULL instead of a valid token address. |
| FDS_ERR_INVALID_ARG | If the file ID or the record key is invalid. |
| FDS_ERR_UNALIGNED_ADDR | If the record data is not aligned to a 4 byte boundary. |
| FDS_ERR_RECORD_TOO_LARGE | If the record data exceeds the maximum length. |
| FDS_ERR_NO_SPACE_IN_QUEUES | If the operation queue is full or there are more record chunks than can be buffered. |
| ret_code_t fds_register | ( | fds_cb_t | cb | ) |
Function for registering an FDS event handler.
The maximum amount of handlers that can be registered can be configured by changing the value of FDS_MAX_USERS in fds_config.h.
| [in] | cb | The event handler function. |
| FDS_SUCCESS | If the event handler was registered successfully. |
| FDS_ERR_USER_LIMIT_REACHED | If the maximum number of registered callbacks is reached. |
| ret_code_t fds_reserve | ( | fds_reserve_token_t * | p_token, |
| uint16_t | length_words | ||
| ) |
Function for reserving space in flash.
This function can be used to reserve space in flash memory. To write a record into the reserved space, use fds_record_write_reserved. Alternatively, use fds_reserve_cancel to cancel a reservation.
Note that this function does not write any data to flash.
| [out] | p_token | A token that can be used to write a record in the reserved space or cancel the reservation. |
| [in] | length_words | The length of the record data (in 4-byte words). |
| FDS_SUCCESS | If the flash space was reserved successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_token is NULL instead of a valid token address. |
| FDS_ERR_RECORD_TOO_LARGE | If the record length exceeds the maximum length. |
| FDS_ERR_NO_SPACE_IN_FLASH | If there is not enough free space in flash to store the record. |
| ret_code_t fds_reserve_cancel | ( | fds_reserve_token_t * | p_token | ) |
Function for canceling an fds_reserve operation.
| [in] | p_token | The token that identifies the reservation, produced by fds_reserve. |
| FDS_SUCCESS | If the reservation was canceled. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_token is NULL instead of a valid token address. |
| FDS_ERR_INVALID_ARG | If p_token contains invalid data. |
| ret_code_t fds_stat | ( | fds_stat_t * | p_stat | ) |
Function for retrieving file system statistics.
This function retrieves file system statistics, such as the number of open records, the space that can be reclaimed by garbage collection, and others.
| [out] | p_stat | File system statistics. |
| FDS_SUCCESS | If the statistics were returned successfully. |
| FDS_ERR_NOT_INITIALIZED | If the module is not initialized. |
| FDS_ERR_NULL_ARG | If p_stat is NULL. |