SDMMC Host Driver

Overview

On the ESP32, SDMMC host peripheral has two slots:

Pin mappings of these slots are given in the following table:

Signal Slot 0 Slot 1
CMD GPIO11 GPIO15
CLK GPIO6 GPIO14
D0 GPIO7 GPIO2
D1 GPIO8 GPIO4
D2 GPIO9 GPIO12
D3 GPIO10 GPIO13
D4 GPIO16  
D5 GPIO17  
D6 GPIO5  
D7 GPIO18  
CD any input via GPIO matrix
WP any input via GPIO matrix

Card Detect and Write Protect signals can be routed to arbitrary pins using GPIO matrix. To use these pins, set gpio_cd and gpio_wp members of sdmmc_slot_config_t structure before calling sdmmc_host_init_slot(). Note that it is not advised to specify Card Detect pin when working with SDIO cards, because in ESP32 card detect signal can also trigger SDIO slave interrupt.

Warning

Pins used by slot 0 (HS1_*) are also used to connect SPI flash chip in ESP-WROOM32 and ESP32-WROVER modules. These pins can not be shared between SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set Efuses accordingly.

Supported speed modes

SDMMC Host driver supports the following speed modes:

  • Default Speed (20MHz), 4-line/1-line (with SD cards), and 8-line (with 3.3V eMMC).
  • High Speed (40MHz), 4-line/1-line (with SD cards), and 8-line (with 3.3V eMMC)
  • High Speed DDR (40MHz), 4-line (with 3.3V eMMC)

Not supported at present are:

  • High Speed DDR mode, 8-line eMMC
  • UHS-I 1.8V modes, 4-line SD cards

Using the SDMMC Host driver

Of all the funtions listed below, only sdmmc_host_init(), sdmmc_host_init_slot(), and sdmmc_host_deinit() will be used directly by most applications.

Other functions, such as sdmmc_host_set_bus_width(), sdmmc_host_set_card_clk(), and sdmmc_host_do_transaction() will be called by the SD/MMC protocol layer via function pointers in sdmmc_host_t structure.

Configuring bus width and frequency

With the default initializers for sdmmc_host_t and sdmmc_slot_config_t (SDMMC_HOST_DEFAULT and SDMMC_SLOT_CONFIG_DEFAULT), SDMMC Host driver will attempt to use widest bus supported by the card (4 lines for SD, 8 lines for eMMC) and 20MHz frequency.

In designs where communication at 40MHz frequency can be achieved, it is possible to increase the bus frequency to by changing max_freq_khz field of sdmmc_host_t:

sdmmc_host_t host = SDMMC_HOST_DEFAULT();
host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;

To configure bus width, set width field of sdmmc_slot_config_t. For example, to set 1-line mode:

sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
slot.width = 1;

See also

See SD/SDIO/MMC Driver for the higher level driver which implements the protocol layer.

See SD SPI Host Driver for a similar driver which uses SPI controller and is limited to SPI mode of SD protocol.

See SD Pullup Requirements for pullup support and compatiblities about modules and devkits.

API Reference

Functions

esp_err_t sdmmc_host_init()

Initialize SDMMC host peripheral.

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_STATE if sdmmc_host_init was already called
  • ESP_ERR_NO_MEM if memory can not be allocated

esp_err_t sdmmc_host_init_slot(int slot, const sdmmc_slot_config_t *slot_config)

Initialize given slot of SDMMC peripheral.

On the ESP32, SDMMC peripheral has two slots:

  • Slot 0: 8-bit wide, maps to HS1_* signals in PIN MUX
  • Slot 1: 4-bit wide, maps to HS2_* signals in PIN MUX

Card detect and write protect signals can be routed to arbitrary GPIOs using GPIO matrix.

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_STATE if host has not been initialized using sdmmc_host_init
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • slot_config: additional configuration for the slot

esp_err_t sdmmc_host_set_bus_width(int slot, size_t width)

Select bus width to be used for data transfer.

SD/MMC card must be initialized prior to this command, and a command to set bus width has to be sent to the card (e.g. SD_APP_SET_BUS_WIDTH)

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_ARG if slot number or width is not valid
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • width: bus width (1, 4, or 8 for slot 0; 1 or 4 for slot 1)

size_t sdmmc_host_get_slot_width(int slot)

Get bus width configured in sdmmc_host_init_slot to be used for data transfer.

Return
configured bus width of the specified slot.
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)

esp_err_t sdmmc_host_set_card_clk(int slot, uint32_t freq_khz)

Set card clock frequency.

Currently only integer fractions of 40MHz clock can be used. For High Speed cards, 40MHz can be used. For Default Speed cards, 20MHz can be used.

Note
This function is not thread safe
Return
  • ESP_OK on success
  • other error codes may be returned in the future
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • freq_khz: card clock frequency, in kHz

esp_err_t sdmmc_host_set_bus_ddr_mode(int slot, bool ddr_enabled)

Enable or disable DDR mode of SD interface.

Return
  • ESP_OK on success
  • ESP_ERR_NOT_SUPPORTED if DDR mode is not supported on this slot
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • ddr_enabled: enable or disable DDR mode

esp_err_t sdmmc_host_do_transaction(int slot, sdmmc_command_t *cmdinfo)

Send command to the card and get response.

This function returns when command is sent and response is received, or data is transferred, or timeout occurs.

Note
This function is not thread safe w.r.t. init/deinit functions, and bus width/clock speed configuration functions. Multiple tasks can call sdmmc_host_do_transaction as long as other sdmmc_host_* functions are not called.
Attention
Data buffer passed in cmdinfo->data must be in DMA capable memory
Return
  • ESP_OK on success
  • ESP_ERR_TIMEOUT if response or data transfer has timed out
  • ESP_ERR_INVALID_CRC if response or data transfer CRC check has failed
  • ESP_ERR_INVALID_RESPONSE if the card has sent an invalid response
  • ESP_ERR_INVALID_SIZE if the size of data transfer is not valid in SD protocol
  • ESP_ERR_INVALID_ARG if the data buffer is not in DMA capable memory
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • cmdinfo: pointer to structure describing command and data to transfer

esp_err_t sdmmc_host_io_int_enable(int slot)

Enable IO interrupts.

This function configures the host to accept SDIO interrupts.

Return
returns ESP_OK, other errors possible in the future
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)

esp_err_t sdmmc_host_io_int_wait(int slot, TickType_t timeout_ticks)

Block until an SDIO interrupt is received, or timeout occurs.

Return
  • ESP_OK on success (interrupt received)
  • ESP_ERR_TIMEOUT if the interrupt did not occur within timeout_ticks
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • timeout_ticks: number of RTOS ticks to wait for the interrupt

esp_err_t sdmmc_host_deinit()

Disable SDMMC host and release allocated resources.

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_STATE if sdmmc_host_init function has not been called

esp_err_t sdmmc_host_pullup_en(int slot, int width)

Enable the pull-ups of sd pins.

Note
You should always place actual pullups on the lines instead of using this function. Internal pullup resistance are high and not sufficient, may cause instability in products. This is for debug or examples only.
Return
  • ESP_OK: if success
  • ESP_ERR_INVALID_ARG: if configured width larger than maximum the slot can support
Parameters
  • slot: Slot to use, normally set it to 1.
  • width: Bit width of your configuration, 1 or 4.

Structures

struct sdmmc_slot_config_t

Extra configuration for SDMMC peripheral slot

Public Members

gpio_num_t gpio_cd

GPIO number of card detect signal.

gpio_num_t gpio_wp

GPIO number of write protect signal.

uint8_t width

Bus width used by the slot (might be less than the max width supported)

uint32_t flags

Features used by this slot.

Macros

SDMMC_HOST_SLOT_0

SDMMC slot 0.

SDMMC_HOST_SLOT_1

SDMMC slot 1.

SDMMC_HOST_DEFAULT()

Default sdmmc_host_t structure initializer for SDMMC peripheral.

Uses SDMMC peripheral, with 4-bit mode enabled, and max frequency set to 20MHz

SDMMC_SLOT_FLAG_INTERNAL_PULLUP

Enable internal pullups on enabled pins. The internal pullups are insufficient however, please make sure external pullups are connected on the bus. This is for debug / example purpose only.

SDMMC_SLOT_NO_CD

indicates that card detect line is not used

SDMMC_SLOT_NO_WP

indicates that write protect line is not used

SDMMC_SLOT_WIDTH_DEFAULT

use the default width for the slot (8 for slot 0, 4 for slot 1)

SDMMC_SLOT_CONFIG_DEFAULT()

Macro defining default configuration of SDMMC host slot