Espressif ESP32-S2 Programming Manual page 720

Chapter 2. API Reference
Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS
to preserve this value between ESP32-S2 module restarts.
• value - tracks the number of the ESP32-S2 module soft and hard restarts.
• blob - contains a table with module run times. The table is read from NVS to dynamically allocated
RAM. A new run time is added to the table on each manually triggered soft restart, and then the
added run time is written to NVS. Triggering is done by pulling down GPIO0.
The example also shows how to implement the diagnostic procedure to check if the read / write operation
was successful.
storage/nvs_rw_value_cxx
This example does exactly the same as storage/nvs_rw_value, except that it uses the C++ NVS handle
class.
Internals
Log of key-value pairs
When a value of any given key has to be updated, a new key-value pair is added at the end of the log and the old
key-value pair is marked as erased.
Pages and entries NVS library uses two main entities in its operation: pages and entries. Page is a logical structure
which stores a portion of the overall log. Logical page corresponds to one physical sector of flash memory. Pages
which are in use have a sequence number associated with them. Sequence numbers impose an ordering on pages.
Higher sequence numbers correspond to pages which were created later. Each page can be in one of the following
states:
Empty/uninitialized Flash storage for the page is empty (all bytes are 0xff). Page is not used to store any data at
this point and does not have a sequence number.
Active Flash storage is initialized, page header has been written to flash, page has a valid sequence number. Page
has some empty entries and data can be written there. No more than one page can be in this state at any given
moment.
Full Flash storage is in a consistent state and is filled with key-value pairs. Writing new key-value pairs into this
page is not possible. It is still possible to mark some key-value pairs as erased.
Erasing Non-erased key-value pairs are being moved into another page so that the current page can be erased. This
is a transient state, i.e., page should never stay in this state at the time when any API call returns. In case of a
sudden power off, the move-and-erase process will be completed upon the next power-on.
Corrupted Page header contains invalid data, and further parsing of page data was canceled. Any items previously
written into this page will not be accessible. The corresponding flash sector will not be erased immediately and
will be kept along with sectors in uninitialized state for later use. This may be useful for debugging.
Mapping from flash sectors to logical pages does not have any particular order. The library will inspect sequence
numbers of pages found in each flash sector and organize pages in a list based on these numbers.
+--------+ +--------+
| Page 1 | | Page 2 |
| Full +---> | Full
| #11 | | #12
+---+----+ +----+---+
|
|
|
+---v------+ +-----v----+
| Sector 3 | | Sector 0 |
+----------+ +----------+
Structure of a page For now, we assume that flash sector size is 4096 bytes and that ESP32-S2 flash encryption
hardware operates on 32-byte blocks. It is possible to introduce some settings configurable at compile-time (e.g., via
Espressif Systems
NVS stores key-value pairs sequentially, with new key-value pairs being added at the end.
+--------+
| Page 3 |
+---> | Active |
| | #14
+----+---+
| |
| |
| |
+------v---+
| Sector 2 |
+----------+
Submit Document Feedback
+--------+
| Page 4 |
| Empty | <- states
| | | <- sequence numbers
+---+----+
|
|
|
+------v---+
| Sector 1 | <- physical sectors
+----------+
709 Release v4.4