SD SPI Host Driver

Overview

The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards. This driver’s naming pattern was adopted from the SDMMC Host driver due to their similarity. Likewise, the APIs of both drivers are also very similar.

The SD SPI host driver has the following modes:

  • SPI mode: offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral’s signals can be routed to any ESP32 pin.
  • 1-bit SD mode: offers higher throughput but requires routing the signals through their dedicated IO_MUX pins only.

The SD SPI driver uses software-controlled CS signal.

Currently, the SD SPI driver cannot handle multi-threaded environments as does not support time-division multiplexing on the same SPI bus. It means that if your application needs to communicate with an SD card and other devices on the same SPI bus, the application itself must ensure that its different tasks do not try to access the SPI slaves at the same time.

How to Use

The state and configurations of the SD SPI host driver are stored in a sdmmc_host_t structure. This structure can be initialized using the SDSPI_HOST_DEFAULT macro.

The state and configurations of the SD slot are stored in a sdmmc_slot_config_t structure. Use the macro SDSPI_SLOT_CONFIG_DEFAULT to initialize the structure and to fill in the default pin mappings (SD mode pin mappings).

Only the following driver’s API functions are normally used by most applications:

Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the sdmmc_host_t structure. For more details, see the SD/SDIO/MMC Driver.

Note

SD over SPI does not support speeds above SDMMC_FREQ_DEFAULT due to the limitations of the SPI driver.

API Reference

Functions

esp_err_t sdspi_host_init(void)

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
Note
The SDIO over sdspi needs an extra interrupt line. Call gpio_install_isr_service() before this function.
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(void)

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

esp_err_t sdspi_host_io_int_enable(int slot)

Enable SDIO interrupt.

Return
  • ESP_OK on success
Parameters
  • slot: SPI controller to use (HSPI_HOST or VSPI_HOST)

esp_err_t sdspi_host_io_int_wait(int slot, TickType_t timeout_ticks)

Wait for SDIO interrupt until timeout.

Return
  • ESP_OK on success
Parameters
  • slot: SPI controller to use (HSPI_HOST or VSPI_HOST)
  • timeout_ticks: Ticks to wait before timeout.

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.

gpio_num_t gpio_int

GPIO number of interrupt line (input) for SDIO card.

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_NO_INT

indicates that interrupt line is not used

SDSPI_SLOT_CONFIG_DEFAULT()

Macro defining default configuration of SPI host