Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

nvs_flash: Minor changes to NVS documentation

Browse source 
1) Change API doc to reflect new limits on string and blob length.
2) Add "version" field to Page Header structure in README.

Fixes: https://github.com/espressif/esp-idf/issues/2321
This commit is contained in:
Sagar Bijwe 2018-09-04 18:01:17 +05:30
parent b91cf5a33f
commit db7c257f33
2 changed files with 20 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
components/nvs_flash/README.rst
View file

@ -107,26 +107,28 @@ Page consists of three parts: header, entry state bitmap, and entries themselves
The following diagram illustrates page structure. Numbers in parentheses indicate size of each part in bytes. ::
+-----------+--------------+-------------+-----------+
| State (4) | Seq. no. (4) | Unused (20) | CRC32 (4) | Header (32)
+-----------+--------------+-------------+-----------+
| Entry state bitmap (32) |
+----------------------------------------------------+
| Entry 0 (32) |
+----------------------------------------------------+
| Entry 1 (32) |
+----------------------------------------------------+
/ /
/ /
+----------------------------------------------------+
| Entry 125 (32) |
+----------------------------------------------------+
+-----------+--------------+-------------+-------------------------+
| State (4) | Seq. no. (4) | version (1) | Unused (19) | CRC32 (4) | Header (32)
+-----------+--------------+-------------+-------------------------+
| Entry state bitmap (32) |
+------------------------------------------------------------------+
| Entry 0 (32) |
+------------------------------------------------------------------+
| Entry 1 (32) |
+------------------------------------------------------------------+
/ /
/ /
+------------------------------------------------------------------+
| Entry 125 (32) |
+------------------------------------------------------------------+
Page header and entry state bitmap are always written to flash unencrypted. Entries are encrypted if flash encryption feature of the ESP32 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 not necessary to erase the page to change page state, unless that is a change to *erased* state.
CRC32 value in header is calculated over the part which doesn't include state value (bytes 4 to 28). Unused part is currently filled with ``0xff`` bytes. Future versions of the library may store format version there.
The version field in the header reflects 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 header is calculated over the part which doesn't include state value (bytes 4 to 28). Unused part is currently filled with ``0xff`` bytes.
The following sections describe structure of entry state bitmap and entry itself.

5
components/nvs_flash/include/nvs.h
View file

@ -127,7 +127,7 @@ esp_err_t nvs_open_from_partition(const char *part_name, const char* name, nvs_o
* 15 characters. Shouldn't be empty.
* @param[in] value The value to set.
* For strings, the maximum length (including null character) is
* 1984 bytes.
* 4000 bytes.
*
* @return
* - ESP_OK if value was set successfully
@ -164,7 +164,8 @@ esp_err_t nvs_set_str (nvs_handle handle, const char* key, const char* value);
* @param[in] key Key name. Maximal length is 15 characters. Shouldn't be empty.
* @param[in] value The value to set.
* @param[in] length length of binary value to set, in bytes; Maximum length is
* 1984 bytes.
* 508000 bytes or (97.6% of the partition size - 4000) bytes
* whichever is lower.
*
* @return
* - ESP_OK if value was set successfully