esp-idf/examples/storage/perf_benchmark/README.md

Supported Targets	ESP32	ESP32-C2	ESP32-C3	ESP32-C6	ESP32-H2	ESP32-P4	ESP32-S2	ESP32-S3

Storage performance benchmark example

(See the README.md file in the upper level 'examples' directory for more information about examples.)

WARNING: This example will format both your SPI flash "storage" partition and SD card (if used)!

This example demonstrates a benchmark of a storage media such as SPI flash memory and SD card. Only ESP32 and ESP32-S3 targets can use SDMMC mode when connecting to a SD card.

Pin assignments for SD card connection

The GPIO pin numbers used to connect an SD card can be customized using the following:

• Run idf.py menuconfig in the project directory and open "Performance Benchmark Example Configuration" menu.

However, pins cannot be customized when using ESP32 target in SDMMC mode (SDMMC_HOST_SLOT_1).

This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.

The table below shows the default pin assignments.

SD card pin	SPI pin	ESP32 pin	ESP32-S2	ESP32-S3	ESP32-H2	ESP32-C3 and other chips	Notes
D0	MISO	GPIO2	GPIO37	GPIO37	GPIO0	GPIO6	10k pullup
D1	-	GPIO4	-	GPIO38	-	-	not used in 1-line SD mode; 10k pullup in 4-line mode
D2	-	GPIO12 (MTDI)	-	GPIO33	-	-	not used in 1-line SD mode; 10k pullup in 4-line mode
D3	CS	GPIO13 (MTCK)	GPIO34	GPIO34	GPIO1	GPIO1	not used in 1-line SD mode, but card's D3 pin must have a 10k pullup
CLK	SCK	GPIO14 (MTMS)	GPIO36	GPIO36	GPIO4	GPIO5	10k pullup
CMD	MOSI	GPIO15 (MTDO)	GPIO35	GPIO35	GPIO5	GPIO4	10k pullup

4-line and 1-line SD modes

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:

    components/esptool_py/esptool/espefuse.py set_flash_voltage 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 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)

2. 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)
I (108835) example: SPIFFS partition unmounted
I (108835) example: SD card test
I (108845) example: Initializing SD card
I (108845) example: Using SDMMC peripheral
I (108855) example: Mounting SD card - raw access
I (108855) gpio: GPIO[36]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (108865) gpio: GPIO[35]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (108875) gpio: GPIO[37]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (108885) gpio: GPIO[38]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (108895) gpio: GPIO[33]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (108905) gpio: GPIO[34]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
I (108955) gpio: GPIO[34]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (108965) example: SD card mounted - raw access
Name: USD00
Type: SDHC/SDXC
Speed: 40.00 MHz (limit: 40.00 MHz)
Size: 15080MB
CSD: ver=2, sector_size=512, capacity=30883840 read_bl_len=9
SSR: bus_width=4
Wrote 65536 bytes in 25.321ms (2.468MiB/s) to sector 415075
Read 65536 bytes in 3.809ms (16.409MiB/s) from sector 415075
Wrote 131072 bytes in 7.415ms (16.858MiB/s) to sector 823598
Read 131072 bytes in 7.149ms (17.485MiB/s) from sector 823598
Wrote 196608 bytes in 10.829ms (17.315MiB/s) to sector 180761
Read 196608 bytes in 10.539ms (17.791MiB/s) from sector 180761
I (109045) example: SD card unmounted - raw access
I (109045) example: Mounting SD card - FATFS
I (109045) gpio: GPIO[36]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (109055) gpio: GPIO[35]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (109065) gpio: GPIO[37]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (109075) gpio: GPIO[38]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (109085) gpio: GPIO[33]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
I (109095) gpio: GPIO[34]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
I (109145) gpio: GPIO[34]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0
W (109155) vfs_fat_sdmmc: failed to mount card (13)
W (109155) vfs_fat_sdmmc: partitioning card
W (109155) vfs_fat_sdmmc: formatting card, allocation unit size=16384
W (110525) vfs_fat_sdmmc: mounting again
Name: USD00
Type: SDHC/SDXC
Speed: 40.00 MHz (limit: 40.00 MHz)
Size: 15080MB
CSD: ver=2, sector_size=512, capacity=30883840 read_bl_len=9
SSR: bus_width=4
I (110535) example: SD card mounted - FATFS
I (110715) example: Test with 1MiB file
Wrote 1048576 bytes (buffer size 4096B) in 200.241ms (4.994MiB/s)
Wrote 1048576 bytes (buffer size 8192B) in 129.756ms (7.707MiB/s)
Wrote 1048576 bytes (buffer size 16384B) in 91.955ms (10.875MiB/s)
Wrote 1048576 bytes (buffer size 32768B) in 91.424ms (10.938MiB/s)
Read 1048576 bytes (buffer size 4096B) in 121.086ms (8.259MiB/s)
Read 1048576 bytes (buffer size 8192B) in 87.896ms (11.377MiB/s)
Read 1048576 bytes (buffer size 16384B) in 72.525ms (13.788MiB/s)
Read 1048576 bytes (buffer size 32768B) in 74.664ms (13.393MiB/s)
I (111655) example: Test with 4MiB file
Wrote 4194304 bytes (buffer size 4096B) in 797.167ms (5.018MiB/s)
Wrote 4194304 bytes (buffer size 8192B) in 533.538ms (7.497MiB/s)
Wrote 4194304 bytes (buffer size 16384B) in 530.830ms (7.535MiB/s)
Wrote 4194304 bytes (buffer size 32768B) in 497.953ms (8.033MiB/s)
Read 4194304 bytes (buffer size 4096B) in 473.495ms (8.448MiB/s)
Read 4194304 bytes (buffer size 8192B) in 351.240ms (11.388MiB/s)
Read 4194304 bytes (buffer size 16384B) in 289.767ms (13.804MiB/s)
Read 4194304 bytes (buffer size 32768B) in 287.260ms (13.925MiB/s)
I (115495) example: Test with 16MiB file
Wrote 16777216 bytes (buffer size 4096B) in 4754.141ms (3.365MiB/s)
Wrote 16777216 bytes (buffer size 8192B) in 2290.545ms (6.985MiB/s)
Wrote 16777216 bytes (buffer size 16384B) in 2088.811ms (7.660MiB/s)
Wrote 16777216 bytes (buffer size 32768B) in 2148.595ms (7.447MiB/s)
Read 16777216 bytes (buffer size 4096B) in 1899.620ms (8.423MiB/s)
Read 16777216 bytes (buffer size 8192B) in 1419.345ms (11.273MiB/s)
Read 16777216 bytes (buffer size 16384B) in 1158.909ms (13.806MiB/s)
Read 16777216 bytes (buffer size 32768B) in 1148.426ms (13.932MiB/s)
I (132515) example: SD card unmounted - FATFS
I (132515) example: End of the example

Troubleshooting

Failure to download the example

Connecting........_____....._____....._____....._____....._____....._____....._____

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.