Initial release
Fork of nrf51-sdk by
Flash Data Storage
Flash Data Storage (FDS). More...
Data Structures | |
struct | fds_tl_t |
A piece of a record metadata, keeping information about one of its keys (type) and its lenght, expressed in 4 byte words. More... | |
struct | fds_ic_t |
A piece of a record metadata, keeping information about one of its keys (instance) and its checksum. More... | |
struct | fds_header_t |
The record metadata. More... | |
struct | fds_record_desc_t |
The record descriptor structure, used to manipulate a record. More... | |
struct | fds_record_key_t |
The record key, used to lookup records. More... | |
struct | fds_record_t |
Structure used for reading a record back from flash memory. More... | |
struct | fds_record_chunk_t |
A record chunk, containing a piece of data to be stored in a record. More... | |
struct | fds_write_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_find, fds_find_by_type and fds_find_by_instance operations. More... | |
Typedefs | |
typedef void(* | fds_cb_t )(ret_code_t result, fds_cmd_id_t cmd, fds_record_id_t record_id, fds_record_key_t record_key) |
Flash data storage callback function. | |
Enumerations | |
enum | fds_cmd_id_t { FDS_CMD_NONE, FDS_CMD_INIT, FDS_CMD_WRITE, FDS_CMD_UPDATE, FDS_CMD_CLEAR, FDS_CMD_CLEAR_INST, FDS_CMD_GC } |
Functions | |
ret_code_t | fds_register (fds_cb_t cb) |
Function to register a callback for the module events. | |
ret_code_t | fds_init (void) |
Function to initialize the module. | |
ret_code_t | fds_write (fds_record_desc_t *const p_desc, fds_record_key_t key, uint8_t num_chunks, fds_record_chunk_t chunks[]) |
Function to write a record to flash. | |
ret_code_t | fds_reserve (fds_write_token_t *const p_tok, uint16_t length_words) |
Function to reserve space for a record. | |
ret_code_t | fds_reserve_cancel (fds_write_token_t *const p_tok) |
Function to cancel a space reservation. | |
ret_code_t | fds_write_reserved (fds_write_token_t const *const p_tok, fds_record_desc_t *const p_desc, fds_record_key_t key, uint8_t num_chunks, fds_record_chunk_t chunks[]) |
Function to write a record to flash, the space for which has been previously reserved using fds_reserve. | |
ret_code_t | fds_clear (fds_record_desc_t *const p_desc) |
Function to clear a record. | |
ret_code_t | fds_clear_by_instance (fds_instance_id_t instance) |
Function to clear all records with a given instance. | |
ret_code_t | fds_update (fds_record_desc_t *const p_desc, fds_record_key_t key, uint8_t num_chunks, fds_record_chunk_t chunks[]) |
Function to update an existing record. | |
ret_code_t | fds_find (fds_type_id_t type, fds_instance_id_t instance, fds_record_desc_t *const p_desc, fds_find_token_t *const p_token) |
Function to search for records with a given key pair. | |
ret_code_t | fds_find_by_type (fds_type_id_t type, fds_record_desc_t *const p_desc, fds_find_token_t *const p_token) |
Function to search for records with a given type. | |
ret_code_t | fds_find_by_instance (fds_instance_id_t instance, fds_record_desc_t *const p_desc, fds_find_token_t *const p_token) |
Function to search for records with a given instance. | |
ret_code_t | fds_open (fds_record_desc_t *const p_desc, fds_record_t *const p_record) |
Function to open a record for reading. | |
ret_code_t | fds_close (fds_record_desc_t const *const p_desc) |
Function to close a record, after its contents have been read. | |
ret_code_t | fds_gc (void) |
Function to perform a garbage collection. | |
bool | fds_descriptor_match (fds_record_desc_t const *const p_desc_one, fds_record_desc_t const *const p_desc_two) |
Function to compare two record descriptors. | |
ret_code_t | fds_descriptor_from_rec_id (fds_record_desc_t *const p_desc, fds_record_id_t record_id) |
Function to obtain a descriptor from a record ID. | |
ret_code_t | fds_record_id_from_desc (fds_record_desc_t const *const p_desc, fds_record_id_t *const p_record_id) |
Function to obtain a record ID from a record descriptor. |
Detailed Description
Flash Data Storage (FDS).
Flash Data Storage (FDS) is a minimalistic filesystem for the on-chip flash. It can be used to manipulate records, which consist of a piece of data, made up of one or more chunks, and an associated key pair.
Typedef Documentation
typedef void(* fds_cb_t)(ret_code_t result, fds_cmd_id_t cmd, fds_record_id_t record_id, fds_record_key_t record_key) |
Enumeration Type Documentation
enum fds_cmd_id_t |
- Enumerator:
FDS_CMD_NONE No command.
FDS_CMD_INIT Module initialization commnad.
Used in fds_init
FDS_CMD_WRITE Write command.
Used in fds_write and fds_write_reserved.
FDS_CMD_UPDATE Update command.
Used in fds_update.
FDS_CMD_CLEAR Clear record command.
Used in fds_clear and fds_update.
FDS_CMD_CLEAR_INST Clear instance command.
Used in fds_clear_by_instance.
FDS_CMD_GC Garbage collection.
Used in fds_gc.
Function Documentation
ret_code_t fds_clear | ( | fds_record_desc_t *const | p_desc ) |
Function to clear a record.
Clearing a record has the effect of preventing the system from retrieving the record descriptor using the fds_find, fds_find_by_type and fds_find_by_instance functions. Additionally, fds_open calls shall fail when supplied a descritpor for a record which has been cleared. Clearing a record does not free the space it occupies in flash. The reclaim flash space used by cleared records, use fds_gc.
- Note:
- This function is asynchronous, therefore, completion is reported with a callback through the registered event handler.
- Parameters:
-
[in] p_desc The descriptor of the record to clear.
- Return values:
-
NRF_SUCCESS Success. The command was queued. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_NULL Error. p_desc is NULL. NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
ret_code_t fds_clear_by_instance | ( | fds_instance_id_t | instance ) |
Function to clear all records with a given instance.
Clearing a record has the effect of preventing the system from retrieving the record descriptor using the fds_find, fds_find_by_type and fds_find_by_instance functions. Additionally, fds_open calls shall fail when supplied a descritpor for a record which has been cleared. Clearing a record does not free the space it occupies in flash. The reclaim flash space used by cleared records, use fds_gc.
- Note:
- This function is asynchronous, therefore, completion is reported with a callback through the registered event handler. Only one callback will be issued. The record instance ID in the key parameter of the callback will contain the instance ID passed as parameter to this function. The record ID parameter will be zero, and the type ID equal to FDS_TYPE_ID_INVALID.
- Parameters:
-
[in] instance The instance ID of the records to clear.
- Return values:
-
NRF_SUCCESS Success. The command was queued. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_NULL Error. p_desc is NULL. NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
ret_code_t fds_close | ( | fds_record_desc_t const *const | p_desc ) |
Function to close a record, after its contents have been read.
Closing a record allows garbage collection to be run on the page in which the record being closed is stored (if no other records remain open on that page).
- Note:
- Closing a record, does NOT invalidate its descriptor, which can be safely supplied to all functions which accept a descriptor as a parameter.
- Parameters:
-
[in] p_desc The descriptor of the record to close.
- Return values:
-
NRF_SUCCESS Success. The record was closed. NRF_ERROR_NULL Error. p_desc is NULL. NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data.
ret_code_t fds_descriptor_from_rec_id | ( | fds_record_desc_t *const | p_desc, |
fds_record_id_t | record_id | ||
) |
Function to obtain a descriptor from a record ID.
This function can be used to reconstruct a descriptor from a record ID, such as the one passed to the callback function.
- Warning:
- This function does not check if a record with the given record ID exists or not. If a non-existing record ID is supplied, the resulting descriptor will cause other functions to fail when used as parameter.
- Parameters:
-
[out] p_desc The descriptor of the record with given record ID. [in] record_id The record ID for which to provide a descriptor.
- Return values:
-
NRF_SUCCESS Success. NRF_ERROR_NULL Error. p_desc is NULL.
bool fds_descriptor_match | ( | fds_record_desc_t const *const | p_desc_one, |
fds_record_desc_t const *const | p_desc_two | ||
) |
ret_code_t fds_find | ( | fds_type_id_t | type, |
fds_instance_id_t | instance, | ||
fds_record_desc_t *const | p_desc, | ||
fds_find_token_t *const | p_token | ||
) |
Function to search for records with a given key pair.
Because types are not unique, to search for the next record with the given key call the function again and supply the same fds_find_token_t structure to resume searching from the last record found.
- Parameters:
-
[in] type The record type ID. [in] instance The record instance ID. [out] p_desc The descriptor of the record found. [out] p_token A token containing information about the progress of the operation.
- Return values:
-
NRF_SUCCESS Success. A record was found. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_NULL Error. Either p_desc or p_token are NULL. NRF_ERROR_NOT_FOUND Error. No record with the given key pair was found.
ret_code_t fds_find_by_instance | ( | fds_instance_id_t | instance, |
fds_record_desc_t *const | p_desc, | ||
fds_find_token_t *const | p_token | ||
) |
Function to search for records with a given instance.
Because types are not unique, to search for the next record with the given key call the function again and supply the same fds_find_token_t structure to resume searching from the last record found.
- Parameters:
-
[in] instance The instance ID in the record key. [out] p_desc The descriptor of the record found. [out] p_token A token containing information about the progress of the operation.
- Return values:
-
NRF_SUCCESS Success. A record was found. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_NULL Error. Either p_desc or p_token are NULL. NRF_ERROR_NOT_FOUND Error. No record with the given instance was found.
ret_code_t fds_find_by_type | ( | fds_type_id_t | type, |
fds_record_desc_t *const | p_desc, | ||
fds_find_token_t *const | p_token | ||
) |
Function to search for records with a given type.
Because types are not unique, to search for the next record with the given key call the function again and supply the same fds_find_token_t structure to resume searching from the last record found.
- Parameters:
-
[in] type The type ID in the record key. [out] p_desc The descriptor of the record found. [out] p_token A token containing information about the progress of the operation.
- Return values:
-
NRF_SUCCESS Success. A record was found. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_NULL Error. Either p_desc or p_token are NULL. NRF_ERROR_NOT_FOUND Error. No record with the given type was found.
ret_code_t fds_gc | ( | void | ) |
Function to perform a garbage collection.
Garbage collection reclaims the flash space occupied by records which have been cleared using fds_clear.
- Note:
- This function is asynchronous, therefore, completion is reported with a callback through the registered event handler.
ret_code_t fds_init | ( | void | ) |
Function to initialize the module.
This function initializes the module and installs the filesystem, if it is not installed yet.
- Note:
- This function is asynchronous. Completion is reported with a callback through the registered event handler. To be able to receive such callback, be sure to call fds_register before calling fds_init.
- Return values:
-
NRF_SUCCESS Success. The command was queued. NRF_ERROR_INVALID_STATE Error. The module is currently undergoing initialization. NRF_ERROR_NO_MEM Error. Insufficient space to install the filesystem, or insufficient resources to perform the installation.
Initialize the last known record to zero. Its value will be updated by page_scan() called in pages_init().
This flag means fds_init() has been called. However, the module is NOT yet initialized.
ret_code_t fds_open | ( | fds_record_desc_t *const | p_desc, |
fds_record_t *const | p_record | ||
) |
Function to open a record for reading.
Function to read a record which has been written to flash. This function initializes a fds_record_t structure which can be used to access the record data as well as its associated metadata. The pointers provided in the fds_record_t structure are pointers to flash memory. Opening a record with fds_open prevents the garbage collection to run on the flash page in which record is stored, therefore the contents of the memory pointed by the fds_record_t p_data field is guaranteed to remain unmodified, as long as the record is kept open.
- Note:
- When you are done reading a record, close it using fds_close so that successive garbage collections can reclaim space on the page where the record is stored, if necessary.
- Parameters:
-
[in] p_desc The descriptor of the record to open. [out] p_record The record data and metadata, as stored in flash.
- Return values:
-
NRF_SUCCESS Success. The record was opened. NRF_ERROR_NOT_FOUND Error. The record was not found. It may have been cleared, or it may have not been written yet. NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data. NRF_ERROR_NULL Error. Either p_desc or p_record are NULL.
The record could not be found. It either never existed or it has been cleared.
ret_code_t fds_record_id_from_desc | ( | fds_record_desc_t const *const | p_desc, |
fds_record_id_t *const | p_record_id | ||
) |
Function to obtain a record ID from a record descriptor.
This function can be used to extract a record ID from a descriptor. It may be used in the callback function to determine which record the callback is associated to, if you have its descriptor.
- Warning:
- This function does not check the record descriptor sanity. If the descriptor is uninitialized, or has been tampered with, the resulting record ID may be invalid.
- Parameters:
-
[in] p_desc The descriptor from which to extract the record ID. [out] p_record_id The record ID contained in the given descriptor.
- Return values:
-
NRF_SUCCESS Success. NRF_ERROR_NULL Error. Either p_desc is NULL or p_record_id is NULL.
ret_code_t fds_register | ( | fds_cb_t | cb ) |
Function to register a callback for the module events.
The maximum amount of callback which can be registered can be configured by changing the FDS_MAX_USERS macro in fds_config.h.
- Parameters:
-
[in] cb The callback function.
- Return values:
-
NRF_SUCCESS Success. NRF_ERROR_NO_MEM Error. Maximum number of registered callbacks reached.
ret_code_t fds_reserve | ( | fds_write_token_t *const | p_tok, |
uint16_t | length_words | ||
) |
Function to reserve space for a record.
This function can be used to reserve flash space to store a record, which can be later written down using fds_write_reserved. It is possible to cancel a reservation by using fds_reserve_cancel.
- Parameters:
-
[out] p_tok A token which can be used to write a record in the reserved space using fds_write_reserved. [in] length_words The lenght of the record data, in 4 byte words.
- Return values:
-
NRF_SUCCESS Success. Flash space was successfully reserved. NRF_ERROR_NULL Error. p_tok is NULL. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_NO_MEM Error. Insufficient space.
ret_code_t fds_reserve_cancel | ( | fds_write_token_t *const | p_tok ) |
Function to cancel a space reservation.
- Parameters:
-
[in] p_tok The token produced by fds_reserve, identifying the reservation to cancel.
- Return values:
-
NRF_SUCCESS Success. The reservation was canceled. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_NULL Error. p_tok is NULL. NRF_ERROR_INVALID_DATA Error. p_tok contains invalid data.
We are trying to cancel a reservation for more words than how many are currently reserved on the page. This is shouldn't happen.
ret_code_t fds_update | ( | fds_record_desc_t *const | p_desc, |
fds_record_key_t | key, | ||
uint8_t | num_chunks, | ||
fds_record_chunk_t | chunks[] | ||
) |
Function to update an existing record.
Updating a record writes a new record with the given key and data in flash, and then clears the old record.
- Note:
- This function is asynchronous, therefore, completion is reported with a callback through the registered event handler. Two callbacks will be issued, one to signal that the updated record has been written down, and another to signal that the old one has been cleared.
- The record data must be aligned on a 4 byte boundary, and because it is not buffered internally, it must be kept in memory by the application until the callback for the command has been received, i.e., the command completed.
- Parameters:
-
[in,out] p_desc The descriptor of the record to update. The descriptor of the updated record, after the function has returned with NRF_SUCCESS. [in] key The record new key pair. [in] num_chunks The number of elements in the chunks array. [in] chunks An array of chunks making up the record new data.
- Return values:
-
NRF_SUCCESS Success. The command was queued. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance. NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary. NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght. NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation. NRF_ERROR_NO_MEM Error. No flash space available to store the record.
ret_code_t fds_write | ( | fds_record_desc_t *const | p_desc, |
fds_record_key_t | key, | ||
uint8_t | num_chunks, | ||
fds_record_chunk_t | chunks[] | ||
) |
Function to write a record to flash.
This function can be used to write a record to flash. A record data consists of multiple chunks and is supplied to the function as an array of fds_record_chunk_t structures. The maximum lenght of a record data may not exceed the size of one flash page minus FDS_HEADER_SIZE words.
- Note:
- This function is asynchronous, therefore, completion is reported with a callback through the registered event handler.
- The record data must be aligned on a 4 byte boundary, and because it is not buffered internally, it must be kept in memory by the application until the callback for the command has been received, i.e., the command completed.
- Parameters:
-
[out] p_desc The record descriptor. It may be NULL. [in] key The record key pair. [in] num_chunks The number of elements in the chunks array. [in] chunks An array of chunks making up the record data.
- Return values:
-
NRF_SUCCESS Success. The command was queued. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance. NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary. NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght. NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation. NRF_ERROR_NO_MEM Error. No flash space available to store the record.
ret_code_t fds_write_reserved | ( | fds_write_token_t const *const | p_tok, |
fds_record_desc_t *const | p_desc, | ||
fds_record_key_t | key, | ||
uint8_t | num_chunks, | ||
fds_record_chunk_t | chunks[] | ||
) |
Function to write a record to flash, the space for which has been previously reserved using fds_reserve.
This function behaves similarly to fds_write, with the exception that it never fails with NRF_ERROR_NO_MEM.
- Note:
- This function is asynchronous, therefore, completion is reported with a callback through the registered event handler.
- The record data must be aligned on a 4 byte boundary, and because it is not buffered internally, it must be kept in memory by the application until the callback for the command has been received, i.e., the command completed.
- Parameters:
-
[in] p_tok The token return by fds_reserve. [out] p_desc The record descriptor. It may be NULL. [in] key The record key pair. [in] num_chunks The number of elements in the chunks array. [in] chunks An array of chunks making up the record data.
- Return values:
-
NRF_SUCCESS Success. The command was queued. NRF_ERROR_INVALID_STATE Error. The module is not initialized. NRF_ERROR_INVALID_DATA Error. The key contains an invalid type or instance. NRF_ERROR_INVALID_ADDR Error. The record data is not aligned on a 4 byte boundary. NRF_ERROR_INVALID_LENGTH Error. The record length exceeds the maximum lenght. NRF_ERROR_BUSY Error. Insufficient internal resources to queue the operation.
Generated on Tue Jul 12 2022 11:17:21 by
![doxygen](doxygen.png)