Merge branch 'docs/update_application_examples_storage' into 'master'

docs: update application examples for storage component See merge request espressif/esp-idf!33600
2026-05-19 23:45:28 +02:00 · 2024-10-24 11:20:19 +08:00
parent 755d3a2fbe c0417422c5
commit 5dda8a3211
17 changed files with 82 additions and 33 deletions
@@ -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 参考
 ------------------------
@@ -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 镜像。
@@ -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 固件。
@@ -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
 ------------------
@@ -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``
 ^^^^^^^^^^^^
@@ -221,6 +221,7 @@ IDF 定义了多个可供应用程序使用的 VFS 设备。这些设备包括

 - :example:`system/select` 演示了如何使用 ``select()`` 函数进行同步 I/O 多路复用，使用 UART 和套接字文件描述符，并将二者配置为回环模式，以接收来自其他任务发送的消息。

+- :example:`storage/semihost_vfs` 演示了如何使用半托管 VFS 驱动程序，包括注册主机目录、将 UART 的 stdout 重定向到主机上的文件，并读取和打印文本文件的内容。

 API 参考
 -------------
@@ -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 参考
 ------------------------