SD SPI Host Driver

Overview

SPI controllers accessible via spi_master driver (HSPI, VSPI) can be used to work with SD cards. The driver which provides this capability is called “SD SPI Host”, due to its similarity with the SDMMC Host driver.

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.

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

API Reference

Functions

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

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

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_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_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

Structures

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)

Macros

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.

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