Merge branch 'update/sdcard_troubleshooting' into 'master'

fix(sd_card): update sd_card troubleshooting notes in readme.md

See merge request espressif/esp-idf!25879

components/fatfs/vfs/vfs_fat_sdmmc.c

@@ -439,6 +439,8 @@ esp_err_t esp_vfs_fat_sdcard_unmount(const char *base_path, sdmmc_card_t *card)
     if (!found) {
         return ESP_ERR_INVALID_ARG;
     }
+    free(s_ctx[id]->base_path);
+    s_ctx[id]->base_path = NULL;
     free(s_ctx[id]);
     s_ctx[id] = NULL;
 

examples/peripherals/sdio/host/README.md

@@ -1,4 +1,20 @@
 | Supported Targets | ESP32 | ESP32-S3 |
 | ----------------- | ----- | -------- |
 
+
+## Troubleshooting
+
+### Getting the following error
+
+> `E (2562) sdmmc_io: sdmmc_io_read_byte: sdmmc_io_rw_direct (read 0x2) returned 0x107`
+
+Kindly activate the debug log from `idf.py menuconfig -> Component config -> Log output -> Default log verbosity` option and verify the card's IO type status. If the card does not possess IO capabilities, it will encounter issues while attempting to read IO buffers.
+
+To identify the card type, please inspect the following lines in the debug log.
+
+```
+D (659) sdmmc_io: sdmmc_init_io: io_send_op_cond (1) returned 0x106; not IO card
+D (729) sdmmc_init: sdmmc_card_init: card type is SD
+```
+
 See README.md in the parent folder

examples/storage/README.md

@@ -1,5 +1,27 @@
 # Storage Examples
 
 Storage and management of user and system data in module’s flash and on external memory / devices.
+This directory contains a range of examples ESP-IDF projects. These are intended to demonstrate the storage features, and to provide code that you can copy and adapt into your own projects.
+
+# Example Layout
+
+The examples are grouped into sub-directories by category. Each category directory contains one or more example projects:
+
+* `custom_flash_driver` example demonstrates how to implement your own flash chip driver by overriding the default driver.
+* `emmc` example demonstrates how to use an eMMC chip with an ESP device.
+* `ext_flash_fatfs` example demonstrates how to use FATFS partition with external SPI FLASH chip.
+* `fatfsgen` example demonstrates how to use FATFS partition
+* `nvs_rw_blob` example demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP module restarts.
+* `nvs_rw_value` example demonstrates how to read and write a single integer value using NVS.
+* `nvs_rw_value_cxx` example demonstrates how to read and write a single integer value using NVS (it uses the C++ NVS handle API).
+* `partition_api` examples demonstrate how to use different partition APIs.
+* `parttool` example demonstrates common operations the partitions tool allows the user to perform.
+* `sd_card` examples demonstrate how to use an SD card with an ESP device.
+* `semihost_vfs` example demonstrates how to use semihosting VFS driver with ESP device.
+* `spiffs` example demonstrates how to use SPIFFS with ESP device.
+* `spiffsgen` example demonstrates how to use the SPIFFS image generation tool spiffsgen.py to automatically create a SPIFFS.
+* `wear_levelling` example demonstrates how to use wear levelling library and FATFS library to store files in a partition inside SPI flash.
+
+# More
 
 See the [README.md](../README.md) file in the upper level [examples](../) directory for more information about examples.

examples/storage/sd_card/sdspi/README.md

@@ -111,6 +111,19 @@ I (7396) example: Card unmounted
 
 The example will be able to mount only cards formatted using FAT32 filesystem. If the card is formatted as exFAT or some other filesystem, you have an option to format it in the example code. Enable the `CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED` menuconfig option, then build and flash the example.
 
+> Once you've enabled the `CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED` option, if you continue to encounter the following error:
+
+```
+E (600) sdmmc_cmd: sdmmc_read_sectors_dma: sdmmc_send_cmd returned 0x108
+E (600) diskio_sdmmc: sdmmc_read_blocks failed (264)
+W (610) vfs_fat_sdmmc: failed to mount card (1)
+E (610) vfs_fat_sdmmc: mount_to_vfs failed (0xffffffff).
+I (620) gpio: GPIO[13]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
+E (630) example: Failed to mount filesystem. If you want the card to be formatted, set the CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option.
+```
+
+Please ensure that your SD card is operational and not experiencing any malfunctions.
+
 
 ### Unable to flash the example, or serial port not available (ESP32 only)
 
@@ -125,3 +138,20 @@ An attempt to download a new firmware under this conditions may also result in t
 `esptool --port PORT --before no_reset --baud 115200 --chip esp32 erase_flash`
 
 to erase your board's flash, then flash the firmware again.
+
+> If you insert an SD card into the slot and encounter issues when attempting to flash a supported target using the `idf.py flash` command, please consider removing the SD card and attempting to flash the target again. If the flashing process succeeds after removing the SD card, it suggests potential issues with power supply.
+
+Ensure that the board and SD card adapter you are using are powered using the appropriate power source.
+
+
+### Getting the following errors
+
+> `vfs_fat_sdmmc: slot init failed (0x103)`
+
+> `vfs_fat_sdmmc: sdmmc_card_init failed (0x102)`
+
+> `sdmmc_init_ocr: send_op_cond (1) returned 0x107`
+
+Attempt to reboot the board. This error may occur if you reset the ESP board or host controller without power-cycling it. In such cases, the card may remain in its previous state, causing it to potentially not respond to commands sent by the host controller.
+
+Additionally, if the example works with certain SD cards but encounters issues with others, please confirm the read/write speed of the SD card. If the card is not compatible with the host frequency, consider lowering the host frequency and then attempting the operation again.

tools/idf_py_actions/hints.yml

@@ -275,6 +275,35 @@
     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: "vfs_fat_sdmmc: sdmmc_card_init failed"
+    hint: "Please verify if there is an SD card inserted into the SD slot. Then, try rebooting the board."
+
+-
+    re: "sdmmc_common: sdmmc_init_ocr: send_op_cond"
+    hint: "Please reboot the board and then try again"
+
+-
+    re: "sdmmc_io: sdmmc_io_read_byte: sdmmc_io_rw_direct"
+    hint: "Please verify that card supports IO capabilities. Refer 'IDF_PATH/examples/peripherals/sdio/host/README.md' for more details"
+
+-
+    re: "example: Failed to initialize the card \\({}\\). Make sure SD card lines have pull-up resistors in place."
+    hint: "Please refer ./README.md for details"
+    variables:
+        -
+            re_variables: ['ESP_ERR_TIMEOUT']
+            hint_variables: []
+        -
+            re_variables: ['ESP_ERR_INVALID_RESPONSE']
+            hint_variables: []
+        -
+            re_variables: ['ESP_ERR_INVALID_STATE']
+            hint_variables: []
+        -
+            re_variables: ['ESP_ERR_INVALID_ARG']
+            hint_variables: []
+
 -
     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."