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.
注解
SD over SPI does not support speeds above SDMMC_FREQ_DEFAULT
due to the limitations of the SPI driver.
API Reference¶
Header File¶
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
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)
-
gpio_num_t
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