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

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

See merge request espressif/esp-idf!43661

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

@@ -183,6 +183,8 @@ Points to keep in mind when developing NVS related code:
 
 - :example:`storage/nvs/nvs_rw_value` demonstrates how to use NVS to write and read a single integer value.
 - :example:`storage/nvs/nvs_rw_blob` demonstrates how to use NVS to write and read a blob.
+- :example:`storage/nvs/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/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/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/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/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/nvs_bootloader>`
       - Shows the use of the API available to the bootloader code to read NVS data.
     * - :example:`nvsgen <storage/nvs/nvsgen>`

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

@@ -177,6 +177,22 @@ You can find code examples in the :example:`storage/nvs` directory of ESP-IDF ex
 
   This example does exactly the same as :example:`storage/nvs/nvs_rw_value`, except that it uses the C++ NVS handle class.
 
+:example:`storage/nvs/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/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
 ---------
 

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

@@ -183,6 +183,8 @@ NVS 具有如下特性：
 
 - :example:`storage/nvs/nvs_rw_value` 演示了如何写入和读取一个整数值。
 - :example:`storage/nvs/nvs_rw_blob` 演示如何写入和读取一个 blob。
+- :example:`storage/nvs/nvs_statistics` 演示了如何获取并解读 NVS 使用情况统计信息：包括指定 NVS 分区中的空闲、已用、可用、总条目数、以及命名空间数量。
+- :example:`storage/nvs/nvs_iteration` 演示了如何遍历特定（或任意）NVS 数据类型的条目，以及如何获取这些条目的相关信息。
 - :example:`security/nvs_encryption_hmac` 演示了如何用 HMAC 外设进行 NVS 加密，并通过 efuse 中的 HMAC 密钥生成加密密钥。
 - :example:`security/flash_encryption` 演示了如何进行 flash 加密，包括创建和使用 NVS 分区。
 

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

@@ -53,6 +53,10 @@
       - 演示了如何在 NVS flash 中使用 C 语言 API 读写整数数据类型。
     * - :example:`nvs_rw_value <storage/nvs/nvs_rw_value_cxx>`
       - 演示了如何在 NVS flash 中使用 C++ 语言 API 读写整数数据类型。
+    * - :example:`nvs_statistics <storage/nvs/nvs_statistics>`
+      - 演示了如何使用 C 风格 API 获取 NVS 使用情况统计信息，包括指定 NVS 分区中的空闲、已用、可用、总条目数、以及命名空间数量。
+    * - :example:`nvs_iteration <storage/nvs/nvs_iteration>`
+      - 演示了如何使用 C 风格 API 遍历特定（或任意）NVS 数据类型的条目，以及如何获取这些条目的相关信息。
     * - :example:`nvs_bootloader <storage/nvs/nvs_bootloader>`
       - 演示了如何使用引导加载程序代码中可用的 API 来读取 NVS 数据。
     * - :example:`nvsgen <storage/nvs/nvsgen>`

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

@@ -177,6 +177,22 @@ ESP-IDF :example:`storage/nvs` 目录下提供了数个代码示例：
 
   这个例子与 :example:`storage/nvs/nvs_rw_value` 完全一样，只是使用了 C++ 的 NVS 句柄类。
 
+:example:`storage/nvs/nvs_statistics`
+
+  该示例演示了如何获取并解读 NVS 使用情况统计信息：包括指定 NVS 分区中的空闲、已用、可用、总条目数、以及命名空间数量。
+
+  默认的 NVS 分区会在运行本示例前被擦除，以确保干净的运行环境。随后，会写入模拟的字符串类型数据。
+
+  在写入数据前后分别获取使用情况统计信息，并将两者的差异与新占用条目的预期值进行比较。
+
+:example:`storage/nvs/nvs_iteration`
+
+  该示例演示了如何遍历特定（或任意）NVS 数据类型的条目，以及如何获取这些条目的相关信息。
+
+  默认的 NVS 分区会在运行本示例前被擦除，以确保干净的运行环境。随后，会写入包含不同 NVS 整型数据类型的模拟数据。
+
+  之后，本示例会遍历各个数据类型以及通用的 ``NVS_TYPE_ANY`` 类型，并记录在每次遍历过程中获取到的信息。
+
 内部实现
 ---------