From db7c257f339fbecb1234ba72dcd2bc5efa5cdbeb Mon Sep 17 00:00:00 2001
From: Sagar Bijwe <sagar@espressif.com>
Date: Tue, 4 Sep 2018 18:01:17 +0530
Subject: [PATCH] nvs_flash: Minor changes to NVS documentation

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
---
 components/nvs_flash/README.rst    | 32 ++++++++++++++++--------------
 components/nvs_flash/include/nvs.h |  5 +++--
 2 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/components/nvs_flash/README.rst b/components/nvs_flash/README.rst
index e69d12b712..7225ba52b4 100644
--- a/components/nvs_flash/README.rst
+++ b/components/nvs_flash/README.rst
@@ -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.
 
diff --git a/components/nvs_flash/include/nvs.h b/components/nvs_flash/include/nvs.h
index 44c6c7a2ca..bcc46563c3 100644
--- a/components/nvs_flash/include/nvs.h
+++ b/components/nvs_flash/include/nvs.h
@@ -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