Flash Data Storage

Invalid file ID.

This value must not be used as a file ID by the application.

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.

FDS event handler function prototype.

Parameters

p_evt

The event.

FDS return values.

FDS event IDs.

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.

Note

This function does not check whether a record with the given record ID exists. If a non-existing record ID is supplied, the resulting descriptor is invalid and will cause other functions to fail when it is supplied as parameter.

Parameters

[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.

Return values

FDS_SUCCESS	If a descriptor was returned.
FDS_ERR_NULL_ARG	If p_desc is NULL.

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.

Parameters

[in]

file_id

The ID of the file to be deleted.

Return values

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.

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.

Return values

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.

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.

Return values

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.

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.

Parameters

[in]

p_desc

The descriptor of the record to close.

Return values

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.

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.

Parameters

[in]

p_desc

The descriptor of the record that should be deleted.

Return values

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.

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.

Parameters

[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.

Return values

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.

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.

Parameters

[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.

Return values

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.

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.

Parameters

[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.

Return values

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.

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.

Warning

This function does not check whether the record descriptor is valid. If the descriptor is not initialized or has been tampered with, the resulting record ID might be invalid.

Parameters

[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.

Return values

FDS_SUCCESS	If a record ID was returned.
FDS_ERR_NULL_ARG	If p_desc or p_record_id is NULL.

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.

Parameters

[out]	p_desc	The descriptor of the record that was found.
[out]	p_token	A token containing information about the progress of the operation.

Return values

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.

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.

Parameters

[in]	p_desc	The descriptor of the record to open.
[out]	p_flash_record	The record, as stored in flash.

Return values

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.

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.

Parameters

[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.

Return values

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.

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.

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.

Parameters

[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.

Return values

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.

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.

Note

This function behaves similarly to fds_record_write , with the exception that it never fails with the error FDS_ERR_NO_SPACE_IN_FLASH .

Parameters

[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.

Return values

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.

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.

Parameters

[in]

cb

The event handler function.

Return values

FDS_SUCCESS	If the event handler was registered successfully.
FDS_ERR_USER_LIMIT_REACHED	If the maximum number of registered callbacks is reached.

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.

Parameters

[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).

Return values

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.

Function for canceling an fds_reserve operation.

Parameters

[in]

p_token

The token that identifies the reservation, produced by fds_reserve .

Return values

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.

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.

Parameters

[out]

p_stat

File system statistics.

Return values

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.

Function for enabling and disabling CRC verification for write operations.

CRC verification ensures that data that is queued for writing does not change before the write actually happens. Use this function to enable or disable CRC verification. If verification is enabled, the error FDS_ERR_CRC_CHECK_FAILED is returned in the event for fds_record_write , fds_record_write_reserved , or fds_record_update if verification fails.

Note

CRC verification is enabled or disabled globally, thus for all users of the FDS module.

Parameters

[in]

enabled

1 to enable CRC verification. 0 to disable CRC verification.

Return values

FDS_SUCCESS

If CRC verification was enabled or disabled successfully.