From fcfa85cb7729c08e631f7ac462f4a9f3649a43a7 Mon Sep 17 00:00:00 2001 From: Zhang Shuxian Date: Sat, 8 Feb 2025 14:29:17 +0800 Subject: [PATCH] docs: Update CN translation for fatfs --- docs/en/api-reference/storage/fatfs.rst | 9 +++++---- docs/zh_CN/api-reference/storage/fatfs.rst | 15 +++++++++++++-- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/en/api-reference/storage/fatfs.rst b/docs/en/api-reference/storage/fatfs.rst index 260779ef01..b8555133cb 100644 --- a/docs/en/api-reference/storage/fatfs.rst +++ b/docs/en/api-reference/storage/fatfs.rst @@ -20,7 +20,9 @@ The function :cpp:func:`esp_vfs_fat_unregister_path` deletes the registration wi Most applications use the following workflow when working with ``esp_vfs_fat_`` functions: -#. Call :cpp:func:`esp_vfs_fat_register` to specify: +#. + Call :cpp:func:`esp_vfs_fat_register` to specify: + - Path prefix where to mount the filesystem (e.g., ``"/sdcard"``, ``"/spiflash"``) - FatFs drive number - A variable which receives the pointer to the ``FATFS`` structure @@ -72,15 +74,14 @@ The following configuration options are available for the FatFs component: * :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC` - If enabled, the FatFs will automatically call :cpp:func:`f_sync` to flush recent file changes after each call of :cpp:func:`write`, :cpp:func:`pwrite`, :cpp:func:`link`, :cpp:func:`truncate` and :cpp:func:`ftruncate` functions. This feature improves file-consistency and size reporting accuracy for the FatFs, at a price of decreased performance due to frequent disk operations. * :ref:`CONFIG_FATFS_LINK_LOCK` - If enabled, this option guarantees the API thread safety, while disabling this option might be necessary for applications that require fast frequent small file operations (e.g., logging to a file). Note that if this option is disabled, the copying performed by :cpp:func:`link` will be non-atomic. In such case, using :cpp:func:`link` on a large file on the same volume in a different task is not guaranteed to be thread safe. - -These options set a behavior of how the FATFS filesystem calculates and reports free space: +These options set a behavior of how the FatFs filesystem calculates and reports free space: * :ref:`CONFIG_FATFS_DONT_TRUST_FREE_CLUSTER_CNT` - If 1, free cluster count will be ignored. Default value is 0. * :ref:`CONFIG_FATFS_DONT_TRUST_LAST_ALLOC` - If 1, last allocation number will be ignored. Default value is 0. .. note:: - Setting these settings to 1 may increase the accuracy of :cpp:func:`f_getfree` output at a price of decreased performance, e.g. due to performing full FAT scan. + Setting these options to 1 may increase the accuracy of :cpp:func:`f_getfree` output at a price of decreased performance, e.g., due to performing full FAT scan. .. _fatfs-diskio-layer: diff --git a/docs/zh_CN/api-reference/storage/fatfs.rst b/docs/zh_CN/api-reference/storage/fatfs.rst index a5d7e6e8b2..a661e0ca8c 100644 --- a/docs/zh_CN/api-reference/storage/fatfs.rst +++ b/docs/zh_CN/api-reference/storage/fatfs.rst @@ -20,7 +20,9 @@ FatFs 与 VFS 配合使用 多数应用程序在使用 ``esp_vfs_fat_`` 函数时，采用如下步骤： -#. 调用 :cpp:func:`esp_vfs_fat_register`，指定： +#. + 调用 :cpp:func:`esp_vfs_fat_register`，指定： + - 挂载文件系统的路径前缀（例如，``"/sdcard"`` 或 ``"/spiflash"``） - FatFs 驱动编号 - 一个用于接收指向 ``FATFS`` 结构指针的变量 @@ -69,9 +71,18 @@ FatFs 与 VFS 配合使用（只读模式下） FatFs 组件有以下配置选项： * :ref:`CONFIG_FATFS_USE_FASTSEEK` - 如果启用该选项，POSIX :cpp:func:`lseek` 函数将以更快的速度执行。快速查找不适用于编辑模式下的文件，所以，使用快速查找时，应在只读模式下打开（或者关闭然后重新打开）文件。 -* :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC` - 如果启用该选项，FatFs 将在每次调用 :cpp:func:`write`、:cpp:func:`pwrite`、:cpp:func:`link`、:cpp:func:`truncate` 和 :cpp:func:`ftruncate` 函数后，自动调用 :cpp:func:`f_sync` 以同步最近的文件改动。该功能可提高文件系统中文件的一致性和文件大小报告的准确性，但由于需要频繁进行磁盘操作，性能将会受到影响。 +* :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC` - 如果启用该选项，FatFs 将在每次调用 :cpp:func:`write`、:cpp:func:`pwrite`、:cpp:func:`link`、:cpp:func:`truncate` 和 :cpp:func:`ftruncate` 函数后，自动调用 :cpp:func:`f_sync` 以同步最近的文件改动。该功能提升了 FatFs 的文件一致性和文件大小报告的准确性，但频繁的磁盘操作会降低性能。 * :ref:`CONFIG_FATFS_LINK_LOCK` - 如果启用该选项，可保证 API 的线程安全，但如果应用程序需要快速频繁地进行小文件操作（例如将日志记录到文件），则可能有必要禁用该选项。请注意，如果禁用该选项，调用 :cpp:func:`link` 后的复制操作将是非原子的，此时如果在不同任务中对同一卷上的大文件调用 :cpp:func:`link`，则无法确保线程安全。 +以下选项用于设置 FatFs 文件系统计算和报告空闲空间的策略： + +* :ref:`CONFIG_FATFS_DONT_TRUST_FREE_CLUSTER_CNT` – 如果设置为 1，将忽略空闲簇计数。默认值为 0。 +* :ref:`CONFIG_FATFS_DONT_TRUST_LAST_ALLOC` – 如果设置为 1，将忽略上次分配的簇号。默认值为 0。 + +.. note:: + + 将这两个选项设为 1 可能会提高 :cpp:func:`f_getfree` 输出的准确性，但性能会下降，例如，可能需要执行完整的 FAT 扫描。 + .. _fatfs-diskio-layer: