SD SPI Host Driver¶
Overview¶
The SD SPI host driver allows communicating with one or more SD cards by the SPI Master driver which makes use of the SPI host. Each card is accessed through an SD SPI device represented by an sdspi_dev_handle_t spi_handle returned when attaching the device to an SPI bus by calling sdspi_host_init_device. The bus should be already initialized before (by spi_bus_initialize).
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.
SD SPI driver (access the SD card in 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. Otherwise, if SDMMC host driver is used (See SDMMC Host) to access the card in SD 1-bit/4-bit mode, higher throughput can be reached but it requires routing the signals through their dedicated IO_MUX pins only.
With the help of SPI Master driver based on, the SPI bus can be shared among SD cards and other SPI devices. The SPI Master driver will handle exclusive access from different tasks.
The SD SPI driver uses software-controlled CS signal.
How to Use¶
Firstly, use the macro SDSPI_DEVICE_CONFIG_DEFAULT
to initialize a structure sdmmc_slot_config_t
, which is used to initialize an SD SPI device. This macro will also fill in the default pin mappings, which is same as the pin mappings of SDMMC host driver. Modify the host and pins of the structure to desired value. Then call sdspi_host_init_device to initialize the SD SPI device and attach to its bus.
Then use SDSPI_HOST_DEFAULT
macro to initialize a sdmmc_host_t
structure, which is used to store the state and configurations of upper layer (SD/SDIO/MMC driver). Modify the slot parameter of the structure to the SD SPI device spi_handle just returned from sdspi_host_init_device. Call sdmmc_card_init with the sdmmc_host_t
to probe and initialize the SD card.
Now you can use SD/SDIO/MMC driver functions to access your card!
Other Details¶
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_device
(const sdspi_device_config_t *dev_config, sdspi_dev_handle_t *out_handle)¶ Attach and initialize an SD SPI device on the specific SPI bus.
- Note
This function is not thread safe
- Note
Initialize the SPI bus by
spi_bus_initialize()
before calling this function.- 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_host_init_device has invalid arguments
ESP_ERR_NO_MEM if memory can not be allocated
other errors from the underlying spi_master and gpio drivers
- Parameters
dev_config
: pointer to device configuration structureout_handle
: Output of the handle to the sdspi device.
-
esp_err_t
sdspi_host_remove_device
(sdspi_dev_handle_t handle)¶ Remove an SD SPI device.
- Return
Always ESP_OK
- Parameters
handle
: Handle of the SD SPI device
-
esp_err_t
sdspi_host_do_transaction
(sdspi_dev_handle_t handle, 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
handle
: Handle of the sdspi devicecmdinfo
: pointer to structure describing command and data to transfer
-
esp_err_t
sdspi_host_set_card_clk
(sdspi_dev_handle_t host, 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
host
: Handle of the sdspi devicefreq_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
(sdspi_dev_handle_t handle)¶ Enable SDIO interrupt.
- Return
ESP_OK on success
- Parameters
handle
: Handle of the sdspi device
-
esp_err_t
sdspi_host_io_int_wait
(sdspi_dev_handle_t handle, TickType_t timeout_ticks)¶ Wait for SDIO interrupt until timeout.
- Return
ESP_OK on success
- Parameters
handle
: Handle of the sdspi devicetimeout_ticks
: Ticks to wait before timeout.
-
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.- Parameters
slot
: SPI controller to use (SPI2_HOST or SPI3_HOST)slot_config
: pointer to slot configuration structure
- 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
Structures¶
-
struct
sdspi_device_config_t
¶ Extra configuration for SD SPI device.
Public Members
-
spi_host_device_t
host_id
¶ SPI host to use, SPIx_HOST (see spi_types.h).
-
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.
-
spi_host_device_t
-
struct
sdspi_slot_config_t
¶ Extra configuration for SPI host.
Public Members
-
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.
-
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.
-
int
dma_channel
¶ DMA channel to be used by SPI driver (1 or 2).
-
gpio_num_t
Macros¶
-
SDSPI_DEFAULT_HOST
¶
-
SDSPI_HOST_DEFAULT
()¶ Default sdmmc_host_t structure initializer for SD over SPI driver.
Uses SPI mode and max frequency set to 20MHz
‘slot’ should be set to an sdspi device initialized by
sdspi_host_init_device()
.
-
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_DEVICE_CONFIG_DEFAULT
()¶ Macro defining default configuration of SD SPI device.
-
SDSPI_SLOT_CONFIG_DEFAULT
()¶ Macro defining default configuration of SPI host