Merge branch 'feat/simplify_storage_examples' into 'master'

feat(storage/fatfs): update fatfs examples

Closes IDF-5705

See merge request espressif/esp-idf!31174

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

@@ -105,7 +105,7 @@ The most supported file system, recommended for common applications - file/direc
 **Examples:**
 
 * :example:`storage/sd_card`: access the SD card which uses the FAT file system
-* :example:`storage/ext_flash_fatfs`: access the external flash chip which uses the FAT file system
+* :example:`storage/fatfs/ext_flash`: access the external flash chip which uses the FAT file system
 
 
 .. _spiffs-fs-section:

docs/en/api-guides/performance/speed.rst

@@ -301,9 +301,9 @@ Improving I/O Performance
 
 Using standard C library functions like ``fread`` and ``fwrite`` instead of platform-specific unbuffered syscalls such as ``read`` and ``write``, may result in slower performance.
 
-The ``fread`` and ``fwrite`` functions are designed for portability rather than speed, introducing some overhead due to their buffered nature. Check the example :example:`storage/fatfsgen` to see how to use these two functions.
+The ``fread`` and ``fwrite`` functions are designed for portability rather than speed, introducing some overhead due to their buffered nature. Check the example :example:`storage/fatfs/getting_started` to see how to use these two functions.
 
-In contrast, the ``read`` and ``write`` functions are standard POSIX APIs that can be used directly when working with FatFs through VFS, with ESP-IDF handling the underlying implementation. Check the example :example:`storage/perf_benchmark` to see how to use the two functions.
+In contrast, the ``read`` and ``write`` functions are standard POSIX APIs that can be used directly when working with FatFs through VFS, with ESP-IDF handling the underlying implementation. Check the example :example:`storage/fatfs/fs_operations` to see how to use the two functions.
 
 Additional tips are provided below, and further details can be found in :doc:`/api-reference/storage/fatfs`.
 

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

@@ -123,7 +123,7 @@ If you decide for any reason to use ``fatfs_create_rawflash_image`` (without wea
 
 The arguments of the function are as follows:
 
-#. partition - the name of the partition as defined in the partition table (e.g., :example_file:`storage/fatfsgen/partitions_example.csv`).
+#. partition - the name of the partition as defined in the partition table (e.g., :example_file:`storage/fatfs/fatfsgen/partitions_example.csv`).
 
 #. base_dir - the directory that will be encoded to FatFs partition and optionally flashed into the device. Beware that you have to specify the suitable size of the partition in the partition table.
 
@@ -139,7 +139,7 @@ For example::
 
 If FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool.py`` or a custom build system target.
 
-For an example, see :example:`storage/fatfsgen`.
+For an example, see :example:`storage/fatfs/fatfsgen`.
 
 
 .. _fatfs-partition-analyzer:

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

@@ -37,22 +37,15 @@ For information about storage security, please refer to :doc:`Storage Security <
     wear-levelling
     storage-security.rst
 
-.. list-table:: Code Examples for Storage API
+Examples
+--------
+
+.. list-table:: NVS API examples
     :widths: 25 75
     :header-rows: 0
 
     * - **Code Example**
       - **Description**
-    * - :doc:`fatfs`
-      -
-    * - :example:`wear_leveling <storage/wear_levelling>`
-      - Demonstrates using FATFS over wear leveling on internal flash.
-    * - :example:`ext_flash_fatfs <storage/ext_flash_fatfs>`
-      - Demonstrates using FATFS over wear leveling on external flash.
-    * - :example:`fatfsgen <storage/fatfsgen>`
-      - Demonstrates the capabilities of Python-based tooling for FATFS images available on host computers.
-    * - :doc:`nvs_flash`
-      -
     * - :example:`nvs_rw_blob <storage/nvs_rw_blob>`
       - Shows the use of the C-style API to read and write blob data types in NVS flash.
     * - :example:`nvs_rw_value <storage/nvs_rw_value>`
@@ -61,20 +54,59 @@ For information about storage security, please refer to :doc:`Storage Security <
       - Shows the use of the C++-style API to read and write integer data types in NVS flash.
     * - :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.
-    * - :doc:`spiffs`
-      -
+
+.. list-table:: Common Filesystem API
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **Code Example**
+      - **Description**
+    * - :example:`fatfs/getting_started <storage/fatfs/getting_started>`
+      - Demonstrates basic common file API (stdio.h) usage over internal flash using FATFS.
+    * - :example:`fatfs/fs_operations <storage/fatfs/fs_operations>`
+      - Demonstrates POSIX API for filesystem manipulation, such as moving, removing and renaming files.
+
+.. list-table:: FATFS API examples
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **Code Example**
+      - **Description**
+    * - :example:`fatfsgen <storage/fatfs/fatfsgen>`
+      - Demonstrates the capabilities of Python-based tooling for FATFS images available on host computers.
+    * - :example:`ext_flash_fatfs <storage/fatfs/ext_flash>`
+      - Demonstrates using FATFS over wear leveling on external flash.
+    * - :example:`wear_leveling <storage/wear_levelling>`
+      - Demonstrates using FATFS over wear leveling on internal flash.
+
+.. list-table:: SPIFFS API examples
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **Code Example**
+      - **Description**
     * - :example:`spiffs <storage/spiffs>`
       - Shows the use of the SPIFFS API to initialize the filesystem and work with files using POSIX functions.
     * - :example:`spiffsgen <storage/spiffsgen>`
       - Demonstrates the capabilities of Python-based tooling for SPIFFS images available on host computers.
-    * - :doc:`partition`
-      -
+
+.. list-table:: Partition API examples
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **Code Example**
+      - **Description**
     * - :example:`partition_api <storage/partition_api>`
       - Provides an overview of API functions to look up particular partitions, perform basic I/O operations, and use partitions via CPU memory mapping.
     * - :example:`parttool <storage/parttool>`
       - Demonstrates the capabilities of Python-based tooling for partition images available on host computers.
-    * - :doc:`vfs`
-      -
+
+.. list-table:: VFS related examples
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **Code Example**
+      - **Description**
     * - :example:`littlefs <storage/littlefs>`
       - Shows the use of the LittleFS component to initialize the filesystem and work with a file using POSIX functions.
     * - :example:`semihost_vfs <storage/semihost_vfs>`

docs/zh_CN/api-guides/performance/speed.rst

@@ -301,9 +301,9 @@ ESP-IDF 支持动态 :doc:`/api-reference/system/intr_alloc` 和中断抢占。
 
 使用标准 C 库函数，如 ``fread`` 和 ``fwrite``，相较于使用平台特定的不带缓冲系统调用，如 ``read`` 和 ``write``，可能会导致 I/O 性能下降。
 
-``fread`` 与 ``fwrite`` 函数是为可移植性而设计的，而非速度，其缓冲性质会引入一些额外的开销。关于如何使用这两个函数，请参考示例 :example:`storage/fatfsgen`。
+``fread`` 与 ``fwrite`` 函数是为可移植性而设计的，而非速度，其缓冲性质会引入一些额外的开销。关于如何使用这两个函数，请参考示例 :example:`storage/fatfs/getting_started`。
 
-与之相比，``read`` 与 ``write`` 函数是标准的 POSIX API，可直接通过 VFS 处理 FatFs，由 ESP-IDF 负责底层实现。关于如何使用这两个函数，请参考示例 :example:`storage/perf_benchmark`。
+与之相比，``read`` 与 ``write`` 函数是标准的 POSIX API，可直接通过 VFS 处理 FatFs，由 ESP-IDF 负责底层实现。关于如何使用这两个函数，请参考示例 :example:`storage/fatfs/fs_operations`。
 
 下面提供了一些提示，更多信息请见 :doc:`/api-reference/storage/fatfs`。
 

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

@@ -123,7 +123,7 @@ FatFs 分区生成器
 
 该函数的参数如下：
 
-#. partition - 分区的名称，需要在分区表中定义（如 :example_file:`storage/fatfsgen/partitions_example.csv`）。
+#. partition - 分区的名称，需要在分区表中定义（如 :example_file:`storage/fatfs/fatfsgen/partitions_example.csv`）。
 
 #. base_dir - 目录名称，该目录会被编码为 FatFs 分区，也可以选择将其被烧录进设备。但注意必须在分区表中指定合适的分区大小。
 
@@ -139,7 +139,7 @@ FatFs 分区生成器
 
 没有指定 FLASH_IN_PROJECT 时也可以生成分区镜像，但是用户需要使用 ``esptool.py`` 或自定义的构建系统目标对其手动烧录。
 
-相关示例请查看 :example:`storage/fatfsgen`。
+相关示例请查看 :example:`storage/fatfs/fatfsgen`。
 
 
 .. _fatfs-partition-analyzer:

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

@@ -37,44 +37,76 @@
    wear-levelling
    storage-security.rst
 
+示例
+----
+
 .. list-table:: 存储 API 相关例程
     :widths: 25 75
     :header-rows: 0
 
     * - **例程**
       - **描述**
-    * - :doc:`fatfs`
-      -
-    * - :example:`wear_leveling <storage/wear_levelling>`
-      - 演示了如何在内部 flash 上使用 FATFS 磨损均衡。
-    * - :example:`ext_flash_fatfs <storage/ext_flash_fatfs>`
-      - 演示了如何在外部 flash 上使用 FATFS 磨损均衡。
-    * - :example:`fatfsgen <storage/fatfsgen>`
-      - 演示了在主机计算机上使用 Python 工具生成 FATFS 镜像的功能。
-    * - :doc:`nvs_flash`
-      -
     * - :example:`nvs_rw_blob <storage/nvs_rw_blob>`
       - 演示了如何在 NVS flash 中使用 C 语言 API 读写 blob 数据类型。
     * - :example:`nvs_rw_value <storage/nvs_rw_value>`
       - 演示了如何在 NVS flash 中使用 C 语言 API 读写整数数据类型。
-    * - :example:`nvs_rw_value_cxx <storage/nvs_rw_value_cxx>`
+    * - :example:`nvs_rw_value <storage/nvs_rw_value>`
       - 演示了如何在 NVS flash 中使用 C++ 语言 API 读写整数数据类型。
     * - :example:`nvsgen <storage/nvsgen>`
       - 演示了如何使用基于 Python 的 NVS 镜像生成工具，根据 CSV 文件内容创建 NVS 分区镜像。
-    * - :doc:`spiffs`
-      -
+
+.. list-table:: 常用文件系统 API
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **代码示例**
+      - **描述**
+    * - :example:`fatfs/getting_started <storage/fatfs/getting_started>`
+      - 演示了如何使用 FATFS 库在内部 flash 上应用标准文件 API (stdio.h)。
+    * - :example:`fatfs/fs_operations <storage/fatfs/fs_operations>`
+      - 演示了如何使用 POSIX API 进行文件系统操作，如移动、删除和重命名文件等。
+
+.. list-table:: FATFS API 示例
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **代码示例**
+      - **描述**
+    * - :example:`fatfsgen <storage/fatfs/fatfsgen>`
+      - 演示了在主机上使用 Python 工具生成 FATFS 镜像的相关功能。
+    * - :example:`ext_flash_fatfs <storage/fatfs/ext_flash>`
+      - 演示了在外部 flash 上使用带有磨损均衡功能的 FATFS。
+    * - :example:`wear_leveling <storage/wear_levelling>`
+      - 演示了在内部 flash 上使用带有磨损均衡功能的 FATFS。
+
+.. list-table:: SPIFFS API 示例
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **代码示例**
+      - **描述**
     * - :example:`spiffs <storage/spiffs>`
       - 演示了如何使用 SPIFFS API 初始化文件系统，并使用 POSIX 函数处理文件。
     * - :example:`spiffsgen <storage/spiffsgen>`
       - 演示了在主机计算机上使用 Python 工具生成 SPIFFS 镜像的功能。
-    * - :doc:`partition`
-      -
+
+.. list-table:: 分区 API 示例
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **代码示例**
+      - **描述**
     * - :example:`partition_api <storage/partition_api>`
       - 介绍了用于查找特定分区、执行基本 I/O 操作以及通过 CPU 内存映射使用分区的 API 函数。
     * - :example:`parttool <storage/parttool>`
       - 演示了在主机计算机上使用 Python 工具生成分区镜像的功能。
-    * - :doc:`vfs`
-      -
+
+.. list-table:: VFS 相关示例
+    :widths: 25 75
+    :header-rows: 0
+
+    * - **代码示例**
+      - **描述**
     * - :example:`littlefs <storage/littlefs>`
       - 演示了如何使用 LittleFS 组件初始化文件系统，并使用 POSIX 函数处理文件。
     * - :example:`semihost_vfs <storage/semihost_vfs>`

examples/storage/.build-test-rules.yml

@@ -19,29 +19,6 @@ examples/storage/emmc:
     - if: IDF_TARGET == "esp32s3"
       reason: only support on esp32s3
 
-examples/storage/ext_flash_fatfs:
-  depends_components:
-    - fatfs
-    - vfs
-    - spi_flash
-    - driver
-  disable:
-    - if: IDF_TARGET in ["esp32p4", "esp32c5", "esp32c61"]
-      temporary: true
-      reason: not supported on p4 and c5  # TODO: [ESP32C5] IDF-8715, [ESP32C61] IDF-9314
-  disable_test:
-    - if: IDF_TARGET not in ["esp32"]
-      temporary: true
-      reason: lack of runners
-
-examples/storage/fatfsgen:
-  depends_components:
-    - fatfs
-    - vfs
-  disable_test:
-    - if: IDF_TARGET != "esp32"
-      reason: only one target needed
-
 examples/storage/nvs_rw_blob:
   depends_components:
     - nvs_flash

examples/storage/README.md

@@ -7,10 +7,11 @@ This directory contains a range of examples ESP-IDF projects. These are intended
 
 The examples are grouped into sub-directories by category. Each category directory contains one or more example projects:
 
+* `fatfs_basic` minimal example of FatFS usage on SPI FLASH
+* `fatfs_advanced` example demonstrates how to use advanced features for working with FatFS such as automatic partition generation
 * `custom_flash_driver` example demonstrates how to implement your own flash chip driver by overriding the default driver.
 * `emmc` example demonstrates how to use an eMMC chip with an ESP device.
 * `ext_flash_fatfs` example demonstrates how to use FATFS partition with external SPI FLASH chip.
-* `fatfsgen` example demonstrates how to use FATFS partition
 * `nvs_rw_blob` example demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP module restarts.
 * `nvs_rw_value` example demonstrates how to read and write a single integer value using NVS.
 * `nvs_rw_value_cxx` example demonstrates how to read and write a single integer value using NVS (it uses the C++ NVS handle API).

examples/storage/fatfs/.build-test-rules.yml

@@ -0,0 +1,24 @@
+# Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
+
+examples/storage/fatfs:
+  depends_components:
+    - fatfs
+    - vfs
+  disable_test:
+    - if: IDF_TARGET != "esp32"
+      reason: only one target needed
+
+examples/storage/fatfs/ext_flash:
+  depends_components:
+    - fatfs
+    - vfs
+    - spi_flash
+    - driver
+  disable:
+    - if: IDF_TARGET in ["esp32p4", "esp32c5", "esp32c61"]
+      temporary: true
+      reason: not supported on p4 and c5  # TODO: [ESP32C5] IDF-8715, [ESP32C61] IDF-9314
+  disable_test:
+    - if: IDF_TARGET not in ["esp32"]
+      temporary: true
+      reason: lack of runners

examples/storage/ext_flash_fatfs/CMakeLists.txt → examples/storage/fatfs/ext_flash/CMakeLists.txt

@@ -4,4 +4,4 @@ cmake_minimum_required(VERSION 3.16)
 
 # external SPI flash driver not currently supported for ESP32-S2
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-project(ext_flash_fatfs)
+project(fatfs_ext_flash)

examples/storage/ext_flash_fatfs/README.md → examples/storage/fatfs/ext_flash/README.md

@@ -5,7 +5,7 @@
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 
-This example is similar to the [wear levelling](../wear_levelling/README.md) example, except that it uses an external SPI Flash chip. This can be useful if you need to add more storage to a module with only 4 MB flash size.
+This example is similar to the [wear levelling](../../wear_levelling/README.md) example, except that it uses an external SPI Flash chip. This can be useful if you need to add more storage to a module with only 4 MB flash size.
 
 The flow of the example is as follows:
 

examples/storage/fatfs/ext_flash/main/CMakeLists.txt

@@ -0,0 +1 @@
+idf_component_register(SRCS "fatfs_ext_flash_example_main.c")

examples/storage/ext_flash_fatfs/main/ext_flash_fatfs_example_main.c → examples/storage/fatfs/ext_flash/main/fatfs_ext_flash_example_main.c

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
 /* Example of FAT filesystem on external Flash.
    This example code is in the Public Domain (or CC0 licensed, at your option.)
 

examples/storage/ext_flash_fatfs/pytest_ext_flash_fatfs.py → examples/storage/fatfs/ext_flash/pytest_fatfs_ext_flash.py

@@ -1,7 +1,5 @@
 # SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Unlicense OR CC0-1.0
-
-
 import pytest
 from pytest_embedded import Dut
 

examples/storage/fatfs/fatfsgen/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(fatfs_fatfsgen)