Flash Data Storage (FDS). More...

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

#define	FDS_BOUND_NOT_SET (0)
	Value for unconfigured FDS physical bound. 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...

ret_code_t	flash_bounds_set (const uint32_t start_addr, const uint32_t end_addr)
	Set physical boundaries for FDS. More...

Variables
	ANON_UNIONS_ENABLE

	ANON_UNIONS_DISABLE

Detailed Description

Flash Data Storage (FDS).

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA integrated circuit in a product or a software update for such product, must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
This software, with or without modification, must only be used with a Nordic Semiconductor ASA integrated circuit.
Any software provided in binary form under this license must not be reverse engineered, decompiled, modified and/or disassembled.

THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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.

Macro Definition Documentation

◆ FDS_BOUND_NOT_SET

#define FDS_BOUND_NOT_SET (0)

Value for unconfigured FDS physical bound.

Definition at line 83 of file fds.h.

◆ FDS_FILE_ID_INVALID

#define FDS_FILE_ID_INVALID (0xFFFF)

Invalid file ID.

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

Definition at line 70 of file fds.h.

◆ FDS_RECORD_KEY_DIRTY

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

Definition at line 78 of file fds.h.

Typedef Documentation

◆ fds_cb_t

typedef void(* fds_cb_t) (fds_evt_t const *p_evt)

FDS event handler function prototype.

Parameters

p_evt The event.

Definition at line 273 of file fds.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

FDS return values.

Enumerator
FDS_SUCCESS	The operation completed successfully.
FDS_ERR_OPERATION_TIMEOUT	Error. The operation timed out.
FDS_ERR_NOT_INITIALIZED	Error. The module has not been initialized.
FDS_ERR_UNALIGNED_ADDR	Error. The input data is not aligned to a word boundary.
FDS_ERR_INVALID_ARG	Error. The parameter contains invalid data.
FDS_ERR_NULL_ARG	Error. The parameter is NULL.
FDS_ERR_NO_OPEN_RECORDS	Error. The record is not open, so it cannot be closed.
FDS_ERR_NO_SPACE_IN_FLASH	Error. There is no space in flash memory.
FDS_ERR_NO_SPACE_IN_QUEUES	Error. There is no space in the internal queues.
FDS_ERR_RECORD_TOO_LARGE	Error. The record exceeds the maximum allowed size.
FDS_ERR_NOT_FOUND	Error. The record was not found.
FDS_ERR_NO_PAGES	Error. No flash pages are available.
FDS_ERR_USER_LIMIT_REACHED	Error. The maximum number of users has been reached.
FDS_ERR_CRC_CHECK_FAILED	Error. The CRC check failed.
FDS_ERR_BUSY	Error. The underlying flash subsystem was busy.
FDS_ERR_INTERNAL	Error. An internal error occurred.

Definition at line 88 of file fds.h.

◆ fds_evt_id_t

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.

Definition at line 193 of file fds.h.

Function Documentation

◆ fds_descriptor_from_rec_id()

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.

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.

◆ fds_file_delete()

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.

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.

◆ fds_gc()

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.

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.

◆ fds_init()

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.

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.

◆ fds_record_close()

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.

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.

◆ fds_record_delete()

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.

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.

◆ fds_record_find()

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.

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.

◆ fds_record_find_by_key()

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.

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.

◆ fds_record_find_in_file()

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.

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.

◆ fds_record_id_from_desc()

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.

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.

◆ fds_record_iterate()

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.

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.

◆ fds_record_open()

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.

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.

◆ fds_record_update()

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.

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. The record is required to be word aligned.

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.

◆ fds_record_write()

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.

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. The record is required to be word aligned.

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.

◆ fds_record_write_reserved()

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.

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. The record is required to be word aligned.
[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.

◆ fds_register()

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.

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.

◆ fds_reserve()

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.

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.

◆ fds_reserve_cancel()

ret_code_t fds_reserve_cancel ( fds_reserve_token_t * p_token )

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.

◆ fds_stat()

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.

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.

◆ flash_bounds_set()

ret_code_t flash_bounds_set	(	const uint32_t	start_addr,
		const uint32_t	end_addr
	)

Set physical boundaries for FDS.

This function must be called before init to ensure safe access to flash. Ideally the flash area is configured in linker. If the allocated space is larger than required by FDS, space will be allocated from top to down. E.g. start_addr 0x10000 end_addr 0x19000 FDS_PHY_PAGES 5 (size 0x1000) => end_addr 0x19000, start_addr 0x14000. The addresses must aligned to physical flash pages.

Parameters

[in]	start_addr	Start of physical space in flash. Inclusive.
[in]	end_addr	End of physical space in flash. Exclusive.

Return values

FDS_SUCCESS	Flash bounds were configured.
FDS_ERR_INVALID_ARG	End address is smaller than or equal to start address.
FDS_ERR_UNALIGNED_ADDR	End address is not aligned to physical flash pages.
FDS_ERR_NO_SPACE_IN_FLASH	Configured address space isn't enough for FDS_PHY_PAGES.
FDS_ERR_INTERNAL	if FDS bounds are already configured.

Variable Documentation

◆ ANON_UNIONS_DISABLE

ANON_UNIONS_DISABLE

Definition at line 229 of file fds.h.

◆ ANON_UNIONS_ENABLE

ANON_UNIONS_ENABLE

Definition at line 204 of file fds.h.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ FDS_BOUND_NOT_SET

◆ FDS_FILE_ID_INVALID

◆ FDS_RECORD_KEY_DIRTY

Typedef Documentation

◆ fds_cb_t

Enumeration Type Documentation

◆ anonymous enum

◆ fds_evt_id_t

Function Documentation

◆ fds_descriptor_from_rec_id()

◆ fds_file_delete()

◆ fds_gc()

◆ fds_init()

◆ fds_record_close()

◆ fds_record_delete()

◆ fds_record_find()

◆ fds_record_find_by_key()

◆ fds_record_find_in_file()

◆ fds_record_id_from_desc()

◆ fds_record_iterate()

◆ fds_record_open()

◆ fds_record_update()

◆ fds_record_write()

◆ fds_record_write_reserved()

◆ fds_register()

◆ fds_reserve()

◆ fds_reserve_cancel()

◆ fds_stat()

◆ flash_bounds_set()

Variable Documentation

◆ ANON_UNIONS_DISABLE

◆ ANON_UNIONS_ENABLE