Merge branch 'doc/add_Chinese_translation_to_rst_files_in_storage_folder_1st_batch' into 'master'
Doc/add chinese translation to rst files in storage folder 1st batch See merge request espressif/esp-idf!5613
This commit is contained in:
Krzysztof Budzynski
commit
67960020cd
7 changed files with 284 additions and 4 deletions
|
|
@ -1,6 +1,8 @@
|
|||
FAT Filesystem Support
|
||||
======================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
ESP-IDF uses the `FatFs <http://elm-chan.org/fsw/ff/00index_e.html>`_ library to work with FAT filesystems. FatFs resides in the ``fatfs`` component. Although the library can be used directly, many of its features can be accessed via VFS, using the C standard library and POSIX API functions.
|
||||
|
||||
Additionally, FatFs has been modified to support the runtime pluggable disk I/O layer. This allows mapping of FatFs drives to physical disks at runtime.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
Storage API
|
||||
***********
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
SPIFFS Filesystem
|
||||
=================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1,83 @@
|
|||
.. include:: ../../../en/api-reference/storage/fatfs.rst
|
||||
FAT 文件系统
|
||||
======================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
ESP-IDF 使用 `FatFs <http://elm-chan.org/fsw/ff/00index_e.html>`_ 库来实现 FAT 文件系统。FatFs 库位于 ``fatfs`` 组件中，您可以直接使用，也可以借助 C 标准库和 POSIX API 通过 VFS（虚拟文件系统）使用 FatFs 库的大多数功能。
|
||||
|
||||
此外，我们对 FatFs 库进行了扩展，新增了支持可插拔磁盘 I/O 调度层，从而允许在运行时将 FatFs 驱动映射到物理磁盘。
|
||||
|
||||
FatFs 与 VFS 配合使用
|
||||
----------------------------
|
||||
|
||||
:component_file:`fatfs/vfs/esp_vfs_fat.h` 头文件定义了连接 FatFs 和 VFS 的函数。
|
||||
|
||||
函数 :cpp:func:`esp_vfs_fat_register` 分配一个 ``FATFS`` 结构，并在 VFS 中注册特定路径前缀。如果文件路径以此前缀开头，则对此文件的后续操作将转至 FatFs API。函数 :cpp:func:`esp_vfs_fat_unregister_path` 删除在 VFS 中的注册，并释放 ``FATFS`` 结构。
|
||||
|
||||
多数应用程序在使用 ``esp_vfs_fat_`` 函数时，采用如下步骤：
|
||||
|
||||
1. 调用 :cpp:func:`esp_vfs_fat_register`，指定：
|
||||
|
||||
- 挂载文件系统的路径前缀（例如，``"/sdcard"`` 或 ``"/spiflash"``）
|
||||
- FatFs 驱动编号
|
||||
- 一个用于接收指向 ``FATFS`` 结构指针的变量
|
||||
|
||||
2. 调用 :cpp:func:`ff_diskio_register` 为上述步骤中的驱动编号注册磁盘 I/O 驱动；
|
||||
|
||||
3. 调用 FatFs 函数 ``f_mount``，或 ``f_fdisk``， ``f_mkfs``，并使用与传递到 :cpp:func:`esp_vfs_fat_register` 相同的驱动编号挂载文件系统。请参考 `FatFs 文档 <http://www.elm-chan.org/fsw/ff/doc/mount.html>`_，查看更多信息；
|
||||
|
||||
4. 调用 C 标准库和 POSIX API 对路径中带有步骤 1 中所述前缀的文件（例如，``"/sdcard/hello.txt"``）执行打开、读取、写入、擦除、复制等操作。
|
||||
|
||||
5. 您可以选择直接调用 FatFs 库函数，但需要使用没有 VFS 前缀的路径（例如，``"/hello.txt"``）；
|
||||
|
||||
6. 关闭所有打开的文件；
|
||||
|
||||
7. 调用 ``f_mount`` 并使用 NULL ``FATFS*`` 参数为与上述编号相同的驱动卸载文件系统；
|
||||
|
||||
8. 调用 FatFs 函数 :cpp:func:`ff_diskio_register` 并使用 NULL ``ff_diskio_impl_t*`` 参数和相同的驱动编号来释放注册的磁盘 I/O 驱动。
|
||||
|
||||
9. 调用 :cpp:func:`esp_vfs_fat_unregister_path` 并使用文件系统挂载的路径将 FatFs 从 NVS 中移除，并释放步骤 1 中分配的 FatFs 结构。
|
||||
|
||||
``esp_vfs_fat_sdmmc_mount`` 和 ``esp_vfs_fat_sdmmc_unmount`` 这两个便捷函数对上述步骤进行了封装，并加入对 SD 卡初始化的处理，非常便捷。我们将在下一章节详细介绍这两个函数。
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_register
|
||||
.. doxygenfunction:: esp_vfs_fat_unregister_path
|
||||
|
||||
|
||||
FatFs 与 VFS 和 SD 卡配合使用
|
||||
---------------------------------
|
||||
|
||||
:component_file:`fatfs/vfs/esp_vfs_fat.h` 头文件定义了两个便捷函数 :cpp:func:`esp_vfs_fat_sdmmc_mount` 和 :cpp:func:`esp_vfs_fat_sdmmc_unmount`。这两个函数分别执行上一章节的步骤 1-3 和步骤 7-9，并初始化 SD 卡，但仅提供有限的错误处理功能。我们鼓励开发人员查看源代码并将更多高级功能集成到产品应用中。
|
||||
|
||||
:cpp:func:`esp_vfs_fat_sdmmc_unmount` 函数用于卸载文件系统并释放从 :cpp:func:`esp_vfs_fat_sdmmc_mount` 函数获取的资源。
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
|
||||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||||
:members:
|
||||
.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
|
||||
|
||||
|
||||
FatFs 与 VFS 配合使用（只读模式下）
|
||||
--------------------------------------
|
||||
|
||||
:component_file:`fatfs/vfs/esp_vfs_fat.h` 头文件也定义了两个便捷函数 :cpp:func:`esp_vfs_fat_rawflash_mount` 和 :cpp:func:`esp_vfs_fat_rawflash_unmount`。上述两个函数分别对 FAT 只读分区执行步骤 1-3 和步骤 7-9。有些数据分区仅在工厂时写入一次，之后在整个硬件生命周期内都不会再有任何改动。利用上述两个函数处理这种数据分区非常方便。
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_rawflash_mount
|
||||
.. doxygenfunction:: esp_vfs_fat_rawflash_unmount
|
||||
|
||||
|
||||
FatFs 磁盘 I/O 层
|
||||
-------------------
|
||||
|
||||
我们对 FatFs API 函数进行了扩展，实现了运行期间注册磁盘 I/O 驱动。
|
||||
|
||||
上述 API 为 SD/MMC 卡提供了磁盘 I/O 函数实现方式，可使用 :cpp:func:`ff_diskio_register_sdmmc` 注册指定的 FatFs 驱动编号。
|
||||
|
||||
.. doxygenfunction:: ff_diskio_register
|
||||
.. doxygenstruct:: ff_diskio_impl_t
|
||||
:members:
|
||||
.. doxygenfunction:: ff_diskio_register_sdmmc
|
||||
.. doxygenfunction:: ff_diskio_register_wl_partition
|
||||
.. doxygenfunction:: ff_diskio_register_raw_partition
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1,20 @@
|
|||
.. include:: ../../../en/api-reference/storage/index.rst
|
||||
存储 API
|
||||
***********
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
SPI Flash 和分区 API <spi_flash>
|
||||
SD/SDIO/MMC 驱动程序 <sdmmc>
|
||||
非易失性存储 <nvs_flash>
|
||||
NVS 分区生成程序 <nvs_partition_gen.rst>
|
||||
虚拟文件系统 <vfs>
|
||||
FAT 文件系统 <fatfs>
|
||||
磨损均衡 <wear-levelling>
|
||||
SPIFFS 文件系统 <spiffs>
|
||||
量产程序 <mass_mfg.rst>
|
||||
|
||||
|
||||
此部分 API 代码示例详见 ESP-IDF 项下 :example:`storage` 目录。
|
||||
|
|
|
|||
|
|
@ -1 +1,142 @@
|
|||
.. include:: ../../../en/api-reference/storage/spiffs.rst
|
||||
SPIFFS 文件系统
|
||||
=================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
SPIFFS 是一个用于 SPI NOR flash 设备的嵌入式文件系统，支持磨损均衡、文件系统一致性检查等功能。
|
||||
|
||||
说明
|
||||
-----
|
||||
|
||||
- 目前，SPIFFS 尚不支持目录，但可以生成扁平结构。如果 SPIFFS 挂载在 ``/spiffs`` 下，在 ``/spiffs/tmp/myfile.txt`` 路径下创建一个文件则会在 SPIFFS 中生成一个名为 ``/tmp/myfile.txt`` 的文件，而不是在 ``/spiffs/tmp`` 下生成名为 ``myfile.txt`` 的文件；
|
||||
- SPIFFS 并非实时栈，每次写操作耗时不等；
|
||||
- 目前，SPIFFS 尚不支持检测或处理已损坏的块。
|
||||
|
||||
工具
|
||||
-----
|
||||
|
||||
spiffsgen.py
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
:component_file:`spiffsgen.py<spiffs/spiffsgen.py>`（只写）是 SPIFFS 的一种 Python 实现，可用于从主机文件夹内容生成文件系统映像。打开终端并运行以下命令即可使用 ``spiffsgen.py``::
|
||||
|
||||
python spiffsgen.py <image_size> <base_dir> <output_file>
|
||||
|
||||
参数（必选）说明如下：
|
||||
|
||||
- **image_size**：分区大小，用于烧录生成的 SPIFFS 映像；
|
||||
- **base_dir**：创建 SPIFFS 映像的目录；
|
||||
- **output_file**：SPIFFS 映像输出文件。
|
||||
|
||||
其他参数（可选）也参与控制映像的生成，您可以运行以下帮助命令，查看这些参数的具体信息::
|
||||
|
||||
python spiffsgen.py --help
|
||||
|
||||
上述可选参数对应 SPIFFS 构建配置选项。若想顺利生成可用的映像，请确保使用的参数或配置与构建 SPIFFS 时所用的参数或配置相同。运行帮助命令将显示参数所对应的 SPIFFS 构建配置。如未指定参数，将使用帮助信息中的默认值。
|
||||
|
||||
映像生成后，您可以使用 ``esptool.py`` 或 ``parttool.py`` 烧录映像。
|
||||
|
||||
您可以在命令行或脚本中手动单独调用 ``spiffsgen.py``，也可以直接从构建系统调用 ``spiffs_create_partition_image`` 来使用 ``spiffsgen.py``。
|
||||
|
||||
在 Make 构建系统中运行::
|
||||
|
||||
SPIFFS_IMAGE_FLASH_IN_PROJECT := ...
|
||||
SPIFFS_IMAGE_DEPENDS := ...
|
||||
$(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
|
||||
|
||||
在 CMake 构建系统中运行::
|
||||
|
||||
spiffs_create_partition_image(<partition> <base_dir> [FLASH_IN_PROJECT] [DEPENDS dep dep dep...])
|
||||
|
||||
在构建系统中使用 ``spiffsgen.py`` 更为方便，构建配置自动传递给 ``spiffsgen.py`` 工具，确保生成的映像可用于构建。比如，单独调用 ``spiffsgen.py`` 时需要用到 *image_size* 参数，但在构建系统中调用 ``spiffs_create_partition_image`` 时，仅需要 *partition* 参数，映像大小将直接从工程分区表中获取。
|
||||
|
||||
Make 构建系统和 CMake 构建系统结构有所不同，请注意以下几点：
|
||||
|
||||
- 在 Make 构建系统中使用 ``spiffs_create_partition_image``，需从工程 Makefile 中调用；
|
||||
- 在 CMake 构建系统中使用 ``spiffs_create_partition_image``，需从组件 CMakeLists.txt 文件调用。
|
||||
|
||||
您也可以指定 ``FLASH_IN_PROJECT``，然后使用 ``idf.py flash`` 或 ``make flash`` 将映像与应用程序二进制文件、分区表等一起自动烧录至设备，例如：
|
||||
|
||||
在 Make 构建系统中运行::
|
||||
|
||||
SPIFFS_IMAGE_FLASH_IN_PROJECT := 1
|
||||
$(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
|
||||
|
||||
在 CMake 构建系统中运行::
|
||||
|
||||
spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
|
||||
|
||||
不指定 FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT 也可以生成映像，但须使用 ``esptool.py``、``parttool.py`` 或自定义构建系统目标手动烧录。
|
||||
|
||||
有时基本目录中的内容是在构建时生成的，您可以使用 DEPENDS/SPIFFS_IMAGE_DEPENDS 指定目标，因此可以在生成映像之前执行此目标。
|
||||
|
||||
在 Make 构建系统中运行::
|
||||
|
||||
dep:
|
||||
...
|
||||
|
||||
SPIFFS_IMAGE_DEPENDS := dep
|
||||
$(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
|
||||
|
||||
在 CMake 构建系统中运行::
|
||||
|
||||
add_custom_target(dep COMMAND ...)
|
||||
|
||||
spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)
|
||||
|
||||
请参考 :example:`examples/storage/spiffsgen>`，查看示例。
|
||||
|
||||
mkspiffs
|
||||
^^^^^^^^^^^
|
||||
|
||||
您也可以使用 `mkspiffs <https://github.com/igrr/mkspiffs>`_ 工具创建 SPIFFS 分区映像。与 ``spiffsgen.py`` 相似，`mkspiffs <https://github.com/igrr/mkspiffs>`_ 也可以用于从指定文件夹中生成映像，然后使用 ``esptool.py`` 烧录映像。
|
||||
|
||||
该工具需要获取以下参数：
|
||||
|
||||
- **Block Size**：4096（SPI flash 标准）
|
||||
- **Page Size**：256（SPI flash 标准）
|
||||
- **Image Size**：分区大小（以字节为单位，可从分区表中获取）
|
||||
- **Partition Offset**：分区起始地址（可从分区表内获取）
|
||||
|
||||
运行以下命令，将文件夹打包成 1 MB 大小的映像::
|
||||
|
||||
mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin
|
||||
|
||||
运行以下命令，将映像烧录到 ESP32（偏移量：0x110000）::
|
||||
|
||||
python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
|
||||
|
||||
|
||||
选择合适的 SPIFFS 工具
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
上面介绍的两款 SPIFFS 工具功能相似，需根据实际情况，选择合适的一款。
|
||||
|
||||
以下情况优先选用 ``spiffsgen.py`` 工具：
|
||||
|
||||
1. 仅需在构建时简单生成 SPIFFS 映像，请选择使用 ``spiffsgen.py``，``spiffsgen.py`` 可以直接在构建系统中使用函数或命令生成 SPIFFS 映像。
|
||||
2. 主机没有可用的 C/C++ 编译器时，可以选择使用 ``spiffsgen.py`` 工具，``spiffsgen.py`` 不需要编译。
|
||||
|
||||
以下情况优先选用 ``mkspiffs`` 工具：
|
||||
|
||||
1. 如果您除了需要生成映像外，还需要拆包 SPIFFS 映像，请选择使用 ``mkspiffs`` 工具。``spiffsgen.py`` 目前尚不支持此功能。
|
||||
2. 如果您当前环境中 Python 解释器不可用，但主机编译器可用，或者有预编译的 ``mkspiffs`` 二进制文件，此时请选择使用 ``mkspiffs`` 工具。但是，``mkspiffs`` 没有集成到构建系统，用户必须自己完成以下工作：在构建期间编译 ``mkspiffs`` （如果未使用预编译的二进制文件），为输出文件创建构建规则或目标，将适当的参数传递给工具等。
|
||||
|
||||
另请参阅
|
||||
--------
|
||||
|
||||
- :doc:`分区表 <../../api-guides/partition-tables>`
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
:example:`storage/spiffs` 目录下提供了 SPIFFS 应用示例。该示例初始化并挂载了一个 SPIFFS 分区，然后使用 POSIX 和 C 库 API 写入和读取数据。请参考 ``example`` 目录下的 README.md 文件，查看详细信息。
|
||||
|
||||
|
||||
高级 API 参考
|
||||
------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_spiffs.inc
|
||||
|
|
|
|||
|
|
@ -1 +1,33 @@
|
|||
.. include:: ../../../en/api-reference/storage/wear-levelling.rst
|
||||
.. include:: ../../../../components/wear_levelling/README.rst
|
||||
|
||||
另请参阅
|
||||
-----------
|
||||
|
||||
- :doc:`FAT 文件系统 <./fatfs>`
|
||||
- :doc:`分区表 <../../api-guides/partition-tables>`
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
:example:`storage/wear_levelling` 中提供了一款磨损均衡驱动与 FatFs 库结合使用的示例。该示例初始化磨损均衡驱动，挂载 FAT 文件系统分区，并使用 POSIX（可移植操作系统接口）和 C 库 API 从中写入和读取数据。如需了解更多信息，请参考 :example:`storage/wear_levelling/README.md`。
|
||||
|
||||
高级 API 参考
|
||||
------------------------
|
||||
|
||||
头文件
|
||||
^^^^^^^^^^^^
|
||||
|
||||
* :component_file:`fatfs/src/esp_vfs_fat.h`
|
||||
|
||||
函数
|
||||
^^^^^^^^^
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_mount
|
||||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||||
:members:
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_unmount
|
||||
|
||||
中层 API 参考
|
||||
-----------------------
|
||||
|
||||
.. include:: /_build/inc/wear_levelling.inc
|
||||
|
|
|
|||
Loading…
Reference in a new issue