Merge branch 'fix/examples_format_sd_card_disable_v5.1' into 'release/v5.1'

fix(examples): Disable formatting SD cards in storage examples by default (v5.1)

See merge request espressif/esp-idf!29004

examples/storage/sd_card/sdmmc/README.md

@@ -5,6 +5,8 @@
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 
+__WARNING:__ This example can potentially delete all data from your SD card (when formatting is enabled). Back up your data first before proceeding.
+
 This example demonstrates how to use an SD card with an ESP device. Example does the following steps:
 
 1. Use an "all-in-one" `esp_vfs_fat_sdmmc_mount` function to:
@@ -12,10 +14,11 @@ This example demonstrates how to use an SD card with an ESP device. Example does
     - probe and initialize an SD card,
     - mount FAT filesystem using FATFS library (and format card, if the filesystem cannot be mounted),
     - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used.
-2. Print information about the card, such as name, type, capacity, and maximum supported frequency.
+1. Print information about the card, such as name, type, capacity, and maximum supported frequency.
-3. Create a file using `fopen` and write to it using `fprintf`.
+1. Create a file using `fopen` and write to it using `fprintf`.
-4. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function.
+1. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function.
-5. Open renamed file for reading, read back the line, and print it to the terminal.
+1. Open renamed file for reading, read back the line, and print it to the terminal.
+1. __OPTIONAL:__ Format the SD card, check if the file doesn't exist anymore.
 
 This example supports SD (SDSC, SDHC, SDXC) cards and eMMC chips.
 

examples/storage/sd_card/sdmmc/main/Kconfig.projbuild

@@ -7,6 +7,12 @@ menu "SD/MMC Example Configuration"
             If this config item is set, format_if_mount_failed will be set to true and the card will be formatted if
             the mount has failed.
 
+    config EXAMPLE_FORMAT_SD_CARD
+        bool "Format the card as a part of the example"
+        default n
+        help
+            If this config item is set, the card will be formatted as a part of the example.
+
     choice EXAMPLE_SDMMC_BUS_WIDTH
         prompt "SD/MMC bus width"
         default EXAMPLE_SDMMC_BUS_WIDTH_4

examples/storage/sd_card/sdmmc/main/sd_card_example_main.c

@@ -170,6 +170,7 @@ void app_main(void)
     }
 
     // Format FATFS
+#ifdef CONFIG_EXAMPLE_FORMAT_SD_CARD
     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));
@@ -182,6 +183,7 @@ void app_main(void)
     } else {
         ESP_LOGI(TAG, "file doesnt exist, format done");
     }
+#endif // CONFIG_EXAMPLE_FORMAT_SD_CARD
 
     const char *file_nihao = MOUNT_POINT"/nihao.txt";
     memset(data, 0, EXAMPLE_MAX_CHAR_SIZE);

examples/storage/sd_card/sdmmc/sdkconfig.ci

@@ -1,3 +1,4 @@
 CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED=y
 CONFIG_FATFS_VFS_FSTAT_BLKSIZE=4096
 CONFIG_ESP_TASK_WDT_EN=n
+CONFIG_EXAMPLE_FORMAT_SD_CARD=y

examples/storage/sd_card/sdspi/README.md

@@ -5,6 +5,8 @@
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 
+__WARNING:__ This example can potentially delete all data from your SD card (when formatting is enabled). Back up your data first before proceeding.
+
 This example demonstrates how to use an SD card with an ESP device over an SPI interface. Example does the following steps:
 
 1. Use an "all-in-one" `esp_vfs_fat_sdspi_mount` function to:
@@ -12,10 +14,11 @@ This example demonstrates how to use an SD card with an ESP device over an SPI i
     - probe and initialize the card connected to SPI bus (DMA channel 1, MOSI, MISO and CLK lines, chip-specific SPI host id),
     - mount FAT filesystem using FATFS library (and format card, if the filesystem cannot be mounted),
     - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used.
-2. Print information about the card, such as name, type, capacity, and maximum supported frequency.
+1. Print information about the card, such as name, type, capacity, and maximum supported frequency.
-3. Create a file using `fopen` and write to it using `fprintf`.
+1. Create a file using `fopen` and write to it using `fprintf`.
-4. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function.
+1. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function.
-5. Open renamed file for reading, read back the line, and print it to the terminal.
+1. Open renamed file for reading, read back the line, and print it to the terminal.
+1. __OPTIONAL:__ Format the SD card, check if the file doesn't exist anymore.
 
 This example support SD (SDSC, SDHC, SDXC) cards.
 

examples/storage/sd_card/sdspi/main/Kconfig.projbuild

@@ -7,6 +7,12 @@ menu "SD SPI Example Configuration"
             If this config item is set, format_if_mount_failed will be set to true and the card will be formatted if
             the mount has failed.
 
+    config EXAMPLE_FORMAT_SD_CARD
+        bool "Format the card as a part of the example"
+        default n
+        help
+            If this config item is set, the card will be formatted as a part of the example.
+
     config EXAMPLE_PIN_MOSI
         int "MOSI GPIO number"
         default 15 if IDF_TARGET_ESP32

examples/storage/sd_card/sdspi/main/sd_card_example_main.c

@@ -166,6 +166,7 @@ void app_main(void)
     }
 
     // Format FATFS
+#ifdef CONFIG_EXAMPLE_FORMAT_SD_CARD
     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));
@@ -178,6 +179,7 @@ void app_main(void)
     } else {
         ESP_LOGI(TAG, "file doesnt exist, format done");
     }
+#endif // CONFIG_EXAMPLE_FORMAT_SD_CARD
 
     const char *file_nihao = MOUNT_POINT"/nihao.txt";
     memset(data, 0, EXAMPLE_MAX_CHAR_SIZE);

examples/storage/sd_card/sdspi/sdkconfig.ci

@@ -1,3 +1,4 @@
 CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED=y
 CONFIG_FATFS_VFS_FSTAT_BLKSIZE=4096
 CONFIG_ESP_TASK_WDT_EN=n
+CONFIG_EXAMPLE_FORMAT_SD_CARD=y

examples/storage/sd_card/sdspi/sdkconfig.defaults

@@ -0,0 +1 @@
+CONFIG_FATFS_VFS_FSTAT_BLKSIZE=4096