SD card & internal flash support on ESP32S3 (QEMU-275)

[ysard]

Checklist

• Checked the issue tracker for similar issues to ensure this is not a duplicate
• Read the documentation to confirm the issue is not addressed there and your configuration is set correctly
• Tested with the latest version to ensure the issue hasn't been fixed

How often does this bug occurs?

always

Expected behavior

Hi, the SD card and internal flash support does not seem to work on ESP32S3.
By the way, the SD card is not mentioned in the documentation.

This seems to be not related to #38 (IDF 5.4.1 has the commit).

Actual behavior (suspected bug)

SDMMC:
The mount fails as if the slot cannot be initialized.

SPI flash:
The mount fails even after formatting (which appears to work).

With the command -drive file=sd_image.bin,if=sd,format=raw, there is the following error:

(qemu) qemu-system-xtensa: -drive file=sd_image.bin,if=sd,format=raw: machine type does not support if=sd,bus=0,unit=0

Error logs or terminal output

Here are the logs for SDMMC & SPI flash tests.


ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x1 (POWERON),boot:0x4 (SPI_FLASH_BOOT)
SPIWP:0xee
mode:QIO, clock div:2
load:0x3fce2820,len:0x170c
load:0x403c8700,len:0x4
load:0x403c8704,len:0xec4
load:0x403cb700,len:0x318c
entry 0x403c8948
I (35) boot: ESP-IDF 5.4.1 2nd stage bootloader
I (39) boot: compile time Sep  2 2025 01:04:10
I (40) boot: Multicore bootloader
I (46) boot: chip revision: v0.0
I (47) boot: efuse block revision: v1.0
I (50) qio_mode: Enabling QIO for flash chip ISSI
I (54) boot.esp32s3: Boot SPI Speed : 40MHz
I (55) boot.esp32s3: SPI Mode       : SLOW READ
I (56) boot.esp32s3: SPI Flash Size : 16MB
I (59) boot: Enabling RNG early entropy source...
I (65) boot: Partition Table:
I (66) boot: ## Label            Usage          Type ST Offset   Length
I (68) boot:  0 nvs              WiFi data        01 02 00009000 00006000
I (70) boot:  1 phy_init         RF data          01 01 0000f000 00001000
I (72) boot:  2 factory          factory app      00 00 00010000 00200000
I (74) boot:  3 storage          Unknown data     01 83 00210000 000f0000
I (76) boot:  4 storage2         Unknown data     01 81 00300000 00a00000
I (78) boot: End of partition table
I (80) esp_image: segment 0: paddr=00010020 vaddr=3c030020 size=0ffb4h ( 65460) map
I (95) esp_image: segment 1: paddr=0001ffdc vaddr=3fc93e00 size=0003ch (    60) load
I (99) esp_image: segment 2: paddr=00020020 vaddr=42000020 size=2db00h (187136) map
I (144) esp_image: segment 3: paddr=0004db28 vaddr=3fc93e3c size=03104h ( 12548) load
I (151) esp_image: segment 4: paddr=00050c34 vaddr=40374000 size=0fd74h ( 64884) load
I (167) esp_image: segment 5: paddr=000609b0 vaddr=600fe100 size=0001ch (    28) load
I (172) boot: Loaded app from partition at offset 0x10000
I (174) boot: Disabling RNG early entropy source...
I (192) octal_psram: vendor id    : 0x0d (AP)
I (194) octal_psram: dev id       : 0x02 (generation 3)
I (195) octal_psram: density      : 0x03 (64 Mbit)
I (196) octal_psram: good-die     : 0x01 (Pass)
I (197) octal_psram: Latency      : 0x01 (Fixed)
I (199) octal_psram: VCC          : 0x00 (1.8V)
I (200) octal_psram: SRF          : 0x01 (Fast Refresh)
I (202) octal_psram: BurstType    : 0x01 (Hybrid Wrap)
I (204) octal_psram: BurstLen     : 0x01 (32 Byte)
I (205) octal_psram: Readlatency  : 0x02 (10 cycles@Fixed)
I (207) octal_psram: DriveStrength: 0x00 (1/1)
W (211) MSPI Timing: tuning fail, best point is fallen back to index 5
I (213) MSPI Timing: PSRAM timing tuning index: 5
I (216) esp_psram: Found 8MB PSRAM device
I (217) esp_psram: Speed: 80MHz
I (219) cpu_start: Multicore app
I (228) esp_psram: SPI SRAM memory test OK
I (242) cpu_start: Pro cpu start user code
I (243) cpu_start: cpu freq: 160000000 Hz
I (243) app_init: Application information:
I (244) app_init: Project name:     code_station
I (244) app_init: App version:      b3c1a5c-dirty
I (245) app_init: Compile time:     Sep  2 2025 01:03:26
I (245) app_init: ELF file SHA256:  b584162b0...
I (246) app_init: ESP-IDF:          5.4.1
I (246) efuse_init: Min chip rev:     v0.0
I (248) efuse_init: Max chip rev:     v0.99 
I (249) efuse_init: Chip rev:         v0.0
I (250) heap_init: Initializing. RAM available for dynamic allocation:
I (252) heap_init: At 3FC97978 len 00051D98 (327 KiB): RAM
I (252) heap_init: At 3FCE9710 len 00005724 (21 KiB): RAM
I (253) heap_init: At 3FCF0000 len 00008000 (32 KiB): DRAM
I (254) heap_init: At 600FE11C len 00001ECC (7 KiB): RTCRAM
I (256) esp_psram: Adding pool of 8192K of PSRAM memory to heap allocator
I (261) spi_flash: detected chip: issi
I (262) spi_flash: flash io: qio
W (265) i2c: This driver is an old driver, please migrate your application code to adapt `driver/i2c_master.h`
I (267) sleep_gpio: Configure to isolate all GPIO pins in sleep state
I (268) sleep_gpio: Enable automatic switching of GPIO sleep configuration
I (276) main_task: Started on CPU0
I (286) esp_psram: Reserving pool of 32K of internal memory for DMA/internal allocations
I (293) main_task: Calling app_main()
D (298) sdmmc_periph: peripheral version 0, hardware config 00000000
D (303) intr_alloc: Connected src 30 to int 9 (cpu 0)
D (308) sdmmc_periph: using GPIO39 as clk pin
I (313) gpio: GPIO[39]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
D (319) sdmmc_periph: using GPIO40 as cmd pin
I (322) gpio: GPIO[40]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
D (327) sdmmc_periph: using GPIO38 as d0 pin
I (371) gpio: GPIO[38]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
D (377) sdmmc_periph: using GPIO45 as d1 pin
I (380) gpio: GPIO[45]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
D (386) sdmmc_periph: using GPIO42 as d2 pin
I (390) gpio: GPIO[42]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
I (396) gpio: GPIO[41]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
D (403) sdmmc_periph: Slot 0 is not initialized yet, skipping sdmmc_host_change_to_slot
D (409) sdmmc_periph: clk_src_freq_hz: 160000000 hz
D (412) sdmmc_periph: slot=0 clk_src=6 host_div=10 card_div=20 freq=400kHz (max 400kHz)
D (417) sdmmc_periph: Slot 0 is not initialized yet, skipping sdmmc_host_change_to_slot
D (422) sdmmc_periph: Slot 0 is not initialized yet, skipping sdmmc_host_change_to_slot
D (428) sdmmc_periph: slot=0 width=1
E (1432) sdmmc_req: sdmmc_host_wait_for_event returned 0x107
D (1439) sdmmc_cmd: cmd=52, sdmmc_req_run returned 0x107
E (2443) sdmmc_req: sdmmc_host_wait_for_event returned 0x107
D (2448) sdmmc_cmd: cmd=0, sdmmc_req_run returned 0x107
D (2453) sdmmc_init: sdmmc_card_init: sdmmc_send_cmd_go_idle_state returned 0x107
E (2456) vfs_fat_sdmmc: sdmmc_card_init failed (0x107).
I (2462) gpio: GPIO[39]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
I (2468) gpio: GPIO[40]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
I (2473) gpio: GPIO[38]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
I (2478) gpio: GPIO[45]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
I (2484) gpio: GPIO[42]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
I (2490) gpio: GPIO[41]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
D (2498) sdmmc_periph: SDMMC host deinitialized
E (2502) SDMMC: Failed to initialize the card (ESP_ERR_TIMEOUT). 
I (2508) main_task: Returned from app_main()


---
    

I (283) main_task: Calling app_main()
D (295) wl_flash: config - config result: state_size=0x0000b000, cfg_size=0x00001000, addr_cfg=0x009ff000, addr_state1=0x009e9000, addr_state2=0x009f4000, flash_size=0x009e8000
D (309) wl_flash: init - config ID=2, stored ID=4294967295, wl_sec_erase_cycle_count=4294967295, wl_block_size=4294967295, wl_max_sec_erase_cycle_count=4294967295, wl_dummy_sec_pos=4294901760, wl_dummy_sec_move_count=0xFFFFFFFF
D (332) wl_flash: init starts: crc1= 0x7092074e, crc2 = 0x7092074e, this->state.crc= 0xffffffff, state_copy->crc= 0xffffffff, version=2, read_version=4294967295
D (341) wl_flash: init: try to update version - crc1= 0x7092074e, crc2 = 0x7092074e, result= 0x00000000
D (347) wl_flash: updateV1_V2 - process crc1=0xa2f49d8d, crc2=0xa2f49d8d, v1_crc1=0xffffffff, v1_crc2=0xffffffff, version=4294967295
D (354) wl_flash: init: init flash sections
D (375) wl_flash: initSections - this->state->wl_max_sec_erase_cycle_count= 0x00000010, this->state->wl_part_max_sec_pos= 0x000009e9
D (384) wl_flash: initSections - result= 0x00000000
D (388) wl_flash: recoverPos - this->state.wl_dummy_sec_pos= 0x00000000, position= 0x00000000, result= 0x00000000, wl_part_max_sec_pos= 0x000009e9
D (397) wl_flash: init - wl_dummy_sec_move_count= 0x00000000
D (401) vfs_fat_spiflash: using pdrv=0
D (406) wl_flash: read - src_addr= 0x00000000, size= 0x00001000
W (416) vfs_fat_spiflash: f_mount failed (13)
I (419) vfs_fat_spiflash: Formatting FATFS partition, allocation unit size=4096
D (427) wl_flash: erase_range - start_address= 0x00000000, size= 0x00001000
D (432) wl_flash: erase_sector - sector= 0x00000000
D (435) wl_flash: write - dest_addr= 0x00000000, size= 0x00001000
D (539) wl_flash: erase_range - start_address= 0x00001000, size= 0x00001000
D (545) wl_flash: erase_sector - sector= 0x00000001
D (549) wl_flash: write - dest_addr= 0x00001000, size= 0x00001000
D (618) wl_flash: erase_range - start_address= 0x00002000, size= 0x00001000
D (623) wl_flash: erase_sector - sector= 0x00000002
D (626) wl_flash: write - dest_addr= 0x00002000, size= 0x00001000
D (700) wl_flash: erase_range - start_address= 0x00003000, size= 0x00001000
D (704) wl_flash: erase_sector - sector= 0x00000003
D (708) wl_flash: write - dest_addr= 0x00003000, size= 0x00001000
D (786) wl_flash: erase_range - start_address= 0x00004000, size= 0x00001000
D (791) wl_flash: erase_sector - sector= 0x00000004
D (795) wl_flash: write - dest_addr= 0x00004000, size= 0x00001000
D (872) wl_flash: erase_range - start_address= 0x00005000, size= 0x00001000
D (875) wl_flash: erase_sector - sector= 0x00000005
D (879) wl_flash: write - dest_addr= 0x00005000, size= 0x00001000
D (940) wl_flash: erase_range - start_address= 0x00006000, size= 0x00001000
D (946) wl_flash: erase_sector - sector= 0x00000006
D (949) wl_flash: write - dest_addr= 0x00006000, size= 0x00001000
I (1024) vfs_fat_spiflash: Mounting again
D (1028) wl_flash: read - src_addr= 0x00000000, size= 0x00001000
E (1034) vfs_fat_spiflash: s_f_mount_rw(118): f_mount failed after formatting (13)
E (1040) SDMMC: Failed to mount filesystem. 
I (1045) main_task: Returned from app_main()

Steps to reproduce the behavior

Here are the code snippets used for SDMMC & SPI flash tests.

SDMMC:

esp_err_t ret;

// Default: 20MHz
sdmmc_host_t host = SDMMC_HOST_DEFAULT();
host.slot = SDMMC_HOST_SLOT_0;

// Default: 4-bits
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
slot.width = 4;
slot.clk = GPIO_SD_CLK;
slot.cmd = GPIO_SD_CMD;
slot.d0  = GPIO_SD_DATA0;
slot.d1  = GPIO_SD_DATA1;
slot.d2  = GPIO_SD_DATA2;
slot.d3  = GPIO_SD_DATA3;

esp_vfs_fat_sdmmc_mount_config_t mount_config =
{
    .format_if_mount_failed = true,
    .max_files = 5,
    .allocation_unit_size = 16 * 1024 // Only if format on fail is used...
};

/*
 *   - initializes SDMMC driver
 *   - initializes SD card
 *   - mounts FAT partition on SD card using FATFS library
 *   - registers FATFS library with VFS, with prefix */
ret = esp_vfs_fat_sdmmc_mount(SD_MOUNT_POINT, &host, &slot, &mount_config, &card);
if (ret != ESP_OK) {
    if (ret == ESP_FAIL) {
        ESP_LOGE(TAG, "Failed to mount filesystem. ");
    } else {
        ESP_LOGE(TAG, "Failed to initialize the card (%s). ", esp_err_to_name(ret));
    }
}

SPI flash:

wl_handle_t spiflash_card;
mount_config = (esp_vfs_fat_sdmmc_mount_config_t) {
    .format_if_mount_failed = true,
    .max_files = 4,
    .allocation_unit_size = 512
};
ret = esp_vfs_fat_spiflash_mount_rw_wl(SD_MOUNT_POINT, "storage2", &mount_config, &spiflash_card);

Project release version

9.2.2 (esp_develop_9.2.2_20250817)

System architecture

Intel/AMD 64-bit (modern PC, older Mac)

Operating system

Linux

Operating system version

Debian Testing

Shell

ZSH

Additional context

No response

[ysard]

I confirm that #140 solves the SD card problem. The problem with the internal SPI flash remains (or maybe I'm missing something).

[Throows]

Awesome !
As far as I know, the SPI is not officially supported so I just implemented the SDMMC.

Does the SD card works in SPI mode with ESP32 ? (If yes I'll try to make it work with esp32s3 too 😅)

~Romain

[ysard]

I don't know if SPI mode is supposed to work on esp32 emulation, but it doesn't work as it is currently on esp32s3.

Code:
(EDIT: this code is wrong, SPI bus is not initialized, host is not initialized correctly; see below)

    #define GPIO_SD_CLK             GPIO_NUM_39
    #define GPIO_SD_CMD             GPIO_NUM_40
    #define GPIO_SD_DATA0           GPIO_NUM_38
    #define GPIO_SD_DATA1           GPIO_NUM_45

    sdmmc_card_t *card;
    
    sdmmc_host_t host = SDMMC_HOST_DEFAULT();
    
    esp_vfs_fat_sdmmc_mount_config_t mount_config =
    {
        .format_if_mount_failed = true,
        .max_files = 4,
        .allocation_unit_size = 16 * 1024
    };
    
    sdspi_device_config_t slot_config = SDSPI_DEVICE_CONFIG_DEFAULT();
    
    slot_config.gpio_cs = GPIO_SD_DATA0;
    slot_config.gpio_cd = GPIO_SD_DATA1;
    slot_config.gpio_wp = GPIO_SD_CLK;
    slot_config.gpio_int = GPIO_SD_CMD;
    
    ret = esp_vfs_fat_sdspi_mount("/sdcard", &host, &slot_config, &mount_config, &card);

Result (similar with default pins):

D (672) sdspi_host: sdspi_host_init_device: SPI2 cs=38 cd=45 wp=39 wp_polarity:0
E (682) spi_master: spi_master_init_driver(274): host_id not initialized
D (682) sdspi_host: spi_bus_add_device failed with rc=0x103
E (682) vfs_fat_sdmmc: Failed to attach sdspi device onto an SPI bus (rc=0x103), please initialize the bus first and check the device parameters.
E (692) vfs_fat_sdmmc: slot init failed (0x103).
E (702) SDMMC: Failed to initialize the card (ESP_ERR_INVALID_STATE). 

Internal SPI flash mount (different from SD SPI) and also littlefs mount, are more problematic since there are no available fallback.

[igrr]

Regarding the last code snippet, I think it would fail the same way on a real chip. As the error indicates, you aren't initializing the SPI bus, so adding an SPI device fails.

Anyway, even if SD in SPI mode would work in QEMU, it would be incredibly slow, since SPI emulation is done on a byte-by-byte level, similar to how the internal Flash is emulated.

For SPI flash emulation issue, could you please try switching to DIO mode (default is QIO)?

[ysard]

@igrr Ok, indeed, my code was seriously wrong for SD SPI. Thanks for pointing that. Here is the modified snippet:

    #define GPIO_SPI_SCLK            GPIO_NUM_39
    #define GPIO_SPI_MOSI            GPIO_NUM_40
    #define GPIO_SPI_MISO            GPIO_NUM_38
    #define GPIO_SPI_CS              GPIO_NUM_45

    sdmmc_card_t *card;
    sdmmc_host_t host = SDSPI_HOST_DEFAULT();
    spi_bus_config_t bus_cfg = {
        .mosi_io_num = GPIO_SPI_MOSI,
        .miso_io_num = GPIO_SPI_MISO,
        .sclk_io_num = GPIO_SPI_SCLK,
        .quadwp_io_num = -1,
        .quadhd_io_num = -1,
        // .max_transfer_sz = 4000,
    };
    ret = spi_bus_initialize(host.slot, &bus_cfg, SPI_DMA_CH_AUTO);
    // Do not forget spi_bus_free(host.slot); later
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to initialize bus.");
        return ret;
    }

    sdspi_device_config_t slot_config = SDSPI_DEVICE_CONFIG_DEFAULT();

    slot_config.gpio_cs = GPIO_SPI_CS;
    // slot_config.gpio_cd = ;
    // slot_config.gpio_wp = ;
    // slot_config.gpio_int = ;
    // slot_config.host_id = host.slot; // useful ?

    ret = esp_vfs_fat_sdspi_mount("/sdcard", &host, &slot_config, &mount_config, &card);

Logs:

I (687) SDMMC: Using SPI peripheral
D (687) gdma: new group (0) at 0x3fcb94e0
D (697) gdma: new pair (0,0) at 0x3fcb932c
D (697) gdma: new tx channel (0,0) at 0x3fcb94a8
D (707) gdma: new rx channel (0,0) at 0x3fcb956c
D (717) spi: SPI2 use gpio matrix.
D (717) sdspi_host: sdspi_host_init_device: SPI2 cs=45 cd=-1 wp=-1 wp_polarity:0
D (727) intr_alloc: Connected src 21 to int 13 (cpu 0)
D (747) spi_hal: eff: 400, limit: 80000k(/0), 0 dummy, -1 delay
D (747) spi_master: SPI2: New device added to CS5, effective clock: 400000 Hz
I (747) gpio: GPIO[45]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
D (757) spi_master: device5 locked the bus

The emulation hangs with no apparent crash/backtrace. Again this is not a big issue since we have the SDMMC.

---

For the SPI flash emulation, yes the DIO mode (Menuconfig : Serial flasher config → Flash SPI mode) solves all the problems (littlefs included).
I don't think I could have found it on my own, thanks!

All issues are solved for me.