Merge branch 'feat/nvs_iteration_statistics_examples_v5.4' into 'release/v5.4'

feat(examples/storage): add nvs statistics and iteration examples (v5.4)

See merge request espressif/esp-idf!43671

docs/en/api-guides/file-system-considerations.rst

@@ -179,6 +179,8 @@ Points to keep in mind when developing NVS related code:
 
 - :example:`storage/nvs_rw_value` demonstrates how to use NVS to write and read a single integer value.
 - :example:`storage/nvs_rw_blob` demonstrates how to use NVS to write and read a blob.
+- :example:`storage/nvs_statistics` demonstrates how to obtain and interpret NVS usage statistics: free/used/available/total number of entries and number of namespaces in given NVS partition.
+- :example:`storage/nvs_iteration` demonstrates how to iterate over entries of specific (or any) NVS data type and how to obtain info about such entries.
 - :example:`security/nvs_encryption_hmac` demonstrates NVS encryption using the HMAC peripheral, where the encryption keys are derived from the HMAC key burnt in eFuse.
 - :example:`security/flash_encryption` demonstrates the flash encryption workflow including NVS partition creation and usage.
 

docs/en/api-reference/storage/index.rst

@@ -53,6 +53,10 @@ Examples
       - Shows the use of the C-style API to read and write integer data types in NVS flash.
     * - :example:`nvs_rw_value_cxx <storage/nvs_rw_value_cxx>`
       - Shows the use of the C++-style API to read and write integer data types in NVS flash.
+    * - :example:`nvs_statistics <storage/nvs_statistics>`
+      - Shows the use of the C-style API to obtain NVS usage statistics: free/used/available/total number of entries and number of namespaces in given NVS partition.
+    * - :example:`nvs_iteration <storage/nvs_iteration>`
+      - Shows the use of the C-style API to iterate over entries of specific (or any) NVS data type and how to obtain info about such entries.
     * - :example:`nvs_bootloader <storage/nvs_bootloader>`
       - Shows the use of the API available to the bootloader code to read NVS data.
     * - :example:`nvsgen <storage/nvsgen>`

docs/en/api-reference/storage/nvs_flash.rst

@@ -177,6 +177,22 @@ You can find code examples in the :example:`storage` directory of ESP-IDF exampl
 
   This example does exactly the same as :example:`storage/nvs_rw_value`, except that it uses the C++ NVS handle class.
 
+:example:`storage/nvs_statistics`
+
+  This example demonstrates how to obtain and interpret NVS usage statistics: free/used/available/total number of entries and number of namespaces in given NVS partition.
+
+  Default NVS partition is erased for a clean run of this example. Then mock data string values are written.
+
+  Usage statistics are obtained prior to and post writing, with the differences being compared to expected values of newly used entries.
+
+:example:`storage/nvs_iteration`
+
+  This example demonstrates how to iterate over entries of specific (or any) NVS data type and how to obtain info about such entries.
+
+  Default NVS partition is erased for a clean run of this example. Then mock data consisting of different NVS integer data types are written.
+
+  After that, the example iterates over each individual data type as well as the generic ``NVS_TYPE_ANY`` type, and logs the information obtained from each iteration.
+
 Internals
 ---------