fatfs: added an API to format FAT on spiflash

components/fatfs/test_apps/flash_wl/main/test_fatfs_flash_wl.c

@@ -33,7 +33,7 @@ static void test_setup(void)
 {
     esp_vfs_fat_sdmmc_mount_config_t mount_config = {
         .format_if_mount_failed = true,
-        .max_files = 5
+        .max_files = 5,
     };
 
     TEST_ESP_OK(esp_vfs_fat_spiflash_mount_rw_wl("/spiflash", NULL, &mount_config, &s_test_wl_handle));
@@ -46,13 +46,20 @@ static void test_teardown(void)
 
 TEST_CASE("(WL) can format partition", "[fatfs][wear_levelling]")
 {
-    const esp_partition_t* part = esp_partition_find_first(ESP_PARTITION_TYPE_DATA,
+    TEST_ESP_OK(esp_vfs_fat_spiflash_format_rw_wl("/spiflash", NULL));
-            ESP_PARTITION_SUBTYPE_DATA_FAT, NULL);
-    esp_partition_erase_range(part, 0, part->size);
     test_setup();
     test_teardown();
 }
 
+TEST_CASE("(WL) can format when the FAT is mounted already", "[fatfs][wear_levelling]")
+{
+    test_setup();
+    TEST_ESP_OK(esp_vfs_fat_spiflash_format_rw_wl("/spiflash", NULL));
+    test_fatfs_create_file_with_text("/spiflash/hello.txt", fatfs_test_hello_str);
+    test_fatfs_pread_file("/spiflash/hello.txt");
+    test_teardown();
+}
+
 TEST_CASE("(WL) can create and write file", "[fatfs][wear_levelling]")
 {
     test_setup();

components/fatfs/vfs/esp_vfs_fat.h

@@ -250,6 +250,24 @@ esp_err_t esp_vfs_fat_spiflash_mount_rw_wl(const char* base_path,
  */
 esp_err_t esp_vfs_fat_spiflash_unmount_rw_wl(const char* base_path, wl_handle_t wl_handle);
 
+/**
+ * @brief Format FAT filesystem
+ *
+ * @note
+ * This API can be called when the FAT is mounted / not mounted.
+ * If this API is called when the FAT isn't mounted (by calling esp_vfs_fat_spiflash_mount_rw_wl),
+ * this API will first mount the FAT then format it, then restore back to the original state.
+ *
+ * @param base_path        Path where partition should be registered (e.g. "/spiflash")
+ * @param partition_label  Label of the partition which should be used
+ *
+ * @return
+ *        - ESP_OK
+ *        - ESP_ERR_NO_MEM: if memory can not be allocated
+ *        - Other errors from esp_vfs_fat_spiflash_mount_rw_wl
+ */
+esp_err_t esp_vfs_fat_spiflash_format_rw_wl(const char* base_path, const char* partition_label);
+
 /**
  * @brief Convenience function to initialize read-only FAT filesystem and register it in VFS
  *

components/fatfs/vfs/vfs_fat_spiflash.c

@@ -12,22 +12,107 @@
 #include "esp_vfs_fat.h"
 #include "vfs_fat_internal.h"
 #include "diskio_impl.h"
-
 #include "diskio_rawflash.h"
-
 #include "wear_levelling.h"
 #include "diskio_wl.h"
 
 static const char* TAG = "vfs_fat_spiflash";
 
+typedef struct vfs_fat_spiflash_ctx_t {
+    const esp_partition_t *partition;           //The partition where the FAT is located
+    bool by_label;                              //If the partition is mounted by lable or not
+    BYTE pdrv;                                  //Drive number that is mounted
+    FATFS *fs;                                  //FAT structure pointer that is registered
+    wl_handle_t wlhandle;                       //WL handle
+    esp_vfs_fat_mount_config_t mount_config;    //Mount configuration
+} vfs_fat_spiflash_ctx_t;
+
+static vfs_fat_spiflash_ctx_t *s_ctx[FF_VOLUMES] = {};
+
+static bool s_get_context_id_by_label(const char *label, uint32_t *out_id)
+{
+    vfs_fat_spiflash_ctx_t *p_ctx = NULL;
+    for (int i = 0; i < FF_VOLUMES; i++) {
+        p_ctx = s_ctx[i];
+        if (p_ctx) {
+            if (!label && !p_ctx->by_label) {
+                *out_id = i;
+                return true;
+            }
+            if (label && p_ctx->by_label && strncmp(label, p_ctx->partition->label, 20) == 0) {
+                *out_id = i;
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+static bool s_get_context_id_by_wl_handle(wl_handle_t wlhandle, uint32_t *out_id)
+{
+    vfs_fat_spiflash_ctx_t *p_ctx = NULL;
+    for (int i = 0; i < FF_VOLUMES; i++) {
+        p_ctx = s_ctx[i];
+        if (p_ctx) {
+            if (p_ctx->wlhandle == wlhandle) {
+                *out_id = i;
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+static uint32_t s_get_unused_context_id(void)
+{
+    for (uint32_t i = 0; i < FF_VOLUMES; i++) {
+        if (!s_ctx[i]) {
+            return i;
+        }
+    }
+    return FF_VOLUMES;
+}
+
+static esp_err_t s_f_mount_rw(FATFS *fs, const char *drv, const esp_vfs_fat_mount_config_t *mount_config)
+{
+    FRESULT fresult = f_mount(fs, drv, 1);
+    if (fresult != FR_OK) {
+        ESP_LOGW(TAG, "f_mount failed (%d)", fresult);
+
+        bool need_mount_again = (fresult == FR_NO_FILESYSTEM || fresult == FR_INT_ERR) && mount_config->format_if_mount_failed;
+        if (!need_mount_again) {
+            return ESP_FAIL;
+        }
+
+        const size_t workbuf_size = 4096;
+        void *workbuf = ff_memalloc(workbuf_size);
+        if (workbuf == NULL) {
+            return ESP_ERR_NO_MEM;
+        }
+
+        size_t alloc_unit_size = esp_vfs_fat_get_allocation_unit_size(CONFIG_WL_SECTOR_SIZE, mount_config->allocation_unit_size);
+        ESP_LOGI(TAG, "Formatting FATFS partition, allocation unit size=%d", alloc_unit_size);
+        const MKFS_PARM opt = {(BYTE)(FM_ANY | FM_SFD), 0, 0, 0, alloc_unit_size};
+        fresult = f_mkfs(drv, &opt, workbuf, workbuf_size);
+        free(workbuf);
+        workbuf = NULL;
+        ESP_RETURN_ON_FALSE(fresult == FR_OK, ESP_FAIL, TAG, "f_mkfs failed (%d)", fresult);
+
+        ESP_LOGI(TAG, "Mounting again");
+        fresult = f_mount(fs, drv, 0);
+        ESP_RETURN_ON_FALSE(fresult == FR_OK, ESP_FAIL, TAG, "f_mount failed after formatting (%d)", fresult);
+    }
+    return ESP_OK;
+}
+
 esp_err_t esp_vfs_fat_spiflash_mount_rw_wl(const char* base_path,
     const char* partition_label,
     const esp_vfs_fat_mount_config_t* mount_config,
     wl_handle_t* wl_handle)
 {
     esp_err_t ret = ESP_OK;
-    const size_t workbuf_size = 4096;
+    vfs_fat_spiflash_ctx_t *ctx = NULL;
-    void *workbuf = NULL;
+    uint32_t ctx_id = FF_VOLUMES;
 
     esp_partition_subtype_t subtype = partition_label ?
             ESP_PARTITION_SUBTYPE_ANY : ESP_PARTITION_SUBTYPE_DATA_FAT;
@@ -57,38 +142,33 @@ esp_err_t esp_vfs_fat_spiflash_mount_rw_wl(const char* base_path,
     }
 
     // Try to mount partition
-    FRESULT fresult = f_mount(fs, drv, 1);
+    ret = s_f_mount_rw(fs, drv, mount_config);
-    if (fresult != FR_OK) {
+    if (ret != ESP_OK) {
-        ESP_LOGW(TAG, "f_mount failed (%d)", fresult);
+        goto fail;
-        if (!((fresult == FR_NO_FILESYSTEM || fresult == FR_INT_ERR)
-              && mount_config->format_if_mount_failed)) {
-            ret = ESP_FAIL;
-            goto fail;
-        }
-        workbuf = ff_memalloc(workbuf_size);
-        if (workbuf == NULL) {
-            ret = ESP_ERR_NO_MEM;
-            goto fail;
-        }
-        size_t alloc_unit_size = esp_vfs_fat_get_allocation_unit_size(
-                CONFIG_WL_SECTOR_SIZE,
-                mount_config->allocation_unit_size);
-        ESP_LOGI(TAG, "Formatting FATFS partition, allocation unit size=%d", alloc_unit_size);
-        const MKFS_PARM opt = {(BYTE)(FM_ANY | FM_SFD), 0, 0, 0, alloc_unit_size};
-        fresult = f_mkfs(drv, &opt, workbuf, workbuf_size);
-        ESP_GOTO_ON_FALSE(fresult == FR_OK, ESP_FAIL, fail, TAG, "f_mkfs failed (%d)", fresult);
-        free(workbuf);
-        workbuf = NULL;
-        ESP_LOGI(TAG, "Mounting again");
-        fresult = f_mount(fs, drv, 0);
-        ESP_GOTO_ON_FALSE(fresult == FR_OK, ESP_FAIL, fail, TAG, "f_mount failed after formatting (%d)", fresult);
     }
+
+    ctx = calloc(sizeof(vfs_fat_spiflash_ctx_t), 1);
+    ESP_GOTO_ON_FALSE(ctx, ESP_ERR_NO_MEM, fail, TAG, "no mem");
+    ctx->partition = data_partition;
+    ctx->by_label = (partition_label != NULL);
+    ctx->pdrv = pdrv;
+    ctx->fs = fs;
+    ctx->wlhandle = *wl_handle;
+    memcpy(&ctx->mount_config, mount_config, sizeof(esp_vfs_fat_mount_config_t));
+    ctx_id = s_get_unused_context_id();
+    //At this stage, we should always get a free context, otherwise program should return already
+    assert (ctx_id != FF_VOLUMES);
+    s_ctx[ctx_id] = ctx;
+
     return ESP_OK;
 
 fail:
-    free(workbuf);
     esp_vfs_fat_unregister_path(base_path);
     ff_diskio_unregister(pdrv);
+    if (ctx_id != FF_VOLUMES) {
+        s_ctx[ctx_id] = NULL;
+    }
+    free(ctx);
     return ret;
 }
 
@@ -104,36 +184,80 @@ esp_err_t esp_vfs_fat_spiflash_unmount_rw_wl(const char* base_path, wl_handle_t
     // release partition driver
     esp_err_t err_drv = wl_unmount(wl_handle);
     esp_err_t err = esp_vfs_fat_unregister_path(base_path);
-    if (err == ESP_OK) err = err_drv;
+    if (err == ESP_OK) {
+        err = err_drv;
+    }
+
+    uint32_t id = FF_VOLUMES;
+    s_get_context_id_by_wl_handle(wl_handle, &id);
+    free(s_ctx[id]);
+    s_ctx[id] = NULL;
+
     return err;
 }
 
-// esp_err_t esp_vfs_fat_spiflash_format_rw_wl(const char* base_path,const char* partition_label, wl_handle_t wl_handle)
+esp_err_t esp_vfs_fat_spiflash_format_rw_wl(const char* base_path, const char* partition_label)
-// {
+{
-//     esp_err_t err = ESP_FAIL;
+    esp_err_t ret = ESP_OK;
-//     BYTE pdrv = ff_diskio_get_pdrv_wl(wl_handle);
+    bool partition_was_mounted = false;
-//     if (pdrv != 0xff) {
-//         ESP_LOGD(TAG, "handle ID: pdrv", pdrv);
-//         err = esp_vfs_fat_spiflash_unmount_rw_wl(base_path, wl_handle);
-//         if (err != ESP_OK) {
-//             ESP_LOGE(TAG, "unmounting fail");
-//             return err;
-//         }
-//     }
 
-//     const esp_partition_t *partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA,
+    wl_handle_t temp_handle = WL_INVALID_HANDLE;
-//                                                                 ESP_PARTITION_SUBTYPE_DATA_FAT,
+    uint32_t id = FF_VOLUMES;
-//                                                                 partition_label);
+    char drv[3] = {0, ':', 0};
-//     if (!partition) {
-//         ESP_LOGE(TAG, "Failed to find FATFS partition (type='data', subtype='fat', partition_label='%s'). Check the partition table.", partition_label);
-//         return ESP_ERR_NOT_FOUND;
-//     }
-//     err = esp_partition_erase_range(partition, 0, partition->size);
-//     if (err != ESP_OK) {
 
-//     }
+    bool found = s_get_context_id_by_label(partition_label, &id);
+    if (!found) {
+        const esp_vfs_fat_mount_config_t mount_config = {
+            .max_files = 1,
+            .format_if_mount_failed = true,
+        };
+        ESP_RETURN_ON_ERROR(esp_vfs_fat_spiflash_mount_rw_wl(base_path, partition_label, &mount_config, &temp_handle), TAG, "Failed to mount");
+        found = s_get_context_id_by_label(partition_label, &id);
+        assert(found);
+    } else {
+        partition_was_mounted = true;
+    }
 
-// }
+    //unmount
+    drv[1] = (char)('0' + s_ctx[id]->pdrv);
+    f_mount(0, drv, 0);
+
+    const size_t workbuf_size = 4096;
+    void *workbuf = ff_memalloc(workbuf_size);
+    if (workbuf == NULL) {
+        ret = ESP_ERR_NO_MEM;
+        goto mount_back;
+    }
+    size_t alloc_unit_size = esp_vfs_fat_get_allocation_unit_size(CONFIG_WL_SECTOR_SIZE, s_ctx[id]->mount_config.allocation_unit_size);
+    ESP_LOGI(TAG, "Formatting FATFS partition, allocation unit size=%d", alloc_unit_size);
+    const MKFS_PARM opt = {(BYTE)(FM_ANY | FM_SFD), 0, 0, 0, alloc_unit_size};
+    FRESULT fresult = f_mkfs(drv, &opt, workbuf, workbuf_size);
+    free(workbuf);
+    workbuf = NULL;
+    ESP_GOTO_ON_FALSE(fresult == FR_OK, ESP_FAIL, mount_back, TAG, "f_mkfs failed (%d)", fresult);
+
+mount_back:
+    if (partition_was_mounted) {
+        esp_err_t err = s_f_mount_rw(s_ctx[id]->fs, drv, &s_ctx[id]->mount_config);
+        if (err != ESP_OK) {
+            ESP_LOGE(TAG, "failed to mount back, go to recycle");
+            goto recycle;
+        }
+    } else {
+        esp_vfs_fat_spiflash_unmount_rw_wl(base_path, s_ctx[id]->wlhandle);
+    }
+    return ret;
+
+recycle:
+    ff_diskio_unregister(s_ctx[id]->pdrv);
+    ff_diskio_clear_pdrv_wl(s_ctx[id]->wlhandle);
+    wl_unmount(s_ctx[id]->wlhandle);
+    esp_vfs_fat_unregister_path(base_path);
+    free(s_ctx[id]);
+    s_ctx[id] = NULL;
+    ESP_LOGE(TAG, "failed to format, resources recycled, please mount again");
+    return ret;
+}
 
 
 esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
@@ -196,7 +320,6 @@ esp_err_t esp_vfs_fat_spiflash_unmount_ro(const char* base_path, const char* par
     return err;
 }
 
-
 esp_err_t esp_vfs_fat_spiflash_mount(const char* base_path,
     const char* partition_label,
     const esp_vfs_fat_mount_config_t* mount_config,

examples/storage/wear_levelling/main/wear_levelling_example_main.c

@@ -17,6 +17,8 @@
 #include "esp_vfs_fat.h"
 #include "esp_system.h"
 
+#define EXAMPLE_MAX_CHAR_SIZE    128
+
 static const char *TAG = "example";
 
 // Handle of the wear levelling library instance
@@ -25,6 +27,42 @@ static wl_handle_t s_wl_handle = WL_INVALID_HANDLE;
 // Mount path for the partition
 const char *base_path = "/spiflash";
 
+static esp_err_t s_example_write_file(char *path, char *data)
+{
+    ESP_LOGI(TAG, "Opening file");
+    FILE *f = fopen(path, "wb");
+    if (f == NULL) {
+        ESP_LOGE(TAG, "Failed to open file for writing");
+        return ESP_FAIL;
+    }
+    fprintf(f, data);
+    fclose(f);
+    ESP_LOGI(TAG, "File written");
+
+    return ESP_OK;
+}
+
+static esp_err_t s_example_read_file(char *path)
+{
+    ESP_LOGI(TAG, "Reading file");
+    FILE *f = fopen(path, "rb");
+    if (f == NULL) {
+        ESP_LOGE(TAG, "Failed to open file for reading");
+        return ESP_FAIL;
+    }
+    char line[EXAMPLE_MAX_CHAR_SIZE];
+    fgets(line, sizeof(line), f);
+    fclose(f);
+    // strip newline
+    char *pos = strchr(line, '\n');
+    if (pos) {
+        *pos = '\0';
+    }
+    ESP_LOGI(TAG, "Read from file: '%s'", line);
+
+    return ESP_OK;
+}
+
 void app_main(void)
 {
     ESP_LOGI(TAG, "Mounting FAT filesystem");
@@ -40,32 +78,49 @@ void app_main(void)
         ESP_LOGE(TAG, "Failed to mount FATFS (%s)", esp_err_to_name(err));
         return;
     }
-    ESP_LOGI(TAG, "Opening file");
-    FILE *f = fopen("/spiflash/hello.txt", "wb");
-    if (f == NULL) {
-        ESP_LOGE(TAG, "Failed to open file for writing");
-        return;
-    }
-    fprintf(f, "written using ESP-IDF %s\n", esp_get_idf_version());
-    fclose(f);
-    ESP_LOGI(TAG, "File written");
 
-    // Open file for reading
+    //Create file and write
-    ESP_LOGI(TAG, "Reading file");
+    char data[EXAMPLE_MAX_CHAR_SIZE];
-    f = fopen("/spiflash/hello.txt", "rb");
+    snprintf(data, EXAMPLE_MAX_CHAR_SIZE, "%s %s\n", "hello world, from ESP-IDF", esp_get_idf_version());
-    if (f == NULL) {
+    err = s_example_write_file("/spiflash/hello.txt", data);
-        ESP_LOGE(TAG, "Failed to open file for reading");
+    if (err != ESP_OK) {
         return;
     }
-    char line[128];
+
-    fgets(line, sizeof(line), f);
+    //Open file for reading
-    fclose(f);
+    err = s_example_read_file("/spiflash/hello.txt");
-    // strip newline
+    if (err != ESP_OK) {
-    char *pos = strchr(line, '\n');
+        return;
-    if (pos) {
+    }
-        *pos = '\0';
+
+    // Format FATFS
+    err = esp_vfs_fat_spiflash_format_rw_wl(base_path, "storage");
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to format FATFS (%s)", esp_err_to_name(err));
+        return;
+    }
+
+    struct stat st;
+    if (stat("/spiflash/hello.txt", &st) == 0) {
+        ESP_LOGI(TAG, "file still exists");
+        return;
+    } else {
+        ESP_LOGI(TAG, "file doesnt exist, format done");
+    }
+
+    //Create file and write
+    memset(data, 0, EXAMPLE_MAX_CHAR_SIZE);
+    snprintf(data, EXAMPLE_MAX_CHAR_SIZE, "%s %s\n", "nihao shijie, from ESP-IDF", esp_get_idf_version());
+    err = s_example_write_file("/spiflash/nihao.txt", data);
+    if (err != ESP_OK) {
+        return;
+    }
+
+    //Open file for reading
+    err = s_example_read_file("/spiflash/nihao.txt");
+    if (err != ESP_OK) {
+        return;
     }
-    ESP_LOGI(TAG, "Read from file: '%s'", line);
 
     // Unmount FATFS
     ESP_LOGI(TAG, "Unmounting FAT filesystem");

examples/storage/wear_levelling/pytest_wear_levelling_example.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Unlicense OR CC0-1.0
 
 
@@ -16,7 +16,13 @@ def test_wear_levelling_example(dut: Dut) -> None:
                     'example: Opening file',
                     'example: File written',
                     'example: Reading file',
-                    re.compile(str.encode('example: Read from file: \'written using ESP-IDF \\S+\'')),
+                    re.compile(str.encode('example: Read from file: \'hello world, from ESP-IDF \\S+\'')),
+                    re.compile(str.encode('vfs_fat_spiflash: Formatting FATFS partition, allocation unit size=\\S+')),
+                    'example: file doesnt exist, format done',
+                    'example: Opening file',
+                    'example: File written',
+                    'example: Reading file',
+                    re.compile(str.encode('example: Read from file: \'nihao shijie, from ESP-IDF \\S+\'')),
                     'example: Unmounting FAT filesystem',
                     'example: Done')