Merge branch 'feat/fatfs_r_0_16' into 'master'

feat(storage/fatfs): Update to FatFS R0.16

Closes IDF-14371

See merge request espressif/esp-idf!42810

Author: pacucha42

components/fatfs/host_test/main/test_fatfs.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -16,47 +16,39 @@
 
 TEST_CASE("Create volume, open file, write and read back data", "[fatfs]")
 {
-    FRESULT fr_result;
     BYTE pdrv;
     FATFS fs;
     FIL file;
     UINT bw;
 
-    esp_err_t esp_result;
-
     const esp_partition_t *partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, "storage");
 
     // Mount wear-levelled partition
     wl_handle_t wl_handle;
-    esp_result = wl_mount(partition, &wl_handle);
-    REQUIRE(esp_result == ESP_OK);
+    REQUIRE(wl_mount(partition, &wl_handle) == ESP_OK);
 
     // Get a physical drive
-    esp_result = ff_diskio_get_drive(&pdrv);
-    REQUIRE(esp_result == ESP_OK);
+    REQUIRE(ff_diskio_get_drive(&pdrv) == ESP_OK);
 
     // Register physical drive as wear-levelled partition
-    esp_result = ff_diskio_register_wl_partition(pdrv, wl_handle);
+    REQUIRE(ff_diskio_register_wl_partition(pdrv, wl_handle) == ESP_OK);
 
     // Create FAT volume on the entire disk
     LBA_t part_list[] = {100, 0, 0, 0};
     BYTE work_area[FF_MAX_SS];
 
-    fr_result = f_fdisk(pdrv, part_list, work_area);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_fdisk(pdrv, part_list, work_area) == FR_OK);
 
     // For host tests, include FM_SFD flag when formatting partitions smaller than 128KB.
     // if n_root field of MKFS_PARM is set to 128 => 1 root directory sec and if set to 0(default 512) => 4 root directory sectors.
     const MKFS_PARM opt = {(BYTE)(FM_ANY | FM_SFD), 0, 0, 128, 0};
-    fr_result = f_mkfs("", &opt, work_area, sizeof(work_area)); // Use default volume
+    REQUIRE(f_mkfs("", &opt, work_area, sizeof(work_area)) == FR_OK); // Use default volume
 
     // Mount the volume
-    fr_result = f_mount(&fs, "", 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(&fs, "", 0) == FR_OK);
 
     // Open, write and read data
-    fr_result = f_open(&file, "test.txt", FA_OPEN_ALWAYS | FA_READ | FA_WRITE);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_open(&file, "test.txt", FA_OPEN_ALWAYS | FA_READ | FA_WRITE) == FR_OK);
 
     // Generate data
     uint32_t data_size = 1000;
@@ -70,72 +62,59 @@ TEST_CASE("Create volume, open file, write and read back data", "[fatfs]")
     }
 
     // Write generated data
-    fr_result = f_write(&file, data, data_size, &bw);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_write(&file, data, data_size, &bw) == FR_OK);
     REQUIRE(bw == data_size);
 
     // Move to beginning of file
-    fr_result = f_lseek(&file, 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_lseek(&file, 0) == FR_OK);
 
     // Read written data
-    fr_result = f_read(&file, read, data_size, &bw);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_read(&file, read, data_size, &bw) == FR_OK);
     REQUIRE(bw == data_size);
 
     REQUIRE(memcmp(data, read, data_size) == 0);
 
     // Close file
-    fr_result = f_close(&file);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_close(&file) == FR_OK);
 
     // Unmount default volume
-    fr_result = f_mount(0, "", 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(0, "", 0) == FR_OK);
 
     // Clear
     free(read);
     free(data);
     ff_diskio_unregister(pdrv);
     ff_diskio_clear_pdrv_wl(wl_handle);
-    esp_result = wl_unmount(wl_handle);
-    REQUIRE(esp_result == ESP_OK);
+    REQUIRE(wl_unmount(wl_handle) == ESP_OK);
 }
 
 static void prepare_fatfs(const char* partition_label, const esp_partition_t** partition, wl_handle_t* wl_handle, BYTE* pdrv)
 {
-    FRESULT fr_result;
-    esp_err_t esp_result;
-
     *partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, partition_label);
     REQUIRE(partition != NULL);
     printf("partition address=0x%x\n", (*partition)->address);
     printf("partition size=0x%x\n", (*partition)->size);
 
     // Mount wear-levelled partition
-    esp_result = wl_mount(*partition, wl_handle);
-    REQUIRE(esp_result == ESP_OK);
+    REQUIRE(wl_mount(*partition, wl_handle) == ESP_OK);
 
     // Get a physical drive
     BYTE _pdrv;
-    esp_result = ff_diskio_get_drive(&_pdrv);
-    REQUIRE(esp_result == ESP_OK);
+    REQUIRE(ff_diskio_get_drive(&_pdrv) == ESP_OK);
     printf("using pdrv=%i\n", _pdrv);
     char drv[3] = {(char)('0' + _pdrv), ':', 0};
     *pdrv = _pdrv;
 
     // Register physical drive as wear-levelled partition
-    esp_result = ff_diskio_register_wl_partition(_pdrv, *wl_handle);
+    REQUIRE(ff_diskio_register_wl_partition(_pdrv, *wl_handle) == ESP_OK);
 
     // Create FAT volume on the entire disk
     LBA_t part_list[] = {100, 0, 0, 0};
     BYTE work_area[FF_MAX_SS];
 
-    fr_result = f_fdisk(_pdrv, part_list, work_area);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_fdisk(_pdrv, part_list, work_area) == FR_OK);
     const MKFS_PARM opt = {(BYTE)(FM_ANY | FM_SFD), 0, 0, 128, 0};
-    fr_result = f_mkfs(drv, &opt, work_area, sizeof(work_area)); // Use default volume
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mkfs(drv, &opt, work_area, sizeof(work_area)) == FR_OK); // Use default volume
 }
 
 /*
@@ -146,9 +125,6 @@ static void prepare_fatfs(const char* partition_label, const esp_partition_t** p
  */
 TEST_CASE("Test mounting 2 volumes, writing data and formatting the 2nd one, reading data", "[fatfs]")
 {
-    FRESULT fr_result;
-    esp_err_t esp_result;
-
     const char* partition_label0 = "storage";
     const esp_partition_t *partition0 = NULL;
     BYTE pdrv0 = UINT8_MAX;
@@ -170,27 +146,22 @@ TEST_CASE("Test mounting 2 volumes, writing data and formatting the 2nd one, rea
     REQUIRE(wl_handle0 != WL_INVALID_HANDLE);
     REQUIRE(pdrv0 == 0);
     char drv0[3] = {(char)('0' + pdrv0), ':', 0};
-    fr_result = f_mount(&fs0, drv0, 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(&fs0, drv0, 0) == FR_OK);
 
     // Open file and write data
     FIL file0;
     UINT bw0;
-    fr_result = f_open(&file0, "0:/test0.txt", FA_OPEN_ALWAYS | FA_WRITE);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_open(&file0, "0:/test0.txt", FA_OPEN_ALWAYS | FA_WRITE) == FR_OK);
     // Write data
     const char *data0 = "123456789";
     char read0[10] = {0};
-    fr_result = f_write(&file0, data0, data_size, &bw0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_write(&file0, data0, data_size, &bw0) == FR_OK);
     REQUIRE(bw0 == data_size);
     // Close file
-    fr_result = f_close(&file0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_close(&file0) == FR_OK);
 
     // Unmount volume 0
-    fr_result = f_mount(0, drv0, 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(0, drv0, 0) == FR_OK);
 
 
     // Mount the volume 1
@@ -199,89 +170,72 @@ TEST_CASE("Test mounting 2 volumes, writing data and formatting the 2nd one, rea
     REQUIRE(wl_handle1 != WL_INVALID_HANDLE);
     REQUIRE(pdrv1 == 1);
     char drv1[3] = {(char)('0' + pdrv1), ':', 0};
-    fr_result = f_mount(&fs1, drv1, 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(&fs1, drv1, 0) == FR_OK);
 
     // Open file and write data
     FIL file1;
     UINT bw1;
-    fr_result = f_open(&file1, "1:/test1.txt", FA_OPEN_ALWAYS | FA_WRITE);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_open(&file1, "1:/test1.txt", FA_OPEN_ALWAYS | FA_WRITE) == FR_OK);
     // Write data
     const char* data1 = "987654321";
     char read1[10] = {0};
-    fr_result = f_write(&file1, data1, data_size, &bw1);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_write(&file1, data1, data_size, &bw1) == FR_OK);
     REQUIRE(bw1 == data_size);
     // Close file
-    fr_result = f_close(&file1);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_close(&file1) == FR_OK);
 
     // Unmount volume 1
-    fr_result = f_mount(0, drv1, 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(0, drv1, 0) == FR_OK);
 
     // Format the volume 1
     const size_t workbuf_size = 4096;
     void *workbuf = ff_memalloc(workbuf_size);
     REQUIRE(workbuf != NULL);
     const MKFS_PARM opt = {(BYTE)(FM_ANY | FM_SFD), 0, 0, 128, CONFIG_WL_SECTOR_SIZE};
-    fr_result = f_mkfs(drv1, &opt, workbuf, workbuf_size);
+    FRESULT fr_result = f_mkfs(drv1, &opt, workbuf, workbuf_size);
     free(workbuf);
     workbuf = NULL;
     REQUIRE(fr_result == FR_OK);
     printf("partition1 formatted\n");
 
 
     // Remount the volume 1
-    fr_result = f_mount(&fs1, drv1, 1);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(&fs1, drv1, 1) == FR_OK);
     // Open file and read data from file1
-    fr_result = f_open(&file1, "1:/test1.txt", FA_OPEN_ALWAYS | FA_READ);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_open(&file1, "1:/test1.txt", FA_OPEN_ALWAYS | FA_READ) == FR_OK);
     // Read written data from file1
-    fr_result = f_read(&file1, read1, data_size, &bw1);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_read(&file1, read1, data_size, &bw1) == FR_OK);
     REQUIRE(bw1 != data_size);
     // Compare data
     printf("data1=%s, read1=%s\n", data1, read1);
     REQUIRE(strncmp(data1, read1, data_size-1) != 0); // 987654321 should be ersead due to formatting
     // Close file from file1
-    fr_result = f_close(&file1);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_close(&file1) == FR_OK);
 
 
     // Remount the volume 0
-    fr_result = f_mount(&fs0, drv0, 1);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(&fs0, drv0, 1) == FR_OK);
     // Open file and read data from file0
-    fr_result = f_open(&file0, "0:/test0.txt", FA_OPEN_ALWAYS | FA_READ);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_open(&file0, "0:/test0.txt", FA_OPEN_ALWAYS | FA_READ) == FR_OK);
     // Read written data from file0
-    fr_result = f_read(&file0, read0, data_size, &bw0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_read(&file0, read0, data_size, &bw0) == FR_OK);
     REQUIRE(bw0 == data_size);
     // Compare data
     printf("data0=%s, read0=%s\n", data0, read0);
     REQUIRE(strncmp(data0, read0, data_size-1) == 0); // should match since the partition was not formatted
     // Close file from file0
-    fr_result = f_close(&file0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_close(&file0) == FR_OK);
 
 
     // Unmount both volumes
-    fr_result = f_mount(0, drv0, 0);
-    REQUIRE(fr_result == FR_OK);
-    fr_result = f_mount(0, drv1, 0);
-    REQUIRE(fr_result == FR_OK);
+    REQUIRE(f_mount(0, drv0, 0) == FR_OK);
+    REQUIRE(f_mount(0, drv1, 0) == FR_OK);
 
     // Clear
     ff_diskio_unregister(pdrv0);
     ff_diskio_unregister(pdrv1);
     ff_diskio_clear_pdrv_wl(wl_handle0);
     ff_diskio_clear_pdrv_wl(wl_handle1);
-    esp_result = wl_unmount(wl_handle0);
-    REQUIRE(esp_result == ESP_OK);
-    esp_result = wl_unmount(wl_handle1);
-    REQUIRE(esp_result == ESP_OK);
+    REQUIRE(wl_unmount(wl_handle0) == ESP_OK);
+    REQUIRE(wl_unmount(wl_handle1) == ESP_OK);
 }

components/fatfs/src/00history.txt

@@ -366,3 +366,24 @@ R0.15 (November 6, 2022)
   Fixed f_mkfs() creates broken exFAT volume when the size of volume is >= 2^32 sectors.
   Fixed string functions cannot write the unicode characters not in BMP when FF_LFN_UNICODE == 2 (UTF-8).
   Fixed a compatibility issue in identification of GPT header.
+
+
+
+R0.15a (November 22, 2024)
+  Fixed a complie error when FF_FS_LOCK != 0.
+  Fixed a potential issue when work FatFs concurrency with FF_FS_REENTRANT, FF_VOLUMES >= 2 and FF_FS_LOCK > 0.
+  Made f_setlabel() accept a volume label in Unix style volume ID when FF_STR_VOLUME_ID == 2.
+  Made FatFs update PercInUse field in exFAT VBR. (A preceding f_getfree() is needed for the accuracy)
+
+
+
+R0.15b (June 21, 2025)
+  Added support for timestamp of created time. (FF_FS_CRTIME)
+  Fixed FatFs fails to load the FsInfo in FAT32 volumes and the f_getfree always be forced a full FAT scan which takes a long time. (appeared at R0.15a)
+
+
+
+R0.16 (July 22, 2025)
+  Removed a long-pending limitation that f_getcwd and double-dot .. in the path name did not work on the exFAT volume.
+  Fixed f_readdir cannot detect end of directory and it leads the application process into infinite loop. (appeared at R0.15b)
+  Fixed dot names with terminating separator or duplicated separator are rejected when LFN is not enabled.

components/fatfs/src/00readme.txt

@@ -1,4 +1,4 @@
-FatFs Module Source Files R0.15
+FatFs Module Source Files R0.16
 
 
 FILES

components/fatfs/src/diskio.c

@@ -1,19 +1,23 @@
 /*-----------------------------------------------------------------------*/
-/* Low level disk I/O module SKELETON for FatFs     (C)ChaN, 2019        */
+/* Low level disk I/O module SKELETON for FatFs     (C)ChaN, 2025        */
 /*-----------------------------------------------------------------------*/
 /* If a working storage control module is available, it should be        */
 /* attached to the FatFs via a glue function rather than modifying it.   */
 /* This is an example of glue functions to attach various exsisting      */
 /* storage control modules to the FatFs module with a defined API.       */
 /*-----------------------------------------------------------------------*/
 
-#include "ff.h"			/* Obtains integer types */
-#include "diskio.h"		/* Declarations of disk functions */
+#include "ff.h"			/* Basic definitions of FatFs */
+#include "diskio.h"		/* Declarations FatFs MAI */
 
-/* Definitions of physical drive number for each drive */
-#define DEV_RAM		0	/* Example: Map Ramdisk to physical drive 0 */
-#define DEV_MMC		1	/* Example: Map MMC/SD card to physical drive 1 */
-#define DEV_USB		2	/* Example: Map USB MSD to physical drive 2 */
+/* Example: Declarations of the platform and disk functions in the project */
+#include "platform.h"
+#include "storage.h"
+
+/* Example: Mapping of physical drive number for each drive */
+#define DEV_FLASH	0	/* Map FTL to physical drive 0 */
+#define DEV_MMC		1	/* Map MMC/SD card to physical drive 1 */
+#define DEV_USB		2	/* Map USB MSD to physical drive 2 */
 
 
 /*-----------------------------------------------------------------------*/

components/fatfs/src/diskio.h

@@ -1,5 +1,5 @@
 /*-----------------------------------------------------------------------/
-/  Low level disk interface modlue include file   (C)ChaN, 2019          /
+/  Low level disk interface modlue include file   (C)ChaN, 2025          /
 /-----------------------------------------------------------------------*/
 
 #ifndef _DISKIO_DEFINED
@@ -57,7 +57,7 @@ DRESULT disk_ioctl (BYTE pdrv, BYTE cmd, void* buff);
 #define CTRL_EJECT			7	/* Eject media */
 #define CTRL_FORMAT			8	/* Create physical format on the media */
 
-/* MMC/SDC specific ioctl command */
+/* MMC/SDC specific ioctl command (Not used by FatFs) */
 #define MMC_GET_TYPE		10	/* Get card type */
 #define MMC_GET_CSD			11	/* Get CSD */
 #define MMC_GET_CID			12	/* Get CID */
@@ -67,7 +67,7 @@ DRESULT disk_ioctl (BYTE pdrv, BYTE cmd, void* buff);
 #define ISDIO_WRITE			56	/* Write data to SD iSDIO register */
 #define ISDIO_MRITE			57	/* Masked write data to SD iSDIO register */
 
-/* ATA/CF specific ioctl command */
+/* ATA/CF specific ioctl command (Not used by FatFs) */
 #define ATA_GET_REV			20	/* Get F/W revision */
 #define ATA_GET_MODEL		21	/* Get model name */
 #define ATA_GET_SN			22	/* Get serial number */