SDMMC Host Driver¶
Overview¶
On the ESP32, SDMMC host peripheral has two slots:
- Slot 0 (
SDMMC_HOST_SLOT_0
) is an 8-bit slot. It usesHS1_*
signals in the PIN MUX. - Slot 1 (
SDMMC_HOST_SLOT_1
) is a 4-bit slot. It usesHS2_*
signals in the PIN MUX.
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 when 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.
警告
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.
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.
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.
API Reference¶
Header File¶
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_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
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)
-
gpio_num_t
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_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