Merge branch 'feat/ff_fs_nofsinfo_kconfig' into 'master'

feat(fatfs): Add an option to set FF_FS_NOFSINFO value

Closes IDFGH-14467

See merge request espressif/esp-idf!36592

Author: adokitkat

components/fatfs/Kconfig

@@ -310,6 +310,7 @@ menu "FAT Filesystem support"
             If enabled, the whole link operation (including file copying) is performed under lock.
             This ensures that the link operation is atomic, but may cause performance for large files.
             It may create less fragmented file copy.
+
     config FATFS_USE_DYN_BUFFERS
         bool "Use dynamic buffers"
         depends on CONFIG_WL_SECTOR_SIZE_4096
@@ -321,4 +322,27 @@ menu "FAT Filesystem support"
             If disabled, the greatest sector size will be used for all FATFS instances.
             (In most cases, this would be the sector size of Wear Levelling library)
             This might cause more memory to be used than necessary.
+
+    menu "File system free space calculation behavior"
+        help
+            Controls if the file system does or does not trust cached data like free cluster count and allocated
+            cluster number. Setting these to do not trust the data may result of more accurate output from
+            `f_getfree()` function but increased overhead (forces a full FAT scan, etc.).
+
+        config FATFS_DONT_TRUST_FREE_CLUSTER_CNT
+            int "Don't trust free cluster count"
+            default 0
+            range 0 1
+            help
+                If 1, the file system will not trust the free cluster count in the FSINFO (in FATFS struct).
+                This may result in more accurate output from `f_getfree()` function but increased overhead.
+
+        config FATFS_DONT_TRUST_LAST_ALLOC
+            int "Don't trust allocated cluster number"
+            default 0
+            range 0 1
+            help
+                If 1, the file system will not trust the last allocated cluster number in the FSINFO (in FATFS struct).
+                This may result in more accurate output from `f_getfree()` function but increased overhead.
+    endmenu
 endmenu

components/fatfs/src/ffconf.h

@@ -299,7 +299,7 @@
 /  These options have no effect in read-only configuration (FF_FS_READONLY = 1). */
 
 
-#define FF_FS_NOFSINFO	0
+#define FF_FS_NOFSINFO	(CONFIG_FATFS_DONT_TRUST_FREE_CLUSTER_CNT << 0 | CONFIG_FATFS_DONT_TRUST_LAST_ALLOC << 1)
 /* If you need to know correct free space on the FAT32 volume, set bit 0 of this
 /  option, and f_getfree() function at the first time after volume mount will force
 /  a full FAT scan. Bit 1 controls the use of last allocated cluster number.

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
@@ -70,9 +72,18 @@ Configuration options
 The following configuration options are available for the FatFs component:
 
 * :ref:`CONFIG_FATFS_USE_FASTSEEK` - If enabled, the POSIX :cpp:func:`lseek` function will be performed faster. The fast seek does not work for files in write mode, so to take advantage of fast seek, you should open (or close and then reopen) the file in read-only mode.
-* :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 on decreased performance due to frequent disk operations.
+* :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:
+
+* :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 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:
 

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`` 结构指针的变量
@@ -70,9 +72,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: