Merge branch 'feature/vfs_fat_config_register' into 'master'

feat(storage/fatfs): Switch to a config struct for VFS FAT registration

Closes IDF-9174

See merge request espressif/esp-idf!28977

components/fatfs/vfs/esp_vfs_fat.h

@@ -16,10 +16,20 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Configuration structure for esp_vfs_fat_register
+ */
+typedef struct {
+    const char* base_path; /*!< Path prefix where FATFS should be registered, */
+    const char* fat_drive; /*!< FATFS drive specification; if only one drive is used, can be an empty string. */
+    size_t max_files;      /*!< Maximum number of files which can be open at the same time. */
+} esp_vfs_fat_conf_t;
+
 /**
  * @brief Register FATFS with VFS component
  *
  * This function registers given FAT drive in VFS, at the specified base path.
+ * Input arguments are held in esp_vfs_fat_conf_t structure.
  * If only one drive is used, fat_drive argument can be an empty string.
  * Refer to FATFS library documentation on how to specify FAT drive.
  * This function also allocates FATFS structure which should be used for f_mount
@@ -29,17 +39,14 @@ extern "C" {
  *       POSIX and C standard library IO function with FATFS. You need to mount
  *       desired drive into FATFS separately.
  *
- * @param base_path  path prefix where FATFS should be registered
+ * @param conf  pointer to esp_vfs_fat_conf_t configuration structure
- * @param fat_drive  FATFS drive specification; if only one drive is used, can be an empty string
- * @param max_files  maximum number of files which can be open at the same time
  * @param[out] out_fs  pointer to FATFS structure which can be used for FATFS f_mount call is returned via this argument.
  * @return
  *      - ESP_OK on success
  *      - ESP_ERR_INVALID_STATE if esp_vfs_fat_register was already called
  *      - ESP_ERR_NO_MEM if not enough memory or too many VFSes already registered
  */
-esp_err_t esp_vfs_fat_register(const char* base_path, const char* fat_drive,
+esp_err_t esp_vfs_fat_register_cfg(const esp_vfs_fat_conf_t* conf, FATFS** out_fs);
-        size_t max_files, FATFS** out_fs);
 
 /**
  * @brief Un-register FATFS from VFS
@@ -395,6 +402,12 @@ esp_err_t esp_vfs_fat_spiflash_unmount_ro(const char* base_path, const char* par
 esp_err_t esp_vfs_fat_info(const char* base_path, uint64_t* out_total_bytes, uint64_t* out_free_bytes);
 
 /** @cond */
+/**
+ * @deprecated Please use `esp_vfs_fat_register_cfg` instead
+ */
+esp_err_t esp_vfs_fat_register(const char* base_path, const char* fat_drive,
+        size_t max_files, FATFS** out_fs) __attribute__((deprecated("Please use esp_vfs_fat_register_cfg instead")));
+
 /**
  * @deprecated Please use `esp_vfs_fat_spiflash_mount_rw_wl` instead
  */

components/fatfs/vfs/vfs_fat.c

@@ -11,6 +11,7 @@
 #include <sys/errno.h>
 #include <sys/fcntl.h>
 #include <sys/lock.h>
+#include "esp_vfs_fat.h"
 #include "esp_vfs.h"
 #include "esp_log.h"
 #include "ff.h"
@@ -112,7 +113,17 @@ static size_t find_unused_context_index(void)
 
 esp_err_t esp_vfs_fat_register(const char* base_path, const char* fat_drive, size_t max_files, FATFS** out_fs)
 {
-    size_t ctx = find_context_index_by_path(base_path);
+    esp_vfs_fat_conf_t conf = {
+        .base_path = base_path,
+        .fat_drive = fat_drive,
+        .max_files = max_files,
+    };
+    return esp_vfs_fat_register_cfg(&conf, out_fs);
+}
+
+esp_err_t esp_vfs_fat_register_cfg(const esp_vfs_fat_conf_t* conf, FATFS** out_fs)
+{
+    size_t ctx = find_context_index_by_path(conf->base_path);
     if (ctx < FF_VOLUMES) {
         return ESP_ERR_INVALID_STATE;
     }
@@ -153,6 +164,7 @@ esp_err_t esp_vfs_fat_register(const char* base_path, const char* fat_drive, siz
 #endif // CONFIG_VFS_SUPPORT_DIR
     };
 
+    size_t max_files = conf->max_files;
     if (max_files < 1) {
         max_files = 1;  // ff_memalloc(max_files * sizeof(bool)) below will fail if max_files == 0
     }
@@ -170,10 +182,10 @@ esp_err_t esp_vfs_fat_register(const char* base_path, const char* fat_drive, siz
     }
     memset(fat_ctx->o_append, 0, max_files * sizeof(bool));
     fat_ctx->max_files = max_files;
-    strlcpy(fat_ctx->fat_drive, fat_drive, sizeof(fat_ctx->fat_drive) - 1);
+    strlcpy(fat_ctx->fat_drive, conf->fat_drive, sizeof(fat_ctx->fat_drive) - 1);
-    strlcpy(fat_ctx->base_path, base_path, sizeof(fat_ctx->base_path) - 1);
+    strlcpy(fat_ctx->base_path, conf->base_path, sizeof(fat_ctx->base_path) - 1);
 
-    esp_err_t err = esp_vfs_register(base_path, &vfs, fat_ctx);
+    esp_err_t err = esp_vfs_register(conf->base_path, &vfs, fat_ctx);
     if (err != ESP_OK) {
         free(fat_ctx->o_append);
         free(fat_ctx);

components/fatfs/vfs/vfs_fat_sdmmc.c

@@ -166,12 +166,17 @@ static esp_err_t mount_to_vfs_fat(const esp_vfs_fat_mount_config_t *mount_config
     char drv[3] = {(char)('0' + pdrv), ':', 0};
 
     // connect FATFS to VFS
-    err = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
+    esp_vfs_fat_conf_t conf = {
+        .base_path = base_path,
+        .fat_drive = drv,
+        .max_files = mount_config->max_files,
+    };
+    err = esp_vfs_fat_register_cfg(&conf, &fs);
     *out_fs = fs;
     if (err == ESP_ERR_INVALID_STATE) {
         // it's okay, already registered with VFS
     } else if (err != ESP_OK) {
-        ESP_LOGD(TAG, "esp_vfs_fat_register failed 0x(%x)", err);
+        ESP_LOGD(TAG, "esp_vfs_fat_register_cfg failed 0x(%x)", err);
         goto fail;
     }
 

components/fatfs/vfs/vfs_fat_spiflash.c

@@ -142,11 +142,16 @@ esp_err_t esp_vfs_fat_spiflash_mount_rw_wl(const char* base_path,
     ESP_GOTO_ON_ERROR(ff_diskio_register_wl_partition(pdrv, *wl_handle), fail, TAG, "ff_diskio_register_wl_partition failed pdrv=%i, error - 0x(%x)", pdrv, ret);
 
     FATFS *fs;
-    ret = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
+    esp_vfs_fat_conf_t conf = {
+        .base_path = base_path,
+        .fat_drive = drv,
+        .max_files = mount_config->max_files,
+    };
+    ret = esp_vfs_fat_register_cfg(&conf, &fs);
     if (ret == ESP_ERR_INVALID_STATE) {
         // it's okay, already registered with VFS
     } else if (ret != ESP_OK) {
-        ESP_LOGD(TAG, "esp_vfs_fat_register failed 0x(%x)", ret);
+        ESP_LOGD(TAG, "esp_vfs_fat_register_cfg failed 0x(%x)", ret);
         goto fail;
     }
 
@@ -315,11 +320,16 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
     ESP_GOTO_ON_ERROR(ff_diskio_register_raw_partition(pdrv, data_partition), fail, TAG, "ff_diskio_register_raw_partition failed pdrv=%i, error - 0x(%x)", pdrv, ret);
 
     FATFS *fs;
-    ret = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
+    esp_vfs_fat_conf_t conf = {
+        .base_path = base_path,
+        .fat_drive = drv,
+        .max_files = mount_config->max_files,
+    };
+    ret = esp_vfs_fat_register_cfg(&conf, &fs);
     if (ret == ESP_ERR_INVALID_STATE) {
         // it's okay, already registered with VFS
     } else if (ret != ESP_OK) {
-        ESP_LOGD(TAG, "esp_vfs_fat_register failed 0x(%x)", ret);
+        ESP_LOGD(TAG, "esp_vfs_fat_register_cfg failed 0x(%x)", ret);
         goto fail;
     }
 

components/vfs/include/esp_vfs.h

@@ -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
  */
@@ -46,17 +46,17 @@ extern "C" {
 /**
  * Default value of flags member in esp_vfs_t structure.
  */
-#define ESP_VFS_FLAG_DEFAULT        0
+#define ESP_VFS_FLAG_DEFAULT (1 << 0)
 
 /**
  * Flag which indicates that FS needs extra context pointer in syscalls.
  */
-#define ESP_VFS_FLAG_CONTEXT_PTR    1
+#define ESP_VFS_FLAG_CONTEXT_PTR (1 << 1)
 
 /**
  * Flag which indicates that FS is located on read-only partition.
  */
-#define ESP_VFS_FLAG_READONLY_FS  2
+#define ESP_VFS_FLAG_READONLY_FS (1 << 2)
 
 /*
  * @brief VFS identificator used for esp_vfs_register_with_id()