SD SPI 主机驱动程序
概述
SD SPI 主机驱动程序支持使用 SPI 主控驱动程序与一或多张 SD 卡通信，SPI 主控驱动程序则利用 SPI 主机实现功能。每张 SD 卡都通过一个 SD SPI 设备访问，相应设备以 SD SPI 设备句柄 sdspi_dev_handle_t 表示。调用 sdspi_host_init_device() 将设备连接到 SPI 总线上时会返回所需 SPI 设备句柄。注意，在使用 SPI 总线前，需要先通过 spi_bus_initialize() 初始化总线。
SD SPI 主机驱动程序基于 SPI 主机驱动程序 实现。借助 SPI 主控驱动程序，SD 卡及其他 SPI 设备可以共享同一 SPI 总线。SPI 主机驱动程序将处理来自不同任务的独占访问。
SD SPI 驱动程序使用受软件控制的 CS 信号。
使用方法
首先，使用宏 SDSPI_DEVICE_CONFIG_DEFAULT 初始化结构体 sdspi_device_config_t，该结构体用于初始化 SD SPI 设备。该宏还会填充默认的管脚映射，与 SDMMC 主机驱动的管脚映射相同。随后根据需要，修改结构体中的主机和管脚配置。然后调用 sdspi_host_init_device 初始化 SD SPI 设备，并将其连接到所属的总线上。
接着，使用宏 SDSPI_HOST_DEFAULT 初始化结构体 sdmmc_host_t，该结构体用于存储上层（SD/SDIO/MMC 驱动）的状态和配置信息。将结构体中的 slot 参数设置为从 sdspi_host_init_device 返回的 SD SPI 设备的 SD SPI 句柄。使用 sdmmc_host_t 调用 sdmmc_card_init，检测并初始化 SD 卡。
初始化完成后，即可使用 SD/SDIO/MMC 驱动函数访问 SD 卡。
其他细节
通常，大多数应用程序仅使用驱动程序的以下 API 函数：
对于其他函数，大多由协议层的 SD/SDIO/MMC 驱动程序通过 sdmmc_host_t 结构体中的函数指针使用。更多详情，请参阅 SD/SDIO/MMC 驱动程序。
备注
由于 SPI 驱动程序的限制，SD 卡在通过 SPI 总线与主设备进行数据传输和通信时，速度不超过 SDMMC_FREQ_DEFAULT。
警告
在 SD 卡之间以及其他 SPI 设备间共享 SPI 总线时，存在部分限制，详情请参阅 SD 卡与其他 SPI 设备共享 SPI 总线。
相关文档
API 参考
Header File
This header file can be included with:
#include "driver/sdspi_host.h"
This header file is a part of the API provided by the
esp_driver_sdspicomponent. To declare that your component depends onesp_driver_sdspi, add the following to your CMakeLists.txt:REQUIRES esp_driver_sdspi
or
PRIV_REQUIRES esp_driver_sdspi
Functions
-
esp_err_t sdspi_host_init(void)
Initialize SD SPI driver.
备注
This function is not thread safe
- 返回
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.
备注
This function is not thread safe
备注
Initialize the SPI bus by
spi_bus_initialize()before calling this function.备注
The SDIO over sdspi needs an extra interrupt line. Call
gpio_install_isr_service()before this function.- 参数
dev_config -- pointer to device configuration structure
out_handle -- Output of the handle to the sdspi device.
- 返回
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
-
esp_err_t sdspi_host_remove_device(sdspi_dev_handle_t handle)
Remove an SD SPI device.
- 参数
handle -- Handle of the SD SPI device
- 返回
Always ESP_OK
-
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.
备注
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.
- 参数
handle -- Handle of the sdspi device
cmdinfo -- pointer to structure describing command and data to transfer
- 返回
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_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.
备注
This function is not thread safe
- 参数
host -- Handle of the sdspi device
freq_khz -- card clock frequency, in kHz
- 返回
ESP_OK on success
other error codes may be returned in the future
-
esp_err_t sdspi_host_get_real_freq(sdspi_dev_handle_t handle, int *real_freq_khz)
Calculate working frequency for specific device.
- 参数
handle -- SDSPI device handle
real_freq_khz -- [out] output parameter to hold the calculated frequency (in kHz)
- 返回
ESP_ERR_INVALID_ARG :
handleis NULL or invalid orreal_freq_khzparameter is NULLESP_OK : Success
-
esp_err_t sdspi_host_deinit(void)
Release resources allocated using sdspi_host_init.
备注
This function is not thread safe
- 返回
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.
- 参数
handle -- Handle of the sdspi device
- 返回
ESP_OK on success
-
esp_err_t sdspi_host_io_int_wait(sdspi_dev_handle_t handle, TickType_t timeout_ticks)
Wait for SDIO interrupt until timeout.
- 参数
handle -- Handle of the sdspi device
timeout_ticks -- Ticks to wait before timeout.
- 返回
ESP_OK on success
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.
-
bool gpio_wp_polarity
GPIO write protect polarity 0 means "active low", i.e. card is protected when the GPIO is low; 1 means "active high", i.e. card is protected when GPIO is high.
-
uint16_t duty_cycle_pos
Duty cycle of positive clock, in 1/256th increments (128 = 50%/50% duty). Setting this to 0 (=not setting it) is equivalent to setting this to 128.
-
spi_host_device_t host_id
Macros
-
SDSPI_DEFAULT_HOST
-
SDSPI_DEFAULT_DMA
-
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_CS
indicates that card select line is not used
-
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_IO_ACTIVE_LOW
-
SDSPI_DEVICE_CONFIG_DEFAULT()
Macro defining default configuration of SD SPI device.
Type Definitions
-
typedef int sdspi_dev_handle_t
Handle representing an SD SPI device.