Flash Data Storage stores data as records, which are grouped into files. In most use cases, you do not need to understand in detail how FDS stores the data in flash. The following information gives some insight about the data format that FDS uses, but if you are not interested in the details, you can skip this part.

Record layout

Records consist of a header (the record metadata) and the actual content. They are stored contiguously in flash in the order they are written. An exception from this rule might happen when a small record is written after a large record. Then, the small record might be placed in the end of the previous flash page, where the larger record did not fit.

Layout of a record

Record header

The record header consists of three words (12 bytes), which are used in the following way:

Field	Size	Description
Record key	16 bits	Key that can be used to find the record. The value FDS_RECORD_KEY_DIRTY (0x0000) is reserved by the system to flag records that have been invalidated. See Restrictions on keys and IDs for further restrictions.
Data length	16 bits	Length of the data that is stored in the record (in 4-byte words).
File ID	16 bits	ID of the file that the record is associated with. The value FDS_FILE_ID_INVALID (0xFFFF) is used by the system to identify records that have not been written correctly. See Restrictions on keys and IDs for further restrictions.
CRC value	16 bits	CRC value of the whole record (checks can be enabled by setting the FDS_CRC_ENABLED compile flag, see Configuration).
Record ID	32 bits	Unique identifier of the record.

When writing the record header to flash, FDS writes the record key and data length first, followed by the record ID. The file ID and the CRC value are written last and finalize a successful write operation. When scanning through records, the FDS module ignores all records where the second word of the header has not been written, because a missing key indicates that the record was not stored completely.

Maximum length

The maximum length of a record depends on the size of a virtual flash page (defined in in fds_config.h, see FDS_VIRTUAL_PAGE_SIZE), the size of the page tag (2 words), and the size of the record header (3 words). By default, the virtual page size is set to the physical page size (1024 words), which results in a maximum data length of 1019 words.

To store larger data, increase the virtual page size or use the Flash Storage (fstorage) module instead of FDS.

Page tag

Each virtual page that is used by FDS is marked with a page tag that is used by the system to store information about the page. The 2-word page tag contains information about what the page is used for (data storage or garbage collection) and what version of the file system is installed on the page.

The following page tags are used:

Word 0	Word 1	Description
0xDEADC0DE	0xF11E01FF	Page used for swap during garbage collection.
0xDEADC0DE	0xF11E01FE	Page used to store data.

The page tags are written when FDS is first initialized and updated only during garbage collection.