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)

Flash data storage callback function.

Parameters:

result	Result of the command.
cmd	The command associated with the callback.
record_id	The unique ID of the record associated with the callback.
record_key	The key pair of the record associated with the callback.

Definition at line 189 of file fds.h.

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.

Definition at line 170 of file fds.h.

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.

Definition at line 1905 of file fds.c.

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.

Definition at line 1940 of file fds.c.

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.

Definition at line 1645 of file fds.c.

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.

Definition at line 2064 of file fds.c.

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.

Parameters:

[in]	p_desc_one	First descriptor.
[in]	p_desc_two	Second descriptor.

Return values:

true	If the descriptors identify the same record.
false	Otherwise.

Definition at line 2052 of file fds.c.

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.

Definition at line 1998 of file fds.c.

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.

Definition at line 2025 of file fds.c.

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.

Definition at line 2012 of file fds.c.

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.

Definition at line 1988 of file fds.c.

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.

Definition at line 1528 of file fds.c.

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.

Definition at line 1607 of file fds.c.

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.

Definition at line 2078 of file fds.c.

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.

Definition at line 2038 of file fds.c.

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.

Definition at line 1780 of file fds.c.

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.

Definition at line 1807 of file fds.c.

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.

Definition at line 1950 of file fds.c.

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.

Definition at line 1845 of file fds.c.

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.

Definition at line 1858 of file fds.c.

Type:	Library
Created:	30 Jan 2017
Imports:	4
Forks:	0
Commits:	10
Dependents:	1
Dependencies:	0
Followers:	1

Flash Data Storage

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Flash Data Storage

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning