Merge branch 'feature/vfs_fat_x_little_revamp' into 'master'

feat(fatfs): Add format functions with a config parameter

Closes IDF-9111

See merge request espressif/esp-idf!28683

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

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -23,6 +23,7 @@
 #include "wear_levelling.h"
 #include "esp_partition.h"
 #include "esp_memory_utils.h"
+#include "vfs_fat_internal.h"
 
 void app_main(void)
 {
@@ -32,7 +33,7 @@ void app_main(void)
 static wl_handle_t s_test_wl_handle;
 static void test_setup(void)
 {
-    esp_vfs_fat_sdmmc_mount_config_t mount_config = {
+    esp_vfs_fat_mount_config_t mount_config = {
         .format_if_mount_failed = true,
         .max_files = 5,
     };
@@ -45,14 +46,32 @@ static void test_teardown(void)
     TEST_ESP_OK(esp_vfs_fat_spiflash_unmount_rw_wl("/spiflash", s_test_wl_handle));
 }
 
-TEST_CASE("(WL) can format partition", "[fatfs][wear_levelling][timeout=180]")
+TEST_CASE("(WL) can format partition", "[fatfs][wear_levelling][timeout=120]")
 {
     TEST_ESP_OK(esp_vfs_fat_spiflash_format_rw_wl("/spiflash", NULL));
     test_setup();
+    vfs_fat_spiflash_ctx_t* ctx = get_vfs_fat_spiflash_ctx(s_test_wl_handle);
+    TEST_ASSERT_NOT_NULL(ctx);
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 2); // 2 FATs are created by default
     test_teardown();
 }
 
-TEST_CASE("(WL) can format when the FAT is mounted already", "[fatfs][wear_levelling][timeout=180]")
+TEST_CASE("(WL) can format partition with config", "[fatfs][wear_levelling][timeout=120]")
+{
+    esp_vfs_fat_mount_config_t format_config = {
+        .format_if_mount_failed = true,
+        .max_files = 5,
+        .use_one_fat = true,
+    };
+    TEST_ESP_OK(esp_vfs_fat_spiflash_format_cfg_rw_wl("/spiflash", NULL, &format_config));
+    test_setup();
+    vfs_fat_spiflash_ctx_t* ctx = get_vfs_fat_spiflash_ctx(s_test_wl_handle);
+    TEST_ASSERT_NOT_NULL(ctx);
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 1);
+    test_teardown();
+}
+
+TEST_CASE("(WL) can format when the FAT is mounted already", "[fatfs][wear_levelling][timeout=120]")
 {
     test_setup();
     TEST_ESP_OK(esp_vfs_fat_spiflash_format_rw_wl("/spiflash", NULL));
@@ -61,9 +80,28 @@ TEST_CASE("(WL) can format when the FAT is mounted already", "[fatfs][wear_level
     test_teardown();
 }
 
-TEST_CASE("(WL) can format specified FAT when more are mounted", "[fatfs][wear_levelling][timeout=180]")
+TEST_CASE("(WL) can format when the FAT is mounted already with config", "[fatfs][wear_levelling][timeout=120]")
+{
+    TEST_ESP_OK(esp_vfs_fat_spiflash_format_rw_wl("/spiflash", NULL)); // To reset the FAT number to 2
+    test_setup();
+    vfs_fat_spiflash_ctx_t* ctx = get_vfs_fat_spiflash_ctx(s_test_wl_handle);
+    TEST_ASSERT_NOT_NULL(ctx);
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 2);
+    esp_vfs_fat_mount_config_t format_config = {
+        .format_if_mount_failed = true,
+        .max_files = 5,
+        .use_one_fat = true,
+    };
+    TEST_ESP_OK(esp_vfs_fat_spiflash_format_cfg_rw_wl("/spiflash", NULL, &format_config));
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 1);
+    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 format specified FAT when more are mounted", "[fatfs][wear_levelling][timeout=120]")
 {
-    esp_vfs_fat_sdmmc_mount_config_t mount_config = {
+    esp_vfs_fat_mount_config_t mount_config = {
         .format_if_mount_failed = true,
         .max_files = 5,
     };
@@ -126,7 +164,7 @@ TEST_CASE("(WL) pwrite() works well", "[fatfs][wear_levelling]")
 TEST_CASE("(WL) can open maximum number of files", "[fatfs][wear_levelling]")
 {
     size_t max_files = FOPEN_MAX - 3; /* account for stdin, stdout, stderr */
-    esp_vfs_fat_sdmmc_mount_config_t mount_config = {
+    esp_vfs_fat_mount_config_t mount_config = {
         .format_if_mount_failed = true,
         .max_files = max_files
     };

components/fatfs/test_apps/sdcard/main/test_fatfs_sdmmc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -22,6 +22,7 @@
 #include "ff.h"
 #include "test_fatfs_common.h"
 #include "soc/soc_caps.h"
+#include "vfs_fat_internal.h"
 
 #if CONFIG_IDF_TARGET_ESP32
 #define SDSPI_MISO_PIN 2
@@ -102,6 +103,35 @@ TEST_CASE("(SD) can format partition", "[fatfs][sdmmc][timeout=180]")
     test_teardown_sdmmc(card);
 }
 
+TEST_CASE("(SD) can format partition with config", "[fatfs][sdmmc][timeout=180]")
+{
+    sdmmc_card_t *card = NULL;
+    test_setup_sdmmc(&card);
+    vfs_fat_sd_ctx_t* ctx = get_vfs_fat_get_sd_ctx(card);
+    TEST_ASSERT_NOT_NULL(ctx);
+
+    esp_vfs_fat_mount_config_t format_config = {
+        .format_if_mount_failed = true,
+        .max_files = 5,
+        .allocation_unit_size = 16 * 1024,
+        .use_one_fat = true,
+    };
+    TEST_ESP_OK(esp_vfs_fat_sdcard_format_cfg("/sdcard", card, &format_config));
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 1);
+
+    test_fatfs_create_file_with_text(test_filename, fatfs_test_hello_str);
+    test_fatfs_read_file(test_filename);
+
+    format_config.use_one_fat = false;
+    TEST_ESP_OK(esp_vfs_fat_sdcard_format_cfg("/sdcard", card, &format_config));
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 2);
+
+    test_fatfs_create_file_with_text(test_filename, fatfs_test_hello_str);
+    test_fatfs_read_file(test_filename);
+
+    test_teardown_sdmmc(card);
+}
+
 TEST_CASE("(SD) can create and write file", "[fatfs][sdmmc]")
 {
     sdmmc_card_t *card = NULL;

components/fatfs/test_apps/sdcard/main/test_fatfs_sdspi.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -22,6 +22,7 @@
 #include "ff.h"
 #include "test_fatfs_common.h"
 #include "soc/soc_caps.h"
+#include "vfs_fat_internal.h"
 
 #if CONFIG_IDF_TARGET_ESP32
 #define SDSPI_MISO_PIN 2
@@ -89,7 +90,7 @@ static void test_teardown_sdspi(sdspi_mem_t* mem)
     HEAP_SIZE_CHECK(mem->heap_size, 0);
 }
 
-TEST_CASE("(SDSPI) write/read speed test", "[fatfs][sdspi]")
+TEST_CASE("(SDSPI) write/read speed test", "[fatfs][sdspi][timeout=120]")
 {
     sdspi_mem_t mem;
     size_t file_size = 1 * 1024 * 1024;
@@ -197,3 +198,55 @@ TEST_CASE("(SDSPI) can format card", "[fatfs][sdspi][timeout=180]")
     TEST_ESP_OK(esp_vfs_fat_sdcard_unmount(path, card));
     test_teardown_sdspi(&mem);
 }
+
+
+TEST_CASE("(SDSPI) can format card with config", "[fatfs][sdspi][timeout=180]")
+{
+    sdspi_mem_t mem;
+    test_setup_sdspi(&mem);
+
+    const char path[] = "/sdcard";
+    sdmmc_card_t *card;
+    card = NULL;
+    sdspi_device_config_t device_cfg = {
+        .gpio_cs = SDSPI_CS_PIN,
+        .host_id = SDSPI_HOST_ID,
+        .gpio_cd = SDSPI_SLOT_NO_CD,
+        .gpio_wp = SDSPI_SLOT_NO_WP,
+        .gpio_int = SDSPI_SLOT_NO_INT,
+    };
+
+    sdmmc_host_t host = SDSPI_HOST_DEFAULT();
+    host.slot = SDSPI_HOST_ID;
+    esp_vfs_fat_sdmmc_mount_config_t mount_config = {
+        .format_if_mount_failed = true,
+        .max_files = 5,
+        .allocation_unit_size = 64 * 1024,
+    };
+    TEST_ESP_OK(esp_vfs_fat_sdspi_mount(path, &host, &device_cfg, &mount_config, &card));
+
+    vfs_fat_sd_ctx_t* ctx = get_vfs_fat_get_sd_ctx(card);
+    TEST_ASSERT_NOT_NULL(ctx);
+
+    esp_vfs_fat_mount_config_t format_config = {
+        .format_if_mount_failed = true,
+        .max_files = 5,
+        .allocation_unit_size = 64 * 1024,
+        .use_one_fat = true,
+    };
+    TEST_ESP_OK(esp_vfs_fat_sdcard_format_cfg("/sdcard", card, &format_config));
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 1);
+
+    test_fatfs_create_file_with_text(s_test_filename, fatfs_test_hello_str);
+    test_fatfs_read_file(s_test_filename);
+
+    format_config.use_one_fat = false;
+    TEST_ESP_OK(esp_vfs_fat_sdcard_format_cfg("/sdcard", card, &format_config));
+    TEST_ASSERT_TRUE(ctx->fs->n_fats == 2);
+
+    test_fatfs_create_file_with_text(s_test_filename, fatfs_test_hello_str);
+    test_fatfs_read_file(s_test_filename);
+
+    TEST_ESP_OK(esp_vfs_fat_sdcard_unmount(path, card));
+    test_teardown_sdspi(&mem);
+}

components/fatfs/test_apps/sdcard/pytest_fatfs_sdcard.py

@@ -1,6 +1,5 @@
-# SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: CC0-1.0
-
 import pytest
 from pytest_embedded import Dut
 

components/fatfs/vfs/esp_vfs_fat.h

@@ -224,6 +224,25 @@ esp_err_t esp_vfs_fat_sdmmc_unmount(void) __attribute__((deprecated("Please use
  */
 esp_err_t esp_vfs_fat_sdcard_unmount(const char* base_path, sdmmc_card_t *card);
 
+/**
+ * @brief Format FAT filesystem with given configuration
+ *
+ * @note
+ * This API should be only called when the FAT is already mounted.
+ *
+ * @param base_path  Path where partition should be registered (e.g. "/sdcard")
+ * @param card       Pointer to the card handle, which should be initialised by calling `esp_vfs_fat_sdspi_mount` first
+ * @param cfg        Pointer to structure with extra parameters for formatting FATFS (only relevant fields are used).
+ *                   If NULL, the previous configuration will be used.
+ *
+ * @return
+ *        - ESP_OK
+ *        - ESP_ERR_INVALID_STATE: FAT partition isn't mounted, call esp_vfs_fat_sdmmc_mount or esp_vfs_fat_sdspi_mount first
+ *        - ESP_ERR_NO_MEM: if memory can not be allocated
+ *        - ESP_FAIL: fail to format it, or fail to mount back
+ */
+esp_err_t esp_vfs_fat_sdcard_format_cfg(const char *base_path, sdmmc_card_t *card, esp_vfs_fat_mount_config_t *cfg);
+
 /**
  * @brief Format FAT filesystem
  *
@@ -284,6 +303,27 @@ 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 with given configuration
+ *
+ * @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
+ * @param cfg              Pointer to structure with extra parameters for formatting FATFS (only relevant fields are used).
+ *                         If NULL and mounted the previous configuration will be used.
+ *                         If NULL and unmounted the default configuration will 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_cfg_rw_wl(const char* base_path, const char* partition_label, esp_vfs_fat_mount_config_t *cfg);
+
 /**
  * @brief Format FAT filesystem
  *

components/fatfs/vfs/vfs_fat.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -152,6 +152,11 @@ esp_err_t esp_vfs_fat_register(const char* base_path, const char* fat_drive, siz
         .utime_p = &vfs_fat_utime,
 #endif // CONFIG_VFS_SUPPORT_DIR
     };
+
+    if (max_files < 1) {
+        max_files = 1;  // ff_memalloc(max_files * sizeof(bool)) below will fail if max_files == 0
+    }
+
     size_t ctx_size = sizeof(vfs_fat_ctx_t) + max_files * sizeof(FIL);
     vfs_fat_ctx_t* fat_ctx = (vfs_fat_ctx_t*) ff_memalloc(ctx_size);
     if (fat_ctx == NULL) {

components/fatfs/vfs/vfs_fat_internal.h

@@ -1,23 +1,41 @@
-// Copyright 2018 Espressif Systems (Shanghai) PTE LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2018-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 
 #pragma once
 
 #include "esp_vfs_fat.h"
+#include "diskio_impl.h"
+#include "esp_partition.h"
+#include "sdmmc_cmd.h"
 #include <sys/param.h>
 #include <stddef.h>
 
+typedef enum {
+    FORMATTED_DURING_LAST_MOUNT = 1 << 0, // The FATFS partition was formatted during the last mount
+} vfs_fat_x_ctx_flags_t;
+
+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_x_ctx_flags_t flags;                //Flags
+} vfs_fat_spiflash_ctx_t;
+
+typedef struct vfs_fat_sd_ctx_t {
+    BYTE pdrv;                                  //Drive number that is mounted
+    esp_vfs_fat_mount_config_t mount_config;    //Mount configuration
+    FATFS *fs;                                  //FAT structure pointer that is registered
+    sdmmc_card_t *card;                         //Card info
+    char *base_path;                            //Path where partition is registered
+    vfs_fat_x_ctx_flags_t flags;                //Flags
+} vfs_fat_sd_ctx_t;
+
 static inline size_t esp_vfs_fat_get_allocation_unit_size(
         size_t sector_size, size_t requested_size)
 {
@@ -28,3 +46,6 @@ static inline size_t esp_vfs_fat_get_allocation_unit_size(
     alloc_unit_size = MIN(alloc_unit_size, max_size);
     return alloc_unit_size;
 }
+
+vfs_fat_spiflash_ctx_t* get_vfs_fat_spiflash_ctx(wl_handle_t wlhandle);
+vfs_fat_sd_ctx_t* get_vfs_fat_get_sd_ctx(const sdmmc_card_t *card);