Flash Data Storage stores records sequentially in flash, together with some metadata. A record metadata (or header) includes:

The unique record ID.
The record length, expressed in number of 4 byte words.
The record key pair (type and instance).
A 16 bit CRC of the whole record (to be implemented).

Record layout and metadata

The layout of a record in flash is shown below:

+--------------------------+---------------------------+----------------+-----------------------+
|        Word (TL)         |        Word (IC)          |    Word  (ID)  |   <Length> words      |
+------------+-------------|-------------+-------------|----------------+-----------------------+
|    Type    |   Length    |   Instance  |  Checksum   |    Record ID   |         Data          | 
+------------+-------------+-------------+-------------+----------------------------------------+

The size of the record metadata is three words, i.e., 12 bytes, and is divided as follows:

+-------------------+
|  Field   |  Size  |
+-------------------+
|Type      | 16 bits|
|Lenght    | 16 bits|
|Instance  | 16 bits|
|Checksum  | 16 bits|
|Record ID | 32 bits|
+-------------------+

The order with which the record metadata words are written to flash is the following: TL, ID, and IC. The IC is written last and serves as a mean to finalize a successful write. When scanning through records, if the IC word is missing (not written) the system will disregard that record.

A record metadata may be accessed using fds_open through the fds_header_t field in the fds_record_t structure.

Some restrictions are made on the keys:

FDS_TYPE_ID_INVALID (0x0000) is reserved by the system to flag records which have been cleared.
FDS_INSTANCE_ID_INVALID (0xFFFF) is reserved by the system to be able to quickly check the sanity of a record, as discussed above.

Additionally:

Type keys in the range 0x8000 - 0xFFFE, and Instance keys in the range 0x4000 - 0x7FFF are in use by the Peer Manager. The application should avoid using those.

The maximum length of a record depends on the size of one physical flash page, which is 256 words for nRF51, 1024 words for nRF52, the size of the page tag (4 words), and the size of the record metadata (3 words). Therefore, the maximum data length is 249 words for nRF51 and 1017 words for nRF52.

To store larger data, use the Experimental: FStorage module instead of FDS.

The checksum field can be used by the system to validate a write operation and to check for data corruption opon reads. This is currently not implemented.

Page tag

Each page that is used to store FDS data is marked tagged with four words which contain the page metadata, used by the system to store information about the page. This information includes:

What the system is using the page for (storage or for GC).
The version of the filesystem installed on the page.
Whether the page is being garbage collected or not.

The following table gives shows all possible page tag values and their descriptions:

  Word 0   |   Word 1   |   Word 2   |   Word 3  | Description
-----------|------------|------------|-----------|------------
0xA4A4A4A4 | 0xAABBCCDD | 0xAABB01DD | 0x1CEB00DA| Page used for storage.
0xA4A4A4A4 | 0xAABBCCDD | 0xAABB01DD | 0x1CEB00D8| Page used for storage which is being garbage colleted.
0xA5A5A5A5 | 0xAABBCCDD | 0xAABB01DD | 0x1CEB00DA| Reserved for garbage collection.

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