SDMMC Host Peripheral¶
Overview¶
SDMMC peripheral supports SD and MMC memory cards and SDIO cards. SDMMC software builds on top of SDMMC driver and consists of the following parts:
- SDMMC host driver (
driver/sdmmc_host.h
) — this driver provides APIs to send commands to the slave device(s), send and receive data, and handling error conditions on the bus. - SDMMC protocol layer (
sdmmc_cmd.h
) — this component handles specifics of SD protocol such as card initialization and data transfer commands. Despite the name, only SD (SDSC/SDHC/SDXC) cards are supported at the moment. Support for MCC/eMMC cards can be added in the future.
Protocol layer works with the host via sdmmc_host_t
structure. This structure contains pointers to various functions of the host.
In addition to SDMMC Host peripheral, ESP32 has SPI peripherals which can also be used to work with SD cards. This is supported using a variant of the host driver, driver/sdspi_host.h
. This driver has the same interface as SDMMC host driver, and the protocol layer can use either of two.
Application Example¶
An example which combines SDMMC driver with FATFS library is provided in examples/storage/sd_card
directory. This example initializes the card, writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
Protocol layer APIs¶
Protocol layer is given sdmmc_host_t
structure which describes the SD/MMC host driver, lists its capabilites, and provides pointers to functions of the driver. Protocol layer stores card-specific information in sdmmc_card_t
structure. When sending commands to the SD/MMC host driver, protocol layer uses sdmmc_command_t
structure to describe the command, argument, expected return value, and data to transfer, if any.
Normal usage of the protocol layer is as follows:
- Call the host driver functions to initialize the host (e.g.
sdmmc_host_init
,sdmmc_host_init_slot
). - Call
sdmmc_card_init
to initialize the card, passing it host driver information (host
) and a pointer tosdmmc_card_t
structure which will be filled in (card
). - To read and write sectors of the card, use
sdmmc_read_sectors
andsdmmc_write_sectors
, passing the pointer to card information structure (card
). - When card is not used anymore, call the host driver function to disable SDMMC host peripheral and free resources allocated by the driver (e.g.
sdmmc_host_deinit
).
Most applications need to use the protocol layer only in one task; therefore the protocol layer doesn’t implement any kind of locking on the sdmmc_card_t
structure, or when accessing SDMMC host driver. Such locking has to be implemented in the higher layer, if necessary (e.g. in the filesystem driver).
-
struct
sdmmc_host_t
¶ SD/MMC Host description
This structure defines properties of SD/MMC host and functions of SD/MMC host which can be used by upper layers.
Public Members
-
uint32_t
flags
¶ flags defining host properties
-
int
slot
¶ slot number, to be passed to host functions
-
int
max_freq_khz
¶ max frequency supported by the host
-
float
io_voltage
¶ I/O voltage used by the controller (voltage switching is not supported)
-
esp_err_t (*
init
)(void)¶ Host function to initialize the driver
-
esp_err_t (*
set_bus_width
)(int slot, size_t width)¶ host function to set bus width
-
esp_err_t (*
set_card_clk
)(int slot, uint32_t freq_khz)¶ host function to set card clock frequency
-
esp_err_t (*
do_transaction
)(int slot, sdmmc_command_t *cmdinfo)¶ host function to do a transaction
-
esp_err_t (*
deinit
)(void)¶ host function to deinitialize the driver
-
int
command_timeout_ms
¶ timeout, in milliseconds, of a single command. Set to 0 to use the default value.
-
uint32_t
-
SDMMC_HOST_FLAG_1BIT
¶ host supports 1-line SD and MMC protocol
-
SDMMC_HOST_FLAG_4BIT
¶ host supports 4-line SD and MMC protocol
-
SDMMC_HOST_FLAG_8BIT
¶ host supports 8-line MMC protocol
-
SDMMC_HOST_FLAG_SPI
¶ host supports SPI protocol
-
SDMMC_FREQ_DEFAULT
¶ SD/MMC Default speed (limited by clock divider)
-
SDMMC_FREQ_HIGHSPEED
¶ SD High speed (limited by clock divider)
-
SDMMC_FREQ_PROBING
¶ SD/MMC probing speed
-
struct
sdmmc_command_t
¶ SD/MMC command information
Public Members
-
uint32_t
opcode
¶ SD or MMC command index
-
uint32_t
arg
¶ SD/MMC command argument
-
sdmmc_response_t
response
¶ response buffer
-
void *
data
¶ buffer to send or read into
-
size_t
datalen
¶ length of data buffer
-
size_t
blklen
¶ block length
-
int
flags
¶ see below
-
esp_err_t
error
¶ error returned from transfer
-
int
timeout_ms
¶ response timeout, in milliseconds
-
uint32_t
-
struct
sdmmc_card_t
¶ SD/MMC card information structure
Public Members
-
sdmmc_host_t
host
¶ Host with which the card is associated
-
uint32_t
ocr
¶ OCR (Operation Conditions Register) value
-
sdmmc_cid_t
cid
¶ decoded CID (Card IDentification) register value
-
sdmmc_csd_t
csd
¶ decoded CSD (Card-Specific Data) register value
-
sdmmc_scr_t
scr
¶ decoded SCR (SD card Configuration Register) value
-
uint16_t
rca
¶ RCA (Relative Card Address)
-
sdmmc_host_t
-
struct
sdmmc_csd_t
¶ Decoded values from SD card Card Specific Data register
-
struct
sdmmc_cid_t
¶ Decoded values from SD card Card IDentification register
-
struct
sdmmc_scr_t
¶ Decoded values from SD Configuration Register
-
esp_err_t
sdmmc_card_init
(const sdmmc_host_t *host, sdmmc_card_t *out_card)¶ Probe and initialize SD/MMC card using given host
- Note
- Only SD cards (SDSC and SDHC/SDXC) are supported now. Support for MMC/eMMC cards will be added later.
- Return
- ESP_OK on success
- One of the error codes from SDMMC host controller
- Parameters
host
: pointer to structure defining host controllerout_card
: pointer to structure which will receive information about the card when the function completes
-
esp_err_t
sdmmc_write_sectors
(sdmmc_card_t *card, const void *src, size_t start_sector, size_t sector_count)¶ Write given number of sectors to SD/MMC card
- Return
- ESP_OK on success
- One of the error codes from SDMMC host controller
- Parameters
card
: pointer to card information structure previously initialized using sdmmc_card_initsrc
: pointer to data buffer to read data from; data size must be equal to sector_count * card->csd.sector_sizestart_sector
: sector where to start writingsector_count
: number of sectors to write
-
esp_err_t
sdmmc_read_sectors
(sdmmc_card_t *card, void *dst, size_t start_sector, size_t sector_count)¶ Write given number of sectors to SD/MMC card
- Return
- ESP_OK on success
- One of the error codes from SDMMC host controller
- Parameters
card
: pointer to card information structure previously initialized using sdmmc_card_initdst
: pointer to data buffer to write into; buffer size must be at least sector_count * card->csd.sector_sizestart_sector
: sector where to start readingsector_count
: number of sectors to read
SDMMC host driver APIs¶
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.
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
.
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.
-
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
-
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_WIDTH_DEFAULT
¶ use the default width for the slot (8 for slot 0, 4 for slot 1)
-
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
-
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
-
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_CONFIG_DEFAULT
()¶ Macro defining default configuration of SDMMC host 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)
-
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_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
SD SPI driver APIs¶
SPI controllers accessible via spi_master driver (HSPI, VSPI) can be used to work with SD cards. In SPI mode, SD driver has lower throughput than in 1-line SD mode. However SPI mode makes pin selection more flexible, as SPI peripheral can be connected to any ESP32 pins using GPIO Matrix. SD SPI driver uses software controlled CS signal. Currently SD SPI driver assumes that it can use the SPI controller exclusively, so applications which need to share SPI bus between SD cards and other peripherals need to make sure that SD card and other devices are not used at the same time from different tasks.
SD SPI driver is represented using an sdmmc_host_t
structure initialized using SDSPI_HOST_DEFAULT
macro. For slot initialization, SDSPI_SLOT_CONFIG_DEFAULT
can be used to fill in default pin mapping, which is the same as the pin mapping in SD mode.
SD SPI driver APIs are very similar to SDMMC host APIs. As with the SDMMC host driver, only sdspi_host_init
, sdspi_host_init_slot
, and sdspi_host_deinit
functions are normally used by the applications. Other functions are called by the protocol level driver via function pointers in sdmmc_host_t
structure.
-
esp_err_t
sdspi_host_init
()¶ Initialize SD SPI driver.
- Note
- This function is not thread safe
- Return
- ESP_OK on success
- other error codes may be returned in future versions
-
SDSPI_HOST_DEFAULT
()¶ Default sdmmc_host_t structure initializer for SD over SPI driver.
Uses SPI mode and max frequency set to 20MHz
‘slot’ can be set to one of HSPI_HOST, VSPI_HOST.
-
esp_err_t
sdspi_host_init_slot
(int slot, const sdspi_slot_config_t *slot_config)¶ Initialize SD SPI driver for the specific SPI controller.
- Note
- This function is not thread safe
- Return
- ESP_OK on success
- ESP_ERR_INVALID_ARG if sdspi_init_slot has invalid arguments
- ESP_ERR_NO_MEM if memory can not be allocated
- other errors from the underlying spi_master and gpio drivers
- Parameters
slot
: SPI controller to use (HSPI_HOST or VSPI_HOST)slot_config
: pointer to slot configuration structure
-
struct
sdspi_slot_config_t
¶ Extra configuration for SPI host
Public Members
-
gpio_num_t
gpio_miso
¶ GPIO number of MISO signal.
-
gpio_num_t
gpio_mosi
¶ GPIO number of MOSI signal.
-
gpio_num_t
gpio_sck
¶ GPIO number of SCK signal.
-
gpio_num_t
gpio_cs
¶ GPIO number of CS signal.
-
gpio_num_t
gpio_cd
¶ GPIO number of card detect signal.
-
gpio_num_t
gpio_wp
¶ GPIO number of write protect signal.
-
int
dma_channel
¶ DMA channel to be used by SPI driver (1 or 2)
-
gpio_num_t
-
SDSPI_SLOT_NO_CD
¶ indicates that card detect line is not used
-
SDSPI_SLOT_NO_WP
¶ indicates that write protect line is not used
-
SDSPI_SLOT_CONFIG_DEFAULT
()¶ Macro defining default configuration of SPI host
-
esp_err_t
sdspi_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
: SPI controller (HSPI_HOST or VSPI_HOST)freq_khz
: card clock frequency, in kHz
-
esp_err_t
sdspi_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 sdspi_host_do_transaction as long as other sdspi_host_* functions are not called.
- 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
- Parameters
slot
: SPI controller (HSPI_HOST or VSPI_HOST)cmdinfo
: pointer to structure describing command and data to transfer
-
esp_err_t
sdspi_host_deinit
()¶ Release resources allocated using sdspi_host_init.
- Note
- This function is not thread safe
- Return
- ESP_OK on success
- ESP_ERR_INVALID_STATE if sdspi_host_init function has not been called