Merge branch 'feature/storage_nvs_bootloader' into 'master'

feat(storage/nvs): NVS bootloader support

See merge request espressif/esp-idf!31753

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

@@ -27,6 +27,7 @@ For information about storage security, please refer to :doc:`Storage Security <
     fatfsgen
     mass_mfg.rst
     nvs_flash
+    nvs_bootloader
     nvs_encryption
     nvs_partition_gen.rst
     nvs_partition_parse.rst
@@ -52,6 +53,8 @@ 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_bootloader <storage/nvs_bootloader>`
+      - Shows the use of the API available to the bootloader code to read NVS data.
     * - :example:`nvsgen <storage/nvsgen>`
       - Demonstrates how to use the Python-based NVS image generation tool to create an NVS partition image from the contents of a CSV file.
 

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

@@ -0,0 +1,31 @@
+NVS Bootloader
+==============
+
+:link_to_translation:`zh_CN:[中文]`
+
+Overview
+--------
+
+This guide provides an overview of the NVS functionality available for custom bootloader code, along with its limitations.
+
+Due to the constraints of the bootloader runtime environment, custom bootloader code cannot use the full NVS API directly. Instead, NVS provides a simplified API that offers read-only access to NVS data.
+
+The API supports reading all NVS datatypes except for blobs. One call to the API can read multiple NVS entries at once. Values can be read from different namespaces within the same NVS partition. The array of input-output structures serves as placeholders for the data read from NVS, with a fixed size of up to 8 bytes.
+
+To read string entries, the API requires the caller to provide a buffer and its size, due to the heap memory allocation restriction in the bootloader.
+
+Application Example
+-------------------
+
+You can find code examples in the :example:`storage` directory of ESP-IDF examples:
+
+:example:`storage/nvs_bootloader`
+
+This section demonstrates how to prepare data in the input-output structure for various data types, namespaces, and keys. It includes an example of reading string data from NVS.
+
+The example also shows how to check if a read operation was successful, or if there were inconsistencies in the data or if certain values were not found in NVS. The example prints the values (or error codes) returned by the API to the console.
+
+API Reference
+-------------
+
+.. include-build-file:: inc/nvs_bootloader.inc

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

@@ -37,6 +37,13 @@ Although not recommended, NVS can store tens of thousands of keys and NVS partit
     This option is available in the nvs_flash component of the menuconfig menu when SPIRAM is enabled and and :ref:`CONFIG_SPIRAM_USE` is set to ``CONFIG_SPIRAM_USE_CAPS_ALLOC``.
     .. note:: Using SPI-connected PSRAM slows down NVS API for integer operations by an approximate factor of 2.5.
 
+.. _nvs_bootloader:
+
+Use of NVS in Bootloader code
+-----------------------------
+
+The standard NVS API described in this guide is available to the running application. It is also possible to read data from NVS in the custom bootloader code. More information can be found in the :doc:`nvs_bootloader` guide.
+
 Keys and Values
 ^^^^^^^^^^^^^^^