Merge branch 'docs/update_application_examples_storage' into 'master'

docs: update application examples for storage component

See merge request espressif/esp-idf!33600

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

@@ -113,7 +113,7 @@ The most supported file system, recommended for common applications - file/direc
 SPIFFS
 ----------------------
 
-SPIFFS is a file system providing certain level of power-off safety (see repair-after-restart function :cpp:func:`esp_spiffs_check`) and built-in wear levelling. It tend to become slow down when exceeding around 70% of dedicated partition size due to its garbage collector implementation, and it also doesn't support directories. It is useful for applications depending only on few files (possibly large) and requiring high level of consistency. Generally, the SPIFFS needs less RAM resources than FatFS and supports flash chips up to 128MB in size. Please keep in mind the SPIFFS is not being developed and maintained anymore, so consider precisely whether its advantages for your project really prevail over the other file systems.
+SPIFFS is a file system providing certain level of power-off safety (see repair-after-restart function :cpp:func:`esp_spiffs_check`) and built-in wear levelling. It tends to slow down when exceeding around 70% of the dedicated partition size due to its garbage collector implementation, and also doesn't support directories. It is useful for applications depending only on few files (possibly large) and requiring high level of consistency. Generally, the SPIFFS needs less RAM resources than FatFS and supports flash chips up to 128 MB in size. Please keep in mind the SPIFFS is not being developed and maintained anymore, so consider precisely whether its advantages for your project really prevail over the other file systems.
 
 **Related documents:**
 
@@ -122,7 +122,7 @@ SPIFFS is a file system providing certain level of power-off safety (see repair-
 
 **Examples:**
 
-* :example:`storage/spiffs`: SPIFFS examples
+* :example:`storage/spiffs` demonstrates how to use SPIFFS.
 
 
 .. _littlefs-fs-section:
@@ -143,7 +143,7 @@ LittleFS is available as external component in the ESP Registry, see `LittleFS c
 
 **Examples:**
 
-* :example:`storage/littlefs`: ESP-IDF LittleFS example
+* :example:`storage/littlefs` demonstrates how to use LittleFS.
 
 .. _nvs-fs-section:
 
@@ -177,10 +177,10 @@ Points to keep in mind when developing NVS related code:
 
 **Examples:**
 
-- Write a single integer value: :example:`storage/nvs_rw_value`
-- Write a blob: :example:`storage/nvs_rw_blob`
-- Encryption keys generation: :example:`security/nvs_encryption_hmac`
-- Flash encryption workflow including NVS partition: :example:`security/flash_encryption`
+- :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:`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.
 
 
 File handling design considerations
@@ -205,5 +205,5 @@ Encrypting partitions
 Given storage security scheme and the {IDF_TARGET_NAME} chips design result into a few implications which may not be fully obvious in the main documents:
 
 * The Flash encryption applies only to the main SPI Flash memory, due to its cache module design (all the "transparent" encryption APIs run over this cache). This implies that external flash partitions cannot be encrypted using the native Flash Encryption means.
-* External partition encryption can be deployed by implementing custom encrypt/decrypt code in appropriate driver APIs - either by implementing own SPI flash driver (see :example:`storage/custom_flash_driver`) or by customising higher levels in the driver stack, for instance by providing own :ref:`FatFS disk IO layer <fatfs-diskio-layer>`.
+* External partition encryption can be deployed by implementing custom encrypt/decrypt code in appropriate driver APIs - either by implementing own SPI flash driver (see :example:`storage/custom_flash_driver`) or by customizing higher levels in the driver stack, for instance by providing own :ref:`FatFS disk IO layer <fatfs-diskio-layer>`.
 

docs/en/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst

@@ -64,7 +64,7 @@ Steps For Creating Custom Chip Drivers and Overriding the ESP-IDF Default Driver
             .get_chip_caps = spi_flash_chip_eon_get_caps,
          };
 
-   - You also can see how to implement this in the example :example:`storage/custom_flash_driver`.
+   - You also can see how to implement this in the example :example:`storage/custom_flash_driver`. This example demonstrates how to override the default chip driver list.
 
 4. Write a new ``CMakeLists.txt`` file for the ``custom_chip_driver`` component, including an additional line to add a linker dependency from ``spi_flash`` to ``custom_chip_driver``::
 
@@ -80,8 +80,3 @@ Steps For Creating Custom Chip Drivers and Overriding the ESP-IDF Default Driver
 5. The ``linker.lf`` is used to put every chip driver that you are going to use whilst cache is disabled into internal RAM. See :doc:`/api-guides/linker-script-generation` for more details. Make sure this file covers all the source files that you add.
 
 6. Build your project, and you will see the new flash driver is used.
-
-Example
--------
-
-See also :example:`storage/custom_flash_driver`.

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

@@ -182,6 +182,14 @@ The FATFS component supports FAT12, FAT16, and FAT32 file system types. The file
 
 Please refer :doc:`File System Considerations <../../api-guides/file-system-considerations>` for further details.
 
+Application Examples
+--------------------
+
+- :example:`storage/fatfs/getting_started` demonstrates the minimal setup required to store persistent data on SPI flash using the FatFS, including mounting the file system, opening a file, performing basic read and write operations, and unmounting the file system.
+
+- :example:`storage/fatfs/fs_operations` demonstrates more advanced FatFS operations, including reading and writing files, creating, moving, and deleting files and directories, and inspecting file details.
+
+- :example:`storage/fatfs/ext_flash` demonstrates how to operate an external SPI flash formatted with FatFS, including initializing the SPI bus, configuring the flash chip, registering it as a partition, and performing read and write operations.
 
 High-level API Reference
 ------------------------

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

@@ -219,3 +219,8 @@ Date and Time in FAT File System
 The FAT file system protocol used by ESP-IDF does not preserve the date or time on the chips' media, so all the images extracted from the device have the same default timestamp for all the FAT-specified date-time fields (creation and the last modification timestamp as well as creation, last modification and last access dates).
 
 There are a couple of fields in the SFN entry describing time, such as **DIR_CrtTime** and **DIR_WrtTime**. Some fields are ignored by the FAT implementation used by ESP-IDF (see the file ``entry.py``). However, changes in the fields **DIR_WrtTime** and **DIR_WrtDate** are preserved in the chip. Both time and data entry are 16-bit, where the granularity of the time is 2 seconds.
+
+Application Examples
+--------------------
+
+- :example:`storage/fatfs/fatfsgen` demonstrates how to use the FatFS partition generation tool to automatically create a FatFS image from a host folder during the building process.

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

@@ -24,6 +24,16 @@ This component provides API functions to enumerate partitions found in the parti
 - :cpp:func:`esp_partition_find_first` is a convenience function which returns the structure describing the first partition found by :cpp:func:`esp_partition_find`.
 - :cpp:func:`esp_partition_read`, :cpp:func:`esp_partition_write`, :cpp:func:`esp_partition_erase_range` are equivalent to :cpp:func:`esp_flash_read`, :cpp:func:`esp_flash_write`, :cpp:func:`esp_flash_erase_region`, but operate within partition boundaries.
 
+Application Examples
+--------------------
+
+- :example:`storage/partition_api/partition_ops` demonstrates how to perform read, write, and erase operations on a partition table.
+
+- :example:`storage/parttool` demonstrates how to use the partitions tool to perform operations such as reading, writing, erasing partitions, retrieving partition information, and dumping the entire partition table.
+
+- :example:`storage/partition_api/partition_find` demonstrates how to search the partition table and return matching partitions based on set constraints such as partition type, subtype, and label/name.
+
+- :example:`storage/partition_api/partition_mmap` demonstrates how to configure the MMU, map a partition into memory address space for read operations, and verify the data written and read.
 
 See Also
 --------

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

@@ -29,10 +29,16 @@ Host layer driver(s) implement the protocol layer driver by supporting these fun
     :align: center
 
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
+.. list::
+
+    :SOC_SDMMC_HOST_SUPPORTED: - :example:`storage/sd_card/sdmmc` demonstrates how to operate an SD card formatted with the FatFS file system via the SDMMC interface.
+
+    :SOC_SDMMC_HOST_SUPPORTED: - :example:`storage/emmc` demonstrates how to operate an eMMC chip formatted with the FatFS file system via the SDMMC interface.
+
+    :SOC_GPSPI_SUPPORTED: - :example:`storage/sd_card/sdspi` demonstrates how to operate an SD card formatted with the FatFS file system via the SPI interface.
 
 Protocol Layer API
 ------------------

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

@@ -65,7 +65,7 @@ There are cases where the contents of the base directory itself is generated at
 
     spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)
 
-For an example, see :example:`storage/spiffsgen`.
+For an example, see :example:`storage/spiffsgen`. This example demonstrates how to use the SPIFFS image generation tool to automatically create an SPIFFS image from a host folder during building.
 
 ``mkspiffs``
 ^^^^^^^^^^^^

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

@@ -221,6 +221,7 @@ Application Examples
 
 - :example:`system/select` demonstrates how to use synchronous I/O multiplexing with the ``select()`` function, using UART and socket file descriptors, and configuring both to act as loopbacks to receive messages sent from other tasks.
 
+- :example:`storage/semihost_vfs` demonstrates how to use the semihosting VFS driver, including registering a host directory, redirecting stdout from UART to a file on the host, and reading and printing the content of a text file.
 
 API Reference
 -------------

docs/en/api-reference/storage/wear-levelling.rst

@@ -6,10 +6,10 @@ See Also
 - :doc:`./fatfs`
 - :doc:`../../api-guides/partition-tables`
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-An example that combines the wear levelling driver with the FATFS library is provided in the :example:`storage/wear_levelling` directory. This example initializes the wear levelling driver, mounts FatFs partition, as well as writes and reads data from it using POSIX and C library APIs. See :example_file:`storage/wear_levelling/README.md` for more information.
+- :example:`storage/wear_levelling` demonstrates how to use the wear levelling library and FatFS library to store files in a partition, as well as write and read data from these files using POSIX and C library APIs.
 
 High-level API Reference
 ------------------------

docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst

@@ -64,7 +64,7 @@
             .get_chip_caps = spi_flash_chip_eon_get_caps,
          };
 
-   - 也可以在示例 :example:`storage/custom_flash_driver` 中查看如何实现此功能。
+   - 也可以在示例 :example:`storage/custom_flash_driver` 中查看如何实现此功能。该示例演示了如何覆盖默认芯片驱动列表。
 
 4. 为 ``custom_chip_driver`` 组件编写一个新的 ``CMakeLists.txt`` 文件，其中包含额外的一行，添加了从 ``spi_flash`` 到 ``custom_chip_driver`` 的链接依赖项::
 
@@ -80,8 +80,3 @@
 5. ``linker.lf`` 用于在禁用缓存时，把要使用的每个芯片驱动程序都放入内部 RAM 中。详情请参阅 :doc:`/api-guides/linker-script-generation`。请确保此文件包含所有添加的源文件。
 
 6. 构建你的项目，将会看到新的 flash 驱动程序已投入使用。
-
-示例
-----
-
-参考 :example:`storage/custom_flash_driver`。

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

@@ -157,7 +157,6 @@ FatFs 分区分析器
 
 生成文件夹结构之前，参数 --verbose 将根据 FatFs 镜像的引导扇区在终端打印详细信息。
 
-
 FATFS 最小分区大小及限制
 ------------------------
 
@@ -183,6 +182,14 @@ FATFS 组件支持 FAT12、FAT16 和 FAT32 文件系统类型。文件系统类
 
 更多详情请参考 :doc:`文件系统注意事项 <../../api-guides/file-system-considerations>`。
 
+应用示例
+-----------------
+
+- :example:`storage/fatfs/getting_started` 演示了如何使用 FatFS 在 SPI flash 上存储永久数据的基本设置，包括挂载文件系统、打开文件、执行基本的读写操作以及卸载文件系统。
+
+- :example:`storage/fatfs/fs_operations` 演示了更全面的 FatFS 操作，包括读取和写入文件、创建、移动和删除文件及目录，以及检查文件详细信息。
+
+- :example:`storage/fatfs/ext_flash` 演示了如何操作使用 FatFS 格式化的外部 SPI flash，包括初始化 SPI 总线、配置 flash、将其注册为分区以及执行读写操作。
 
 高级 API 参考
 ------------------------

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

@@ -219,3 +219,8 @@ FAT 文件系统中的日期和时间
 ESP-IDF 使用的 FAT 文件系统协议不保留芯片介质上的日期或时间，因此，从设备中提取的所有映像都具有相同的默认时间戳，这个时间戳会应用到所有 FAT 相关的日期和时间字段上，包括创建、最后修改时间戳，以及创建、最后修改和最后访问日期。
 
 SFN 条目中有几个描述时间的字段，如 **DIR_CrtTime** 和 **DIR_WrtTime**。ESP-IDF 的 FAT 实现过程会忽略一些字段（参见文件 ``entry.py``），然而 **DIR_WrtTime** 和 **DIR_WrtDate** 字段的更改会保留在芯片中。时间和数据条目都是 16 位的，其中时间粒度为 2 秒。
+
+应用示例
+---------------
+
+- :example:`storage/fatfs/fatfsgen` 演示了如何在构建过程中使用 FatFS 分区生成工具从主机文件夹自动创建 FatFS 镜像。

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

@@ -24,9 +24,19 @@ ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导加载
 - :cpp:func:`esp_partition_find_first`：返回描述 :cpp:func:`esp_partition_find` 中找到的第一个分区的结构；
 - :cpp:func:`esp_partition_read`、:cpp:func:`esp_partition_write` 和 :cpp:func:`esp_partition_erase_range` 等同于 :cpp:func:`esp_flash_read`、:cpp:func:`esp_flash_write` 和 :cpp:func:`esp_flash_erase_region`，但在分区边界内执行。
 
+应用示例
+-------------
 
-另请参考
-------------
+- :example:`storage/partition_api/partition_ops` 演示了如何对分区表执行读、写和擦除操作。
+
+- :example:`storage/parttool` 演示了如何使用分区工具执行读、写、擦除分区、检索分区信息和转储整个分区表等操作。
+
+- :example:`storage/partition_api/partition_find` 演示了如何搜索分区表，并根据分区类型、子类型和标签/名称等约束条件返回匹配的分区。
+
+- :example:`storage/partition_api/partition_mmap` 演示了如何配置 MMU，将分区映射到内存地址空间以进行读操作，并验证写入和读取的数据。
+
+其他资源
+-------------
 
 - :doc:`../../api-guides/partition-tables`
 - :doc:`../system/ota` 提供了高层 API 用于更新存储在 flash 中的 app 固件。

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

@@ -32,7 +32,13 @@ SD/SDIO/MMC 驱动支持 SD 存储器、SDIO 卡和 eMMC 芯片。这是一个
 应用示例
 -------------------
 
-ESP-IDF :example:`storage/sd_card` 目录下提供了 SDMMC 驱动与 FatFs 库组合使用的示例，演示了先初始化卡，然后使用 POSIX 和 C 库 API 向卡读写数据。请参考示例目录下 README.md 文件，查看更多详细信息。
+.. list::
+
+    :SOC_SDMMC_HOST_SUPPORTED: - :example:`storage/sd_card/sdmmc` 演示了如何通过 SDMMC 接口操作使用 FatFS 文件系统格式化的 SD 卡。
+
+    :SOC_SDMMC_HOST_SUPPORTED: - :example:`storage/emmc` 演示了如何通过 SDMMC 接口操作使用 FatFS 文件系统格式化的 eMMC 芯片。
+
+    :SOC_GPSPI_SUPPORTED: - :example:`storage/sd_card/sdspi` 演示了如何通过 SPI 接口操作使用 FatFS 文件系统格式化的 SD 卡。
 
 协议层 API
 ------------------

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

@@ -65,7 +65,7 @@ SPIFFS 是一个用于 SPI NOR flash 设备的嵌入式文件系统，支持磨
 
     spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)
 
-请参考 :example:`storage/spiffsgen`，查看示例。
+请参考 :example:`storage/spiffsgen`，查看示例。该示例演示了如何使用 SPIFFS 镜像生成工具在构建过程中自动从主机文件夹创建 SPIFFS 镜像。
 
 ``mkspiffs``
 ^^^^^^^^^^^^

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

@@ -221,6 +221,7 @@ IDF 定义了多个可供应用程序使用的 VFS 设备。这些设备包括
 
 - :example:`system/select` 演示了如何使用 ``select()`` 函数进行同步 I/O 多路复用，使用 UART 和套接字文件描述符，并将二者配置为回环模式，以接收来自其他任务发送的消息。
 
+- :example:`storage/semihost_vfs` 演示了如何使用半托管 VFS 驱动程序，包括注册主机目录、将 UART 的 stdout 重定向到主机上的文件，并读取和打印文本文件的内容。
 
 API 参考
 -------------

docs/zh_CN/api-reference/storage/wear-levelling.rst

@@ -9,7 +9,7 @@
 应用示例
 -------------------
 
-:example:`storage/wear_levelling` 中提供了一款磨损均衡驱动与 FatFs 库结合使用的示例。该示例初始化磨损均衡驱动，挂载 FAT 文件系统分区，并使用 POSIX（可移植操作系统接口）和 C 库 API 从中写入和读取数据。如需了解更多信息，请参考 :example_file:`storage/wear_levelling/README.md`。
+:example:`storage/wear_levelling` 演示了如何使用磨损均衡库和 FatFS 库在分区中存储文件，并使用 POSIX 和 C 库 API 从中写入和读取数据。
 
 高级 API 参考
 ------------------------