alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'feature/fatfs_format_api' into 'master'

Browse Source 
fatfs: added APIs to format a FAT filesystem

Closes IDF-6046

See merge request espressif/esp-idf!21845
This commit is contained in:
Martin Vychodil 2023-02-16 19:59:31 +08:00
commit c58a84f893
17 changed files with 823 additions and 275 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
components/fatfs/test_apps/flash_wl/main/test_fatfs_flash_wl.c
View File

@ -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,
ESP_PARTITION_SUBTYPE_DATA_FAT, NULL);
esp_partition_erase_range(part, 0, part->size);
TEST_ESP_OK(esp_vfs_fat_spiflash_format_rw_wl("/spiflash", NULL));
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();

129
components/fatfs/test_apps/sdcard/main/test_fatfs_sdmmc.c
View File

@ -51,8 +51,9 @@
// No runner
#include "driver/sdmmc_host.h"
static void test_setup_sdmmc(void)
static void test_setup_sdmmc(sdmmc_card_t **out_card)
{
sdmmc_card_t *card = NULL;
sdmmc_host_t host = SDMMC_HOST_DEFAULT();
sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
esp_vfs_fat_sdmmc_mount_config_t mount_config = {
@ -60,12 +61,13 @@ static void test_setup_sdmmc(void)
.max_files = 5,
.allocation_unit_size = 16 * 1024
};
TEST_ESP_OK(esp_vfs_fat_sdmmc_mount("/sdcard", &host, &slot_config, &mount_config, NULL));
TEST_ESP_OK(esp_vfs_fat_sdmmc_mount("/sdcard", &host, &slot_config, &mount_config, &card));
*out_card = card;
}
static void test_teardown_sdmmc(void)
static void test_teardown_sdmmc(sdmmc_card_t *card)
{
TEST_ESP_OK(esp_vfs_fat_sdmmc_unmount());
TEST_ESP_OK(esp_vfs_fat_sdcard_unmount("/sdcard", card));
}
static const char* test_filename = "/sdcard/hello.txt";
@ -90,118 +92,144 @@ TEST_CASE("Mount fails cleanly without card inserted", "[fatfs][ignore]")
HEAP_SIZE_CHECK(heap_size, 0);
}
TEST_CASE("(SD) can format partition", "[fatfs][sdmmc]")
{
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
TEST_ESP_OK(esp_vfs_fat_sdcard_format("/sdcard", card));
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]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_create_file_with_text(test_filename, fatfs_test_hello_str);
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) can read file", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_create_file_with_text(test_filename, fatfs_test_hello_str);
test_fatfs_read_file(test_filename);
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) can read file with pread()", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_create_file_with_text(test_filename, fatfs_test_hello_str);
test_fatfs_pread_file(test_filename);
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) pwrite() works well", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_pwrite_file(test_filename);
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) overwrite and append file", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_overwrite_append(test_filename);
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) can lseek", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_lseek("/sdcard/seek.txt");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) can truncate", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_truncate_file("/sdcard/truncate.txt");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) can ftruncate", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_ftruncate_file("/sdcard/ftrunc.txt");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) stat returns correct values", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_stat("/sdcard/stat.txt", "/sdcard");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) utime sets modification time", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_utime("/sdcard/utime.txt", "/sdcard");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) unlink removes a file", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_unlink("/sdcard/unlink.txt");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) link copies a file, rename moves a file", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_link_rename("/sdcard/link");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) can create and remove directories", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_mkdir_rmdir("/sdcard/dir");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) can opendir root directory of FS", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_can_opendir("/sdcard");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) opendir, readdir, rewinddir, seekdir work as expected", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_opendir_readdir_rewinddir("/sdcard/dir");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) multiple tasks can use same volume", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_concurrent("/sdcard/f");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
static void sdmmc_speed_test(void *buf, size_t buf_size, size_t file_size, bool write);
@ -231,6 +259,7 @@ TEST_CASE("(SD) write/read speed test", "[fatfs][sdmmc]")
static void sdmmc_speed_test(void *buf, size_t buf_size, size_t file_size, bool write)
{
sdmmc_card_t *card = NULL;
sdmmc_host_t host = SDMMC_HOST_DEFAULT();
host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
@ -239,11 +268,11 @@ static void sdmmc_speed_test(void *buf, size_t buf_size, size_t file_size, bool
.max_files = 5,
.allocation_unit_size = 64 * 1024
};
TEST_ESP_OK(esp_vfs_fat_sdmmc_mount("/sdcard", &host, &slot_config, &mount_config, NULL));
TEST_ESP_OK(esp_vfs_fat_sdmmc_mount("/sdcard", &host, &slot_config, &mount_config, &card));
test_fatfs_rw_speed("/sdcard/4mb.bin", buf, buf_size, file_size, write);
TEST_ESP_OK(esp_vfs_fat_sdmmc_unmount());
TEST_ESP_OK(esp_vfs_fat_sdcard_unmount("/sdcard", card));
}
TEST_CASE("(SD) mount two FAT partitions, SDMMC and WL, at the same time", "[fatfs][sdmmc]")
@ -265,17 +294,18 @@ TEST_CASE("(SD) mount two FAT partitions, SDMMC and WL, at the same time", "[fat
/* Mount FATFS in SD can WL at the same time. Create a file on each FS */
wl_handle_t wl_handle = WL_INVALID_HANDLE;
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
TEST_ESP_OK(esp_vfs_fat_spiflash_mount_rw_wl("/spiflash", NULL, &mount_config, &wl_handle));
unlink(filename_sd);
unlink(filename_wl);
test_fatfs_create_file_with_text(filename_sd, str_sd);
test_fatfs_create_file_with_text(filename_wl, str_wl);
TEST_ESP_OK(esp_vfs_fat_spiflash_unmount_rw_wl("/spiflash", wl_handle));
test_teardown_sdmmc();
test_teardown_sdmmc(card);
/* Check that the file "sd.txt" was created on FS in SD, and has the right data */
test_setup_sdmmc();
test_setup_sdmmc(&card);
TEST_ASSERT_NULL(fopen(filename_wl, "r"));
FILE* f = fopen(filename_sd, "r");
TEST_ASSERT_NOT_NULL(f);
@ -283,7 +313,7 @@ TEST_CASE("(SD) mount two FAT partitions, SDMMC and WL, at the same time", "[fat
TEST_ASSERT_NOT_NULL(fgets(buf, sizeof(buf) - 1, f));
TEST_ASSERT_EQUAL(0, strcmp(buf, str_sd));
fclose(f);
test_teardown_sdmmc();
test_teardown_sdmmc(card);
/* Check that the file "wl.txt" was created on FS in WL, and has the right data */
TEST_ESP_OK(esp_vfs_fat_spiflash_mount_rw_wl("/spiflash", NULL, &mount_config, &wl_handle));
@ -307,25 +337,28 @@ static const char* test_filename_utf_8 = "/sdcard/测试文件.txt";
TEST_CASE("(SD) can read file using UTF-8 encoded strings", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_create_file_with_text(test_filename_utf_8, fatfs_test_hello_str_utf);
test_fatfs_read_file_utf_8(test_filename_utf_8);
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
TEST_CASE("(SD) opendir, readdir, rewinddir, seekdir work as expected using UTF-8 encoded strings", "[fatfs][ignore]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_opendir_readdir_rewinddir_utf_8("/sdcard/目录");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
#endif // CONFIG_FATFS_API_ENCODING_UTF_8 && CONFIG_FATFS_CODEPAGE == 936
TEST_CASE("(SD) can get partition info", "[fatfs][sdmmc]")
{
test_setup_sdmmc();
sdmmc_card_t *card = NULL;
test_setup_sdmmc(&card);
test_fatfs_info("/sdcard", "/sdcard/test.txt");
test_teardown_sdmmc();
test_teardown_sdmmc(card);
}
#endif //!TEMPORARY_DISABLED_FOR_TARGETS(ESP32S3)

32
components/fatfs/test_apps/sdcard/main/test_fatfs_sdspi.c
View File

@ -53,6 +53,7 @@ typedef struct sdspi_mem {
uint32_t* buf;
} sdspi_mem_t;
static const char* s_test_filename = "/sdcard/hello.txt";
static void sdspi_speed_test(void *buf, size_t buf_size, size_t file_size, bool write);
static void test_setup_sdspi(sdspi_mem_t* mem)
@ -159,3 +160,34 @@ TEST_CASE("(SDSPI) can get partition info", "[fatfs][sdspi]")
test_teardown_sdspi(&mem);
}
TEST_CASE("(SDSPI) can format card", "[fatfs][sdspi]")
{
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));
TEST_ESP_OK(esp_vfs_fat_sdcard_format("/sdcard", card));
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);
}

39
components/fatfs/vfs/esp_vfs_fat.h
View File

@ -194,7 +194,7 @@ esp_err_t esp_vfs_fat_sdspi_mount(const char* base_path,
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount hasn't been called
*/
esp_err_t esp_vfs_fat_sdmmc_unmount(void);
esp_err_t esp_vfs_fat_sdmmc_unmount(void) __attribute__((deprecated("Please use esp_vfs_fat_sdcard_unmount instead")));
/**
* @brief Unmount an SD card from the FAT filesystem and release resources acquired using
@ -207,6 +207,23 @@ esp_err_t esp_vfs_fat_sdmmc_unmount(void);
*/
esp_err_t esp_vfs_fat_sdcard_unmount(const char* base_path, sdmmc_card_t *card);
/**
* @brief Format FAT filesystem
*
* @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
*
* @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(const char *base_path, sdmmc_card_t *card);
/**
* @brief Convenience function to initialize FAT filesystem in SPI flash and register it in VFS
*
@ -250,6 +267,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
*
@ -285,7 +320,7 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount_rw_wl hasn't been called
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount_ro hasn't been called
*/
esp_err_t esp_vfs_fat_spiflash_unmount_ro(const char* base_path, const char* partition_label);

239
components/fatfs/vfs/vfs_fat_sdmmc.c
View File

@ -22,9 +22,6 @@
#endif
static const char* TAG = "vfs_fat_sdmmc";
static sdmmc_card_t* s_card = NULL;
static uint8_t s_pdrv = FF_DRV_NOT_USED;
static char * s_base_path = NULL;
#define CHECK_EXECUTE_RESULT(err, str) do { \
if ((err) !=ESP_OK) { \
@ -33,10 +30,50 @@ static char * s_base_path = NULL;
} \
} while(0)
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_sd_ctx_t;
static vfs_fat_sd_ctx_t *s_ctx[FF_VOLUMES] = {};
/**
* This `s_saved_ctx_id` is only used by `esp_vfs_fat_sdmmc_unmount`, which is deprecated.
* This variable together with `esp_vfs_fat_sdmmc_unmount` should be removed in next major version
*/
static uint32_t s_saved_ctx_id = FF_VOLUMES;
static void call_host_deinit(const sdmmc_host_t *host_config);
static esp_err_t partition_card(const esp_vfs_fat_mount_config_t *mount_config,
const char *drv, sdmmc_card_t *card, BYTE pdrv);
static bool s_get_context_id_by_card(const sdmmc_card_t *card, uint32_t *out_id)
{
vfs_fat_sd_ctx_t *p_ctx = NULL;
for (int i = 0; i < FF_VOLUMES; i++) {
p_ctx = s_ctx[i];
if (p_ctx) {
if (p_ctx->card == card) {
*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 mount_prepare_mem(const char *base_path,
BYTE *out_pdrv,
char **out_dup_path,
@ -79,8 +116,38 @@ cleanup:
return err;
}
static esp_err_t s_f_mount(sdmmc_card_t *card, FATFS *fs, const char *drv, uint8_t pdrv, const esp_vfs_fat_mount_config_t *mount_config)
{
esp_err_t err = ESP_OK;
FRESULT res = f_mount(fs, drv, 1);
if (res != FR_OK) {
err = ESP_FAIL;
ESP_LOGW(TAG, "failed to mount card (%d)", res);
bool need_mount_again = (res == FR_NO_FILESYSTEM || res == FR_INT_ERR) && mount_config->format_if_mount_failed;
if (!need_mount_again) {
return ESP_FAIL;
}
err = partition_card(mount_config, drv, card, pdrv);
if (err != ESP_OK) {
return err;
}
ESP_LOGW(TAG, "mounting again");
res = f_mount(fs, drv, 0);
if (res != FR_OK) {
err = ESP_FAIL;
ESP_LOGD(TAG, "f_mount failed after formatting (%d)", res);
return err;
}
}
return ESP_OK;
}
static esp_err_t mount_to_vfs_fat(const esp_vfs_fat_mount_config_t *mount_config, sdmmc_card_t *card, uint8_t pdrv,
const char *base_path)
const char *base_path, FATFS **out_fs)
{
FATFS *fs = NULL;
esp_err_t err;
@ -91,6 +158,7 @@ static esp_err_t mount_to_vfs_fat(const esp_vfs_fat_mount_config_t *mount_config
// connect FATFS to VFS
err = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
*out_fs = fs;
if (err == ESP_ERR_INVALID_STATE) {
// it's okay, already registered with VFS
} else if (err != ESP_OK) {
@ -99,28 +167,10 @@ static esp_err_t mount_to_vfs_fat(const esp_vfs_fat_mount_config_t *mount_config
}
// Try to mount partition
FRESULT res = f_mount(fs, drv, 1);
if (res != FR_OK) {
err = ESP_FAIL;
ESP_LOGW(TAG, "failed to mount card (%d)", res);
if (!((res == FR_NO_FILESYSTEM || res == FR_INT_ERR)
&& mount_config->format_if_mount_failed)) {
goto fail;
}
err = partition_card(mount_config, drv, card, pdrv);
err = s_f_mount(card, fs, drv, pdrv, mount_config);
if (err != ESP_OK) {
goto fail;
}
ESP_LOGW(TAG, "mounting again");
res = f_mount(fs, drv, 0);
if (res != FR_OK) {
err = ESP_FAIL;
ESP_LOGD(TAG, "f_mount failed after formatting (%d)", res);
goto fail;
}
}
return ESP_OK;
fail:
@ -187,6 +237,9 @@ esp_err_t esp_vfs_fat_sdmmc_mount(const char* base_path,
sdmmc_card_t** out_card)
{
esp_err_t err;
vfs_fat_sd_ctx_t *ctx = NULL;
uint32_t ctx_id = FF_VOLUMES;
FATFS *fs = NULL;
int card_handle = -1; //uninitialized
sdmmc_card_t* card = NULL;
BYTE pdrv = FF_DRV_NOT_USED;
@ -212,20 +265,30 @@ esp_err_t esp_vfs_fat_sdmmc_mount(const char* base_path,
err = sdmmc_card_init(host_config, card);
CHECK_EXECUTE_RESULT(err, "sdmmc_card_init failed");
err = mount_to_vfs_fat(mount_config, card, pdrv, dup_path);
err = mount_to_vfs_fat(mount_config, card, pdrv, dup_path, &fs);
CHECK_EXECUTE_RESULT(err, "mount_to_vfs failed");
if (out_card != NULL) {
*out_card = card;
}
if (s_card == NULL) {
//store the ctx locally to be back-compatible
s_card = card;
s_pdrv = pdrv;
s_base_path = dup_path;
} else {
free(dup_path);
//For deprecation backward compatibility
if (s_saved_ctx_id == FF_VOLUMES) {
s_saved_ctx_id = 0;
}
ctx = calloc(sizeof(vfs_fat_sd_ctx_t), 1);
if (!ctx) {
CHECK_EXECUTE_RESULT(ESP_ERR_NO_MEM, "no mem");
}
ctx->pdrv = pdrv;
memcpy(&ctx->mount_config, mount_config, sizeof(esp_vfs_fat_mount_config_t));
ctx->card = card;
ctx->base_path = dup_path;
ctx->fs = fs;
ctx_id = s_get_unused_context_id();
assert(ctx_id != FF_VOLUMES);
s_ctx[ctx_id] = ctx;
return ESP_OK;
cleanup:
if (host_inited) {
@ -233,6 +296,10 @@ cleanup:
}
free(card);
free(dup_path);
if (ctx) {
free(ctx);
s_ctx[ctx_id] = NULL;
}
return err;
}
#endif
@ -257,6 +324,9 @@ esp_err_t esp_vfs_fat_sdspi_mount(const char* base_path,
{
const sdmmc_host_t* host_config = host_config_input;
esp_err_t err;
vfs_fat_sd_ctx_t *ctx = NULL;
uint32_t ctx_id = FF_VOLUMES;
FATFS *fs = NULL;
int card_handle = -1; //uninitialized
bool host_inited = false;
BYTE pdrv = FF_DRV_NOT_USED;
@ -294,20 +364,30 @@ esp_err_t esp_vfs_fat_sdspi_mount(const char* base_path,
err = sdmmc_card_init(host_config, card);
CHECK_EXECUTE_RESULT(err, "sdmmc_card_init failed");
err = mount_to_vfs_fat(mount_config, card, pdrv, dup_path);
err = mount_to_vfs_fat(mount_config, card, pdrv, dup_path, &fs);
CHECK_EXECUTE_RESULT(err, "mount_to_vfs failed");
if (out_card != NULL) {
*out_card = card;
}
if (s_card == NULL) {
//store the ctx locally to be back-compatible
s_card = card;
s_pdrv = pdrv;
s_base_path = dup_path;
} else {
free(dup_path);
//For deprecation backward compatibility
if (s_saved_ctx_id == FF_VOLUMES) {
s_saved_ctx_id = 0;
}
ctx = calloc(sizeof(vfs_fat_sd_ctx_t), 1);
if (!ctx) {
CHECK_EXECUTE_RESULT(ESP_ERR_NO_MEM, "no mem");
}
ctx->pdrv = pdrv;
memcpy(&ctx->mount_config, mount_config, sizeof(esp_vfs_fat_mount_config_t));
ctx->card = card;
ctx->base_path = dup_path;
ctx->fs = fs;
ctx_id = s_get_unused_context_id();
assert(ctx_id != FF_VOLUMES);
s_ctx[ctx_id] = ctx;
return ESP_OK;
cleanup:
@ -316,18 +396,14 @@ cleanup:
}
free(card);
free(dup_path);
if (ctx) {
free(ctx);
s_ctx[ctx_id] = NULL;
}
return err;
}
static void local_card_remove(void)
{
s_card = NULL;
free(s_base_path);
s_base_path = NULL;
s_pdrv = FF_DRV_NOT_USED;
}
static void call_host_deinit(const sdmmc_host_t *host_config)
{
if (host_config->flags & SDMMC_HOST_FLAG_DEINIT_ARG) {
@ -359,17 +435,74 @@ static esp_err_t unmount_card_core(const char *base_path, sdmmc_card_t *card)
esp_err_t esp_vfs_fat_sdmmc_unmount(void)
{
sdmmc_card_t* card = s_card;
esp_err_t err = unmount_card_core(s_base_path, card);
local_card_remove();
esp_err_t err = unmount_card_core(s_ctx[s_saved_ctx_id]->base_path, s_ctx[s_saved_ctx_id]->card);
free(s_ctx[s_saved_ctx_id]);
s_ctx[s_saved_ctx_id] = NULL;
s_saved_ctx_id = FF_VOLUMES;
return err;
}
esp_err_t esp_vfs_fat_sdcard_unmount(const char *base_path, sdmmc_card_t *card)
{
esp_err_t err = unmount_card_core(base_path, card);
if (s_card == card) {
local_card_remove();
uint32_t id = FF_VOLUMES;
bool found = s_get_context_id_by_card(card, &id);
if (!found) {
return ESP_ERR_INVALID_ARG;
}
free(s_ctx[id]);
s_ctx[id] = NULL;
esp_err_t err = unmount_card_core(base_path, card);
return err;
}
esp_err_t esp_vfs_fat_sdcard_format(const char *base_path, sdmmc_card_t *card)
{
esp_err_t ret = ESP_OK;
if (!card) {
ESP_LOGE(TAG, "card not initialized");
return ESP_ERR_INVALID_STATE;
}
BYTE pdrv = ff_diskio_get_pdrv_card(card);
if (pdrv == 0xff) {
ESP_LOGE(TAG, "card driver not registered");
return ESP_ERR_INVALID_STATE;
}
const size_t workbuf_size = 4096;
void *workbuf = ff_memalloc(workbuf_size);
if (workbuf == NULL) {
return ESP_ERR_NO_MEM;
}
//unmount
char drv[3] = {(char)('0' + pdrv), ':', 0};
f_mount(0, drv, 0);
//format
uint32_t id = FF_VOLUMES;
bool found = s_get_context_id_by_card(card, &id);
assert(found);
size_t alloc_unit_size = esp_vfs_fat_get_allocation_unit_size(
card->csd.sector_size,
s_ctx[id]->mount_config.allocation_unit_size);
ESP_LOGI(TAG, "Formatting card, allocation unit size=%d", alloc_unit_size);
const MKFS_PARM opt = {(BYTE)FM_ANY, 0, 0, 0, alloc_unit_size};
FRESULT res = f_mkfs(drv, &opt, workbuf, workbuf_size);
free(workbuf);
if (res != FR_OK) {
ret = ESP_FAIL;
ESP_LOGD(TAG, "f_mkfs failed (%d)", res);
}
//mount back
esp_err_t err = s_f_mount(card, s_ctx[id]->fs, drv, pdrv, &s_ctx[id]->mount_config);
if (err != ESP_OK) {
unmount_card_core(base_path, card);
ESP_LOGE(TAG, "failed to format, resources recycled, please mount again");
}
return ret;
}

295
components/fatfs/vfs/vfs_fat_spiflash.c
View File

@ -6,42 +6,122 @@
#include <stdlib.h>
#include <string.h>
#include "esp_check.h"
#include "esp_log.h"
#include "esp_vfs.h"
#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 result = ESP_OK;
const size_t workbuf_size = 4096;
void *workbuf = NULL;
esp_err_t ret = ESP_OK;
vfs_fat_spiflash_ctx_t *ctx = NULL;
uint32_t ctx_id = FF_VOLUMES;
esp_partition_subtype_t subtype = partition_label ?
ESP_PARTITION_SUBTYPE_ANY : ESP_PARTITION_SUBTYPE_DATA_FAT;
const esp_partition_t *data_partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA,
subtype, partition_label);
if (data_partition == NULL) {
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;
}
ESP_RETURN_ON_FALSE(data_partition, ESP_ERR_NOT_FOUND, TAG, "Failed to find FATFS partition (type='data', subtype='fat', partition_label='%s'). Check the partition table.", partition_label);
ESP_RETURN_ON_ERROR(wl_mount(data_partition, wl_handle), TAG, "failed to mount wear levelling layer. ret = %i", ret);
result = wl_mount(data_partition, wl_handle);
if (result != ESP_OK) {
ESP_LOGE(TAG, "failed to mount wear levelling layer. result = %i", result);
return result;
}
// connect driver to FATFS
BYTE pdrv = 0xFF;
if (ff_diskio_get_drive(&pdrv) != ESP_OK) {
@ -50,96 +130,145 @@ esp_err_t esp_vfs_fat_spiflash_mount_rw_wl(const char* base_path,
}
ESP_LOGD(TAG, "using pdrv=%i", pdrv);
char drv[3] = {(char)('0' + pdrv), ':', 0};
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);
result = ff_diskio_register_wl_partition(pdrv, *wl_handle);
if (result != ESP_OK) {
ESP_LOGE(TAG, "ff_diskio_register_wl_partition failed pdrv=%i, error - 0x(%x)", pdrv, result);
goto fail;
}
FATFS *fs;
result = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
if (result == ESP_ERR_INVALID_STATE) {
ret = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
if (ret == ESP_ERR_INVALID_STATE) {
// it's okay, already registered with VFS
} else if (result != ESP_OK) {
ESP_LOGD(TAG, "esp_vfs_fat_register failed 0x(%x)", result);
} else if (ret != ESP_OK) {
ESP_LOGD(TAG, "esp_vfs_fat_register failed 0x(%x)", ret);
goto fail;
}
// Try to mount partition
FRESULT fresult = f_mount(fs, drv, 1);
if (fresult != FR_OK) {
ESP_LOGW(TAG, "f_mount failed (%d)", fresult);
if (!((fresult == FR_NO_FILESYSTEM || fresult == FR_INT_ERR)
&& mount_config->format_if_mount_failed)) {
result = ESP_FAIL;
ret = s_f_mount_rw(fs, drv, mount_config);
if (ret != ESP_OK) {
goto fail;
}
workbuf = ff_memalloc(workbuf_size);
if (workbuf == NULL) {
result = 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);
if (fresult != FR_OK) {
result = ESP_FAIL;
ESP_LOGE(TAG, "f_mkfs failed (%d)", fresult);
goto fail;
}
free(workbuf);
workbuf = NULL;
ESP_LOGI(TAG, "Mounting again");
fresult = f_mount(fs, drv, 0);
if (fresult != FR_OK) {
result = ESP_FAIL;
ESP_LOGE(TAG, "f_mount failed after formatting (%d)", fresult);
goto fail;
}
}
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);
return result;
if (ctx_id != FF_VOLUMES) {
s_ctx[ctx_id] = NULL;
}
free(ctx);
return ret;
}
esp_err_t esp_vfs_fat_spiflash_unmount_rw_wl(const char* base_path, wl_handle_t wl_handle)
{
BYTE pdrv = ff_diskio_get_pdrv_wl(wl_handle);
if (pdrv == 0xff) {
return ESP_ERR_INVALID_STATE;
}
char drv[3] = {(char)('0' + pdrv), ':', 0};
ESP_RETURN_ON_FALSE(pdrv != 0xff, ESP_ERR_INVALID_STATE, TAG, "partition isn't registered, call esp_vfs_fat_spiflash_mount_rw_wl first");
char drv[3] = {(char)('0' + pdrv), ':', 0};
f_mount(0, drv, 0);
ff_diskio_unregister(pdrv);
ff_diskio_clear_pdrv_wl(wl_handle);
// 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)
{
esp_err_t ret = ESP_OK;
bool partition_was_mounted = false;
wl_handle_t temp_handle = WL_INVALID_HANDLE;
uint32_t id = FF_VOLUMES;
char drv[3] = {0, ':', 0};
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,
const char* partition_label,
const esp_vfs_fat_mount_config_t* mount_config)
{
esp_err_t result = ESP_OK;
esp_err_t ret = ESP_OK;
const esp_partition_t *data_partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA,
ESP_PARTITION_SUBTYPE_DATA_FAT, partition_label);
if (data_partition == NULL) {
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;
}
ESP_RETURN_ON_FALSE(data_partition, ESP_ERR_NOT_FOUND, TAG, "Failed to find FATFS partition (type='data', subtype='fat', partition_label='%s'). Check the partition table.", partition_label);
// connect driver to FATFS
BYTE pdrv = 0xFF;
@ -149,19 +278,14 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
}
ESP_LOGD(TAG, "using pdrv=%i", pdrv);
char drv[3] = {(char)('0' + pdrv), ':', 0};
result = ff_diskio_register_raw_partition(pdrv, data_partition);
if (result != ESP_OK) {
ESP_LOGE(TAG, "ff_diskio_register_raw_partition failed pdrv=%i, error - 0x(%x)", pdrv, result);
goto fail;
}
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;
result = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
if (result == ESP_ERR_INVALID_STATE) {
ret = esp_vfs_fat_register(base_path, drv, mount_config->max_files, &fs);
if (ret == ESP_ERR_INVALID_STATE) {
// it's okay, already registered with VFS
} else if (result != ESP_OK) {
ESP_LOGD(TAG, "esp_vfs_fat_register failed 0x(%x)", result);
} else if (ret != ESP_OK) {
ESP_LOGD(TAG, "esp_vfs_fat_register failed 0x(%x)", ret);
goto fail;
}
@ -169,7 +293,7 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
FRESULT fresult = f_mount(fs, drv, 1);
if (fresult != FR_OK) {
ESP_LOGW(TAG, "f_mount failed (%d)", fresult);
result = ESP_FAIL;
ret = ESP_FAIL;
goto fail;
}
return ESP_OK;
@ -177,32 +301,25 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
fail:
esp_vfs_fat_unregister_path(base_path);
ff_diskio_unregister(pdrv);
return result;
return ret;
}
esp_err_t esp_vfs_fat_spiflash_unmount_ro(const char* base_path, const char* partition_label)
{
const esp_partition_t *data_partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA,
ESP_PARTITION_SUBTYPE_DATA_FAT, partition_label);
if (data_partition == NULL) {
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;
}
ESP_RETURN_ON_FALSE(data_partition, ESP_ERR_NOT_FOUND, TAG, "Failed to find FATFS partition (type='data', subtype='fat', partition_label='%s'). Check the partition table.", partition_label);
BYTE pdrv = ff_diskio_get_pdrv_raw(data_partition);
if (pdrv == 0xff) {
return ESP_ERR_INVALID_STATE;
}
char drv[3] = {(char)('0' + pdrv), ':', 0};
ESP_RETURN_ON_FALSE(pdrv != 0xff, ESP_ERR_INVALID_STATE, TAG, "partition isn't registered, call esp_vfs_fat_spiflash_mount_ro first");
char drv[3] = {(char)('0' + pdrv), ':', 0};
f_mount(0, drv, 0);
ff_diskio_unregister(pdrv);
esp_err_t err = esp_vfs_fat_unregister_path(base_path);
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,

1
docs/en/migration-guides/release-5.x/5.1/index.rst
View File

@ -7,4 +7,5 @@ Migration from 5.0 to 5.1
:maxdepth: 1
peripherals
storage
networking

9
docs/en/migration-guides/release-5.x/5.1/storage.rst Normal file
View File

@ -0,0 +1,9 @@
Storage
=======
:link_to_translation:`zh_CN:[中文]`
FatFs
-----
``esp_vfs_fat_sdmmc_unmount()`` is now deprecated, you can use :cpp:func:`esp_vfs_fat_sdcard_unmount()` instead. This API is deprecated in previous IDF versions, but without deprecation warning and migration guide. Since IDF v5.1, calling this ``esp_vfs_fat_sdmmc_unmount()`` API will generate deprecation warning.

1
docs/zh_CN/migration-guides/release-5.x/5.1/index.rst
View File

@ -7,4 +7,5 @@
:maxdepth: 1
peripherals
storage
networking

9
docs/zh_CN/migration-guides/release-5.x/5.1/storage.rst Normal file
View File

@ -0,0 +1,9 @@
存储
=======
:link_to_translation:`en:[English]`
FatFs
-----
``esp_vfs_fat_sdmmc_unmount()`` 已被弃用。 您可以使用 :cpp:func:`esp_vfs_fat_sdcard_unmount()` 代替。 此接口在更早的 IDF 版本中已被弃用， 但是尚未添加弃用警告。 自 IDF v5.1 起， 调用这个 ``esp_vfs_fat_sdmmc_unmount()`` 接口将会产生 deprecation 警告。

95
examples/storage/sd_card/sdmmc/main/sd_card_example_main.c
View File

@ -15,11 +15,50 @@
#include "sdmmc_cmd.h"
#include "driver/sdmmc_host.h"
#define EXAMPLE_MAX_CHAR_SIZE 64
static const char *TAG = "example";
#define MOUNT_POINT "/sdcard"
static esp_err_t s_example_write_file(const char *path, char *data)
{
ESP_LOGI(TAG, "Opening file %s", path);
FILE *f = fopen(path, "w");
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(const char *path)
{
ESP_LOGI(TAG, "Reading file %s", path);
FILE *f = fopen(path, "r");
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_err_t ret;
@ -103,19 +142,14 @@ void app_main(void)
// First create a file.
const char *file_hello = MOUNT_POINT"/hello.txt";
ESP_LOGI(TAG, "Opening file %s", file_hello);
FILE *f = fopen(file_hello, "w");
if (f == NULL) {
ESP_LOGE(TAG, "Failed to open file for writing");
char data[EXAMPLE_MAX_CHAR_SIZE];
snprintf(data, EXAMPLE_MAX_CHAR_SIZE, "%s %s!\n", "Hello", card->cid.name);
ret = s_example_write_file(file_hello, data);
if (ret != ESP_OK) {
return;
}
fprintf(f, "Hello %s!\n", card->cid.name);
fclose(f);
ESP_LOGI(TAG, "File written");
const char *file_foo = MOUNT_POINT"/foo.txt";
// Check if destination file exists before renaming
struct stat st;
if (stat(file_foo, &st) == 0) {
@ -130,25 +164,38 @@ void app_main(void)
return;
}
// Open renamed file for reading
ESP_LOGI(TAG, "Reading file %s", file_foo);
f = fopen(file_foo, "r");
if (f == NULL) {
ESP_LOGE(TAG, "Failed to open file for reading");
ret = s_example_read_file(file_foo);
if (ret != ESP_OK) {
return;
}
// Read a line from file
char line[64];
fgets(line, sizeof(line), f);
fclose(f);
// Strip newline
char *pos = strchr(line, '\n');
if (pos) {
*pos = '\0';
// Format FATFS
ret = esp_vfs_fat_sdcard_format(mount_point, card);
if (ret != ESP_OK) {
ESP_LOGE(TAG, "Failed to format FATFS (%s)", esp_err_to_name(ret));
return;
}
if (stat(file_foo, &st) == 0) {
ESP_LOGI(TAG, "file still exists");
return;
} else {
ESP_LOGI(TAG, "file doesnt exist, format done");
}
const char *file_nihao = MOUNT_POINT"/nihao.txt";
memset(data, 0, EXAMPLE_MAX_CHAR_SIZE);
snprintf(data, EXAMPLE_MAX_CHAR_SIZE, "%s %s!\n", "Nihao", card->cid.name);
ret = s_example_write_file(file_nihao, data);
if (ret != ESP_OK) {
return;
}
//Open file for reading
ret = s_example_read_file(file_nihao);
if (ret != ESP_OK) {
return;
}
ESP_LOGI(TAG, "Read from file: '%s'", line);
// All done, unmount partition and disable SDMMC peripheral
esp_vfs_fat_sdcard_unmount(mount_point, card);

10
examples/storage/sd_card/sdmmc/pytest_sdmmc_card_example.py
View File

@ -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
@ -31,7 +31,13 @@ def test_examples_sd_card_sdmmc(dut: Dut) -> None:
'Renaming file /sdcard/hello.txt to /sdcard/foo.txt',
'Reading file /sdcard/foo.txt',
"Read from file: 'Hello {}!'".format(name),
re.compile(str.encode('Formatting card, allocation unit size=\\S+')),
'file doesnt exist, format done',
'Opening file /sdcard/nihao.txt',
'File written',
'Reading file /sdcard/nihao.txt',
"Read from file: 'Nihao {}!'".format(name),
'Card unmounted')
for msg in message_list:
dut.expect(msg, timeout=10)
dut.expect(msg, timeout=20)

93
examples/storage/sd_card/sdspi/main/sd_card_example_main.c
View File

@ -14,6 +14,8 @@
#include "esp_vfs_fat.h"
#include "sdmmc_cmd.h"
#define EXAMPLE_MAX_CHAR_SIZE 64
static const char *TAG = "example";
#define MOUNT_POINT "/sdcard"
@ -25,6 +27,42 @@ static const char *TAG = "example";
#define PIN_NUM_CLK CONFIG_EXAMPLE_PIN_CLK
#define PIN_NUM_CS CONFIG_EXAMPLE_PIN_CS
static esp_err_t s_example_write_file(const char *path, char *data)
{
ESP_LOGI(TAG, "Opening file %s", path);
FILE *f = fopen(path, "w");
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(const char *path)
{
ESP_LOGI(TAG, "Reading file %s", path);
FILE *f = fopen(path, "r");
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)
{
@ -99,16 +137,12 @@ void app_main(void)
// First create a file.
const char *file_hello = MOUNT_POINT"/hello.txt";
ESP_LOGI(TAG, "Opening file %s", file_hello);
FILE *f = fopen(file_hello, "w");
if (f == NULL) {
ESP_LOGE(TAG, "Failed to open file for writing");
char data[EXAMPLE_MAX_CHAR_SIZE];
snprintf(data, EXAMPLE_MAX_CHAR_SIZE, "%s %s!\n", "Hello", card->cid.name);
ret = s_example_write_file(file_hello, data);
if (ret != ESP_OK) {
return;
}
fprintf(f, "Hello %s!\n", card->cid.name);
fclose(f);
ESP_LOGI(TAG, "File written");
const char *file_foo = MOUNT_POINT"/foo.txt";
@ -126,25 +160,38 @@ void app_main(void)
return;
}
// Open renamed file for reading
ESP_LOGI(TAG, "Reading file %s", file_foo);
f = fopen(file_foo, "r");
if (f == NULL) {
ESP_LOGE(TAG, "Failed to open file for reading");
ret = s_example_read_file(file_foo);
if (ret != ESP_OK) {
return;
}
// Read a line from file
char line[64];
fgets(line, sizeof(line), f);
fclose(f);
// Strip newline
char *pos = strchr(line, '\n');
if (pos) {
*pos = '\0';
// Format FATFS
ret = esp_vfs_fat_sdcard_format(mount_point, card);
if (ret != ESP_OK) {
ESP_LOGE(TAG, "Failed to format FATFS (%s)", esp_err_to_name(ret));
return;
}
if (stat(file_foo, &st) == 0) {
ESP_LOGI(TAG, "file still exists");
return;
} else {
ESP_LOGI(TAG, "file doesnt exist, format done");
}
const char *file_nihao = MOUNT_POINT"/nihao.txt";
memset(data, 0, EXAMPLE_MAX_CHAR_SIZE);
snprintf(data, EXAMPLE_MAX_CHAR_SIZE, "%s %s!\n", "Nihao", card->cid.name);
ret = s_example_write_file(file_nihao, data);
if (ret != ESP_OK) {
return;
}
//Open file for reading
ret = s_example_read_file(file_nihao);
if (ret != ESP_OK) {
return;
}
ESP_LOGI(TAG, "Read from file: '%s'", line);
// All done, unmount partition and disable SPI peripheral
esp_vfs_fat_sdcard_unmount(mount_point, card);

8
examples/storage/sd_card/sdspi/pytest_sdspi_card_example.py
View File

@ -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
@ -33,6 +33,12 @@ def test_examples_sd_card_sdspi(dut: Dut) -> None:
'Renaming file /sdcard/hello.txt to /sdcard/foo.txt',
'Reading file /sdcard/foo.txt',
"Read from file: 'Hello {}!'".format(name),
re.compile(str.encode('Formatting card, allocation unit size=\\S+')),
'file doesnt exist, format done',
'Opening file /sdcard/nihao.txt',
'File written',
'Reading file /sdcard/nihao.txt',
"Read from file: 'Nihao {}!'".format(name),
'Card unmounted')
for msg in message_list:

93
examples/storage/wear_levelling/main/wear_levelling_example_main.c
View File

@ -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");
//Create file and write
char data[EXAMPLE_MAX_CHAR_SIZE];
snprintf(data, EXAMPLE_MAX_CHAR_SIZE, "%s %s\n", "hello world, from ESP-IDF", esp_get_idf_version());
err = s_example_write_file("/spiflash/hello.txt", data);
if (err != ESP_OK) {
return;
}
fprintf(f, "written using ESP-IDF %s\n", esp_get_idf_version());
fclose(f);
ESP_LOGI(TAG, "File written");
//Open file for reading
ESP_LOGI(TAG, "Reading file");
f = fopen("/spiflash/hello.txt", "rb");
if (f == NULL) {
ESP_LOGE(TAG, "Failed to open file for reading");
err = s_example_read_file("/spiflash/hello.txt");
if (err != ESP_OK) {
return;
}
char line[128];
fgets(line, sizeof(line), f);
fclose(f);
// strip newline
char *pos = strchr(line, '\n');
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");

10
examples/storage/wear_levelling/pytest_wear_levelling_example.py
View File

@ -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')

4
tools/idf_py_actions/hints.yml
View File

@ -279,6 +279,10 @@
hint: "All the Partition APIs have been moved to the new component 'esp_partition' - please, update your project dependencies. See Storage migration guide 5.x for more details."
match_to_output: True
-
re: "warning: 'esp_vfs_fat_sdmmc_unmount' is deprecated: Please use esp_vfs_fat_sdcard_unmount instead [-Wdeprecated-declarations]"
hint: "``esp_vfs_fat_sdmmc_unmount()`` is now deprecated, you can use :cpp:func:`esp_vfs_fat_sdcard_unmount()` instead. See Storage migration guide 5.1 for more details"
-
re: "esp_usb_jtag: could not find or open device!"
hint: "Please check the wire connection to debugging device or access rights to a serial port."