diff options
Diffstat (limited to 'lib/fatfs/vfs/esp_vfs_fat.h')
| -rw-r--r-- | lib/fatfs/vfs/esp_vfs_fat.h | 118 |
1 files changed, 110 insertions, 8 deletions
diff --git a/lib/fatfs/vfs/esp_vfs_fat.h b/lib/fatfs/vfs/esp_vfs_fat.h index 3e7b165b..7b87818f 100644 --- a/lib/fatfs/vfs/esp_vfs_fat.h +++ b/lib/fatfs/vfs/esp_vfs_fat.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 */ @@ -7,8 +7,7 @@ #pragma once #include <stddef.h> #include "esp_err.h" -#include "driver/gpio.h" -#include "driver/sdmmc_types.h" +#include "sd_protocol_types.h" #include "driver/sdspi_host.h" #include "ff.h" #include "wear_levelling.h" @@ -18,9 +17,19 @@ 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 @@ -30,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 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 conf pointer to esp_vfs_fat_conf_t configuration structure * @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, - size_t max_files, FATFS** out_fs); +esp_err_t esp_vfs_fat_register_cfg(const esp_vfs_fat_conf_t* conf, FATFS** out_fs); /** * @brief Un-register FATFS from VFS @@ -96,8 +102,26 @@ typedef struct { * Doesn't do anything for other memory storage media. */ bool disk_status_check_enable; + /** + * Use 1 FAT (File Allocation Tables) instead of 2. + * This decreases reliability, but makes more space available + * (usually only one sector). + * Note that this option has effect only when the filesystem is formatted. + * When mounting an already-formatted partition, the actual number of FATs + * may be different. + */ + bool use_one_fat; } esp_vfs_fat_mount_config_t; +#define VFS_FAT_MOUNT_DEFAULT_CONFIG() \ + { \ + .format_if_mount_failed = false, \ + .max_files = 5, \ + .allocation_unit_size = 0, \ + .disk_status_check_enable = false, \ + .use_one_fat = false, \ + } + // Compatibility definition typedef esp_vfs_fat_mount_config_t esp_vfs_fat_sdmmc_mount_config_t; @@ -208,6 +232,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 * * @note @@ -268,6 +311,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 * * @note @@ -337,8 +401,46 @@ 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); +/** + * @brief Create a file with contiguous space at given path + * + * @note The file cannot exist before calling this function (or the file size has to be 0) + * For more information see documentation for `f_expand` from FATFS library + * + * @param base_path Base path of the partition examined (e.g. "/spiflash") + * @param full_path Full path of the file (e.g. "/spiflash/ABC.TXT") + * @param size File size expanded to, number of bytes in size to prepare or allocate for the file + * @param alloc_now True == allocate space now, false == prepare to allocate -- see `f_expand` from FATFS + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if invalid arguments (e.g. any of arguments are NULL or size lower or equal to 0) + * - ESP_ERR_INVALID_STATE if partition not found + * - ESP_FAIL if another FRESULT error (saved in errno) + */ +esp_err_t esp_vfs_fat_create_contiguous_file(const char* base_path, const char* full_path, uint64_t size, bool alloc_now); + +/** + * @brief Test if a file is contiguous in the FAT filesystem + * + * @param base_path Base path of the partition examined (e.g. "/spiflash") + * @param full_path Full path of the file (e.g. "/spiflash/ABC.TXT") + * @param[out] is_contiguous True == allocate space now, false == prepare to allocate -- see `f_expand` from FATFS + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if invalid arguments (e.g. any of arguments are NULL) + * - ESP_ERR_INVALID_STATE if partition not found + * - ESP_FAIL if another FRESULT error (saved in errno) + */ +esp_err_t esp_vfs_fat_test_contiguous_file(const char* base_path, const char* full_path, bool* is_contiguous); + /** @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); + +/** * @deprecated Please use `esp_vfs_fat_spiflash_mount_rw_wl` instead */ esp_err_t esp_vfs_fat_spiflash_mount(const char* base_path, |