The Flash Data Storage API exposes functions to manipulate records. A record is made up of one or more record chunks, which contain the record data, and a key pair: type and instance.
To manipulate a record, its descriptor must be obtained first.
When a record is first written to flash using fds_write, a descriptor for the record is returned. Alternatively, a descriptor for a record can be retrieved using the fds_find, fds_find_by_type and fds_find_by_instance functions, which allow to search for a record based on its keys. Since keys are not unique, these functions use a fds_find_token_t structure to keep track of the progress of the operation. See Retrieving data for an example on how to enumerate all records with a given key set.
When a descriptor for a record is available, it is possible to manipulate that record using the fds_open, fds_update and fds_clear functions, to read, update and delete its content respectively.
To read the content of a record, the record must be opened using fds_open. Opening a record returns a fds_record_t structure which contains a pointer to where the record data is stored in flash, as well as the record metadata. Because the fds_record_t structure is pointing directly to flash, fds_open takes care to prevents the record from being moved to a different location in flash memory as a result of a garbage collection operation. When the record has been read, fds_close should be used to close the record, so that the system may relocate the record, if necessary, the next time garbage collection is run.
Deleting a record using fds_clear has the effect of preventing the fds_find, fds_find_by_type and fds_find_by_instance functions from finding the record. Additionally, calls to fds_open to read the contents of the record will fail. However, the space used by the record in flash is not freed. To free the space used by records which have been cleared, garbage collection must be run. See Reclaiming flash space using garbage collection for more information.
Updating a record using fds_update writes down a new record and then clears the old one. Both the content and the keys of the new record may be changed arbitrarily.
Garbage collection is how Flash Data Storage reclaims flash space used by records which have been deleted using fds_clear. Garbage collection is never run automatically by FDS, so the user must take care of running garbage collection manually. Since the operation can result in many flash operations, especially writes, it can be intensive both in terms of power and resource consumption and therefore should only be run when necessary, i.e. when the space in flash is exhausted.
It is possible to configure some FDS parameteres by changing some macros in the fds_config.h header file. These include: