Espressif ESP32-S2 Programming Manual page 721

Chapter 2. API Reference
menuconfig) to accommodate flash chips with different sector sizes (although it is not clear if other components in
the system, e.g., SPI flash driver and SPI flash cache can support these other sizes).
Page consists of three parts: header, entry state bitmap, and entries themselves. To be compatible with ESP32-S2
flash encryption, the entry size is 32 bytes. For integer types, an entry holds one key-value pair. For strings and blobs,
an entry holds part of key-value pair (more on that in the entry structure description).
The following diagram illustrates the page structure. Numbers in parentheses indicate the size of each part in bytes.
+-----------+--------------+-------------+-------------------------+
| State (4) | Seq. no. (4) | version (1) | Unused (19) | CRC32 (4) |
+-----------+--------------+-------------+-------------------------+
| Entry state bitmap (32)
+------------------------------------------------------------------+
|
+------------------------------------------------------------------+
|
+------------------------------------------------------------------+
/
/
+------------------------------------------------------------------+
|
+------------------------------------------------------------------+
Page header and entry state bitmap are always written to flash unencrypted. Entries are encrypted if flash encryption
feature of ESP32-S2 is used.
Page state values are defined in such a way that changing state is possible by writing 0 into some of the bits. Therefore
it is not necessary to erase the page to change its state unless that is a change to the erased state.
The version field in the header reflects the NVS format version used. For backward compatibility reasons, it is
decremented for every version upgrade starting at 0xff (i.e., 0xff for version-1, 0xfe for version-2 and so on).
CRC32 value in the header is calculated over the part which does not include a state value (bytes 4 to 28). The unused
part is currently filled with 0xff bytes.
The following sections describe the structure of entry state bitmap and entry itself.
Entry and entry state bitmap
the entry state bitmap. The final four bits in the bitmap (256 - 2 * 126) are not used.
Empty (2'b11) Nothing is written into the specific entry yet. It is in an uninitialized state (all bytes are 0xff).
Written (2'b10) A key-value pair (or part of key-value pair which spans multiple entries) has been written into
the entry.
Erased (2'b00) A key-value pair in this entry has been discarded. Contents of this entry will not be parsed any-
more.
Structure of entry For values of primitive types (currently integers from 1 to 8 bytes long), entry holds one key-
value pair. For string and blob types, entry holds part of the whole key-value pair. For strings, in case when a
key-value pair spans multiple entries, all entries are stored in the same page. Blobs are allowed to span over multiple
pages by dividing them into smaller chunks. For tracking these chunks, an additional fixed length metadata entry is
stored called "blob index". Earlier formats of blobs are still supported (can be read and modified). However, once
the blobs are modified, they are stored using the new format.
+--------+----------+----------+----------------+-----------+---------------+------
----+
→
| NS (1) | Type (1) | Span (1) | ChunkIndex (1) | CRC32 (4) |
(8) |
→
+--------+----------+----------+----------------+-----------+---------------+------
----+
→
--+
→
Espressif Systems
Entry 0 (32)
Entry 1 (32)
Entry 125 (32)
Each entry can be in one of the following three states represented with two bits in
Primitive
710
Submit Document Feedback
Header (32)
|
|
|
/
/
|
Key (16)
+------------------------------
(continues on next page)
| Data␣
Release v4.4