By default, this example uses 4 line SD mode, utilizing 6 pins: CLK, CMD, D0 - D3. It is possible to use 1-line mode (CLK, CMD, D0) by changing "SD/MMC bus width" in the example configuration menu (see `CONFIG_EXAMPLE_SDMMC_BUS_WIDTH_1`).
Note that even if card's D3 line is not connected to the ESP chip, it still has to be pulled up, otherwise the card will go into SPI protocol mode.
### Note about GPIO2 (ESP32 only)
GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO0, when entering download mode.
- Some boards have pulldown and/or LED on GPIO2. LED is usually ok, but pulldown will interfere with D0 signals and must be removed. Check the schematic of your development board for anything connected to GPIO2.
### Note about GPIO12 (ESP32 only)
GPIO12 is used as a bootstrapping pin to select output voltage of an internal regulator which powers the flash chip (VDD_SDIO). This pin has an internal pulldown so if left unconnected it will read low at reset (selecting default 3.3V operation). When adding a pullup to this pin for SD card operation, consider the following:
- For boards which don't use the internal regulator (VDD_SDIO) to power the flash, GPIO12 can be pulled high.
- For boards which use 1.8V flash chip, GPIO12 needs to be pulled high at reset. This is fully compatible with SD card operation.
- On boards which use the internal regulator and a 3.3V flash chip, GPIO12 must be low at reset. This is incompatible with SD card operation.
* In most cases, external pullup can be omitted and an internal pullup can be enabled using a `gpio_pullup_en(GPIO_NUM_12);` call. Most SD cards work fine when an internal pullup on GPIO12 line is enabled. Note that if ESP32 experiences a power-on reset while the SD card is sending data, high level on GPIO12 can be latched into the bootstrapping register, and ESP32 will enter a boot loop until external reset with correct GPIO12 level is applied.
* Another option is to burn the flash voltage selection efuses. This will permanently select 3.3V output voltage for the internal regulator, and GPIO12 will not be used as a bootstrapping pin. Then it is safe to connect a pullup resistor to GPIO12. This option is suggested for production use.
The following command can be used to program flash voltage selection efuses **to 3.3V**:
This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG` efuses. With all three burned to value 1, the internal VDD_SDIO flash voltage regulator is permanently enabled at 3.3V. See the technical reference manual for more details.
`espefuse.py` has a `--do-not-confirm` option if running from an automated flashing script.
See [the document about pullup requirements](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sd_pullup_requirements.html) for more details about pullup support and compatibility of modules and development boards.
## How to use example
### Configure
1. Set the target chip: `idf.py set-target TARGET` (replace TARGET with ESP32 chip series name)
1. Configure the example (`idf.py menuconfig` -> "Performance Benchmark Example Configuration") wheter you want to:
- Test internal SPI flash
- Raw access
- FATFS
- SPIFFS
- Test SD card
- Select SD card interface
- SDSPI
- SDMMC
- SD card test configuration
- Raw access
- FATFS
- Set SD card frequency
- Set GPIO pins
Some configuration options may be available for ESP32 and ESP32-S3 only.
### Build and flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
idf.py -p PORT build flash monitor
```
(Replace PORT with serial port name.)
(To exit the serial monitor, type ``Ctrl-]``.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
## Example output
```
I (345) example: Start of the example
I (355) example: Internal flash test
I (355) example: Mountig WL layer...
I (415) example: WL layer mounted
I (505) example: Test with 128kiB file
Wrote 131072 bytes in 320.295ms (0.390MiB/s) to address 0
I (895) example: WL layer unmounted
I (895) example: Mounting FATFS partition...
W (895) vfs_fat_spiflash: f_mount failed (13)
I (895) vfs_fat_spiflash: Formatting FATFS partition, allocation unit size=16384
I (1105) vfs_fat_spiflash: Mounting again
I (1105) example: FATFS mounted to /spiflash
I (1205) example: Test with 128kiB file
Wrote 131072 bytes (buffer size 4096B) in 1295.988ms (0.096MiB/s)
Wrote 131072 bytes (buffer size 8192B) in 1277.569ms (0.098MiB/s)
Wrote 131072 bytes (buffer size 16384B) in 1439.405ms (0.087MiB/s)
Read 131072 bytes (buffer size 4096B) in 17.721ms (7.054MiB/s)
Read 131072 bytes (buffer size 8192B) in 16.945ms (7.377MiB/s)
Read 131072 bytes (buffer size 16384B) in 16.596ms (7.532MiB/s)
I (5705) example: Test with 256kiB file
Wrote 262144 bytes (buffer size 4096B) in 2529.380ms (0.099MiB/s)
Wrote 262144 bytes (buffer size 8192B) in 2867.352ms (0.087MiB/s)
Wrote 262144 bytes (buffer size 16384B) in 2879.113ms (0.087MiB/s)
Read 262144 bytes (buffer size 4096B) in 34.809ms (7.182MiB/s)
Read 262144 bytes (buffer size 8192B) in 33.315ms (7.504MiB/s)
Read 262144 bytes (buffer size 16384B) in 32.601ms (7.668MiB/s)
I (14535) example: Test with 512kiB file
Wrote 524288 bytes (buffer size 4096B) in 5119.009ms (0.098MiB/s)
Wrote 524288 bytes (buffer size 8192B) in 5897.010ms (0.085MiB/s)
Wrote 524288 bytes (buffer size 16384B) in 5888.743ms (0.085MiB/s)
Read 524288 bytes (buffer size 4096B) in 68.975ms (7.249MiB/s)
Read 524288 bytes (buffer size 8192B) in 66.063ms (7.569MiB/s)
Read 524288 bytes (buffer size 16384B) in 64.624ms (7.737MiB/s)
I (32295) example: FATFS partition unmounted
I (32295) example: Mounting SPIFFS partition...
W (32295) SPIFFS: mount failed, -10025. formatting...
I (38195) example: SPIFFS mounted to /spiflash
I (41555) example: Partition size: total: 896321, used: 0
I (41645) example: Test with 128kiB file
Wrote 131072 bytes (buffer size 4096B) in 819.950ms (0.152MiB/s)
Wrote 131072 bytes (buffer size 8192B) in 777.949ms (0.161MiB/s)
Wrote 131072 bytes (buffer size 16384B) in 751.682ms (0.166MiB/s)
Read 131072 bytes (buffer size 4096B) in 101.810ms (1.228MiB/s)
Read 131072 bytes (buffer size 8192B) in 99.518ms (1.256MiB/s)
Read 131072 bytes (buffer size 16384B) in 98.472ms (1.269MiB/s)
I (45335) example: Test with 256kiB file
Wrote 262144 bytes (buffer size 4096B) in 1650.525ms (0.151MiB/s)
Wrote 262144 bytes (buffer size 8192B) in 3220.004ms (0.078MiB/s)
Wrote 262144 bytes (buffer size 16384B) in 7139.803ms (0.035MiB/s)
Read 262144 bytes (buffer size 4096B) in 204.933ms (1.220MiB/s)
Read 262144 bytes (buffer size 8192B) in 200.330ms (1.248MiB/s)
Read 262144 bytes (buffer size 16384B) in 198.129ms (1.262MiB/s)
I (60365) example: Test with 512kiB file
Wrote 524288 bytes (buffer size 4096B) in 13917.135ms (0.036MiB/s)
Wrote 524288 bytes (buffer size 8192B) in 14302.046ms (0.035MiB/s)
Wrote 524288 bytes (buffer size 16384B) in 14411.794ms (0.035MiB/s)
Read 524288 bytes (buffer size 4096B) in 317.944ms (1.573MiB/s)
Read 524288 bytes (buffer size 8192B) in 308.865ms (1.619MiB/s)
Read 524288 bytes (buffer size 16384B) in 304.305ms (1.643MiB/s)
A fatal error occurred: Failed to connect to Espressif device: Invalid head of packet (0x34)
```
Disconnect the SD card D0/MISO line from GPIO2 and try uploading again. Read "Note about GPIO2" above.
### Card fails to initialize with `sdmmc_init_sd_scr: send_scr (1) returned 0x107` error
Check connections between the card and the ESP32. For example, if you have disconnected GPIO2 to work around the flashing issue, connect it back and reset the ESP32 (using a button on the development board, or by pressing Ctrl-T Ctrl-R in IDF Monitor).
### Card fails to initialize with `sdmmc_check_scr: send_scr returned 0xffffffff` error
Connections between the card and the ESP32 are too long for the frequency used. Try using shorter connections, or try reducing the clock speed of SD interface.
