SD/SDIO/MMC 驱动程序
概述
SD/SDIO/MMC 驱动支持 SD 存储器、SDIO 卡和 eMMC 芯片。这是一个协议层驱动 (sdmmc/include/sdmmc_cmd.h),可以与以下驱动配合使用:
SDSPI 主机驱动 (esp_driver_sdspi/include/driver/sdspi_host.h),详情请参阅 SD SPI Host API。
协议层与主机层
本文中的 SDMMC 协议层能处理 SD 协议的具体细节,例如卡初始化流程和各种数据传输命令流程。该协议层通过 sdmmc_host_t
结构体与主机通信。该结构体包含指向主机各种功能的指针。
主机驱动通过支持以下功能来实现协议驱动:
发送命令至从设备
接收和发送数据
处理总线错误
应用示例
storage/sd_card/sdspi 演示了如何通过 SPI 接口操作使用 FatFS 文件系统格式化的 SD 卡。
协议层 API
协议层具备 sdmmc_host_t
结构体,此结构体描述了 SD/MMC 主机驱动,列出了其功能,并提供指向驱动程序函数的指针。协议层将卡信息储存于 sdmmc_card_t
结构体中。向 SD/MMC 主机发送命令时,协议层使用 sdmmc_command_t
结构体来描述命令、参数、预期返回值和需传输的数据(如有)。
用于 SD 存储卡的 API
初始化 SDSPI 主机,请调用主机驱动函数,例如
sdspi_host_init()
和sdspi_host_init_slot()
。初始化卡,请调用
sdmmc_card_init()
,并将参数host
(主机驱动信息)和参数card
(指向sdmmc_card_t
结构体的指针)传递给此函数。函数运行结束后,将会向sdmmc_card_t
结构体填充该卡的信息。读取或写入卡的扇区,请分别调用
sdmmc_read_sectors()
和sdmmc_write_sectors()
,并将参数card
(指向卡信息结构的指针)传递给函数。如果不再使用该卡,请调用主机驱动函数,例如
sdmmc_host_deinit
或sdspi_host_deinit
,以禁用SDMMC 主机外设或 SDSPI 主机外设,并释放驱动程序分配的资源。
eMMC 芯片支持
ESP32-C2 没有 SDMMC 主机控制器,只能使用 SPI 协议与卡通信。然而,eMMC 芯片不能通过 SPI 使用。因此,无法在 ESP32-C2 上使用 eMMC 芯片。
线程安全
多数应用程序仅需在一个任务中使用协议层。因此,协议层在 sdmmc_card_t
结构体或在访问 SDMMC 或 SD SPI 主机驱动程序时不使用任何类型的锁。这种锁通常在较高层级实现,例如文件系统驱动程序。
API 参考
Header File
This header file can be included with:
#include "sdmmc_cmd.h"
This header file is a part of the API provided by the
sdmmc
component. To declare that your component depends onsdmmc
, add the following to your CMakeLists.txt:REQUIRES sdmmc
or
PRIV_REQUIRES sdmmc
Functions
-
esp_err_t sdmmc_card_init(const sdmmc_host_t *host, sdmmc_card_t *out_card)
Probe and initialize SD/MMC card using given host
- 参数
host -- pointer to structure defining host controller
out_card -- pointer to structure which will receive information about the card when the function completes
- 返回
ESP_OK on success
One of the error codes from SDMMC host controller
-
void sdmmc_card_print_info(FILE *stream, const sdmmc_card_t *card)
Print information about the card to a stream.
- 参数
stream -- stream obtained using fopen or fdopen
card -- card information structure initialized using sdmmc_card_init
-
esp_err_t sdmmc_get_status(sdmmc_card_t *card)
Get status of SD/MMC card
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
- 返回
ESP_OK on success
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_write_sectors(sdmmc_card_t *card, const void *src, size_t start_sector, size_t sector_count)
Write given number of sectors to SD/MMC card
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
src -- pointer to data buffer to read data from; data size must be equal to sector_count * card->csd.sector_size
start_sector -- sector where to start writing
sector_count -- number of sectors to write
- 返回
ESP_OK on success or sector_count equal to 0
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_read_sectors(sdmmc_card_t *card, void *dst, size_t start_sector, size_t sector_count)
Read given number of sectors from the SD/MMC card
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
dst -- pointer to data buffer to write into; buffer size must be at least sector_count * card->csd.sector_size
start_sector -- sector where to start reading
sector_count -- number of sectors to read
- 返回
ESP_OK on success or sector_count equal to 0
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_erase_sectors(sdmmc_card_t *card, size_t start_sector, size_t sector_count, sdmmc_erase_arg_t arg)
Erase given number of sectors from the SD/MMC card
备注
When sdmmc_erase_sectors used with cards in SDSPI mode, it was observed that card requires re-init after erase operation.
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
start_sector -- sector where to start erase
sector_count -- number of sectors to erase
arg -- erase command (CMD38) argument
- 返回
ESP_OK on success or sector_count equal to 0
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_can_discard(sdmmc_card_t *card)
Check if SD/MMC card supports discard
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
- 返回
ESP_OK if supported by the card/device
ESP_FAIL if not supported by the card/device
-
esp_err_t sdmmc_can_trim(sdmmc_card_t *card)
Check if SD/MMC card supports trim
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
- 返回
ESP_OK if supported by the card/device
ESP_FAIL if not supported by the card/device
-
esp_err_t sdmmc_mmc_can_sanitize(sdmmc_card_t *card)
Check if SD/MMC card supports sanitize
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
- 返回
ESP_OK if supported by the card/device
ESP_FAIL if not supported by the card/device
-
esp_err_t sdmmc_mmc_sanitize(sdmmc_card_t *card, uint32_t timeout_ms)
Sanitize the data that was unmapped by a Discard command
备注
Discard command has to precede sanitize operation. To discard, use MMC_DICARD_ARG with sdmmc_erase_sectors argument
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
timeout_ms -- timeout value in milliseconds required to sanitize the selected range of sectors.
- 返回
ESP_OK on success
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_full_erase(sdmmc_card_t *card)
Erase complete SD/MMC card
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
- 返回
ESP_OK on success
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_io_read_byte(sdmmc_card_t *card, uint32_t function, uint32_t reg, uint8_t *out_byte)
Read one byte from an SDIO card using IO_RW_DIRECT (CMD52)
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
function -- IO function number
reg -- byte address within IO function
out_byte -- [out] output, receives the value read from the card
- 返回
ESP_OK on success
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_io_write_byte(sdmmc_card_t *card, uint32_t function, uint32_t reg, uint8_t in_byte, uint8_t *out_byte)
Write one byte to an SDIO card using IO_RW_DIRECT (CMD52)
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
function -- IO function number
reg -- byte address within IO function
in_byte -- value to be written
out_byte -- [out] if not NULL, receives new byte value read from the card (read-after-write).
- 返回
ESP_OK on success
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_io_read_bytes(sdmmc_card_t *card, uint32_t function, uint32_t addr, void *dst, size_t size)
Read multiple bytes from an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs read operation using CMD53 in byte mode. For block mode, see sdmmc_io_read_blocks.
By default OP Code is set (incrementing address). To send CMD53 without this bit, OR the argument
addr
withSDMMC_IO_FIXED_ADDR
.- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
function -- IO function number
addr -- byte address within IO function where reading starts
dst -- buffer which receives the data read from card. Aligned to 4 byte boundary unless
SDMMC_HOST_FLAG_ALLOC_ALIGNED_BUF
flag is set when callingsdmmc_card_init
. The flag is mandatory when the buffer is behind the cache.size -- number of bytes to read, 1 to 512.
- 返回
ESP_OK on success
ESP_ERR_INVALID_SIZE if size exceeds 512 bytes
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_io_write_bytes(sdmmc_card_t *card, uint32_t function, uint32_t addr, const void *src, size_t size)
Write multiple bytes to an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs write operation using CMD53 in byte mode. For block mode, see sdmmc_io_write_blocks.
By default OP Code is set (incrementing address). To send CMD53 without this bit, OR the argument
addr
withSDMMC_IO_FIXED_ADDR
.- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
function -- IO function number
addr -- byte address within IO function where writing starts
src -- data to be written. Aligned to 4 byte boundary unless
SDMMC_HOST_FLAG_ALLOC_ALIGNED_BUF
flag is set when callingsdmmc_card_init
. The flag is mandatory when the buffer is behind the cache.size -- number of bytes to write, 1 to 512.
- 返回
ESP_OK on success
ESP_ERR_INVALID_SIZE if size exceeds 512 bytes
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_io_read_blocks(sdmmc_card_t *card, uint32_t function, uint32_t addr, void *dst, size_t size)
Read blocks of data from an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs read operation using CMD53 in block mode. For byte mode, see sdmmc_io_read_bytes.
By default OP Code is set (incrementing address). To send CMD53 without this bit, OR the argument
addr
withSDMMC_IO_FIXED_ADDR
.- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
function -- IO function number
addr -- byte address within IO function where writing starts
dst -- buffer which receives the data read from card. Aligned to 4 byte boundary, and also cache line size if the buffer is behind the cache.
size -- number of bytes to read, must be divisible by the card block size.
- 返回
ESP_OK on success
ESP_ERR_INVALID_SIZE if size is not divisible by 512 bytes
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_io_write_blocks(sdmmc_card_t *card, uint32_t function, uint32_t addr, const void *src, size_t size)
Write blocks of data to an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs write operation using CMD53 in block mode. For byte mode, see sdmmc_io_write_bytes.
By default OP Code is set (incrementing address). To send CMD53 without this bit, OR the argument
addr
withSDMMC_IO_FIXED_ADDR
.- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
function -- IO function number
addr -- byte address within IO function where writing starts
src -- data to be written. Aligned to 4 byte boundary, and also cache line size if the buffer is behind the cache.
size -- number of bytes to write, must be divisible by the card block size.
- 返回
ESP_OK on success
ESP_ERR_INVALID_SIZE if size is not divisible by 512 bytes
One of the error codes from SDMMC host controller
-
esp_err_t sdmmc_io_enable_int(sdmmc_card_t *card)
Enable SDIO interrupt in the SDMMC host
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
- 返回
ESP_OK on success
ESP_ERR_NOT_SUPPORTED if the host controller does not support IO interrupts
-
esp_err_t sdmmc_io_wait_int(sdmmc_card_t *card, TickType_t timeout_ticks)
Block until an SDIO interrupt is received
Slave uses D1 line to signal interrupt condition to the host. This function can be used to wait for the interrupt.
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
timeout_ticks -- time to wait for the interrupt, in RTOS ticks
- 返回
ESP_OK if the interrupt is received
ESP_ERR_NOT_SUPPORTED if the host controller does not support IO interrupts
ESP_ERR_TIMEOUT if the interrupt does not happen in timeout_ticks
-
esp_err_t sdmmc_io_get_cis_data(sdmmc_card_t *card, uint8_t *out_buffer, size_t buffer_size, size_t *inout_cis_size)
Get the data of CIS region of an SDIO card.
You may provide a buffer not sufficient to store all the CIS data. In this case, this function stores as much data into your buffer as possible. Also, this function will try to get and return the size required for you.
- 参数
card -- pointer to card information structure previously initialized using sdmmc_card_init
out_buffer -- Output buffer of the CIS data
buffer_size -- Size of the buffer.
inout_cis_size -- Mandatory, pointer to a size, input and output.
input: Limitation of maximum searching range, should be 0 or larger than buffer_size. The function searches for CIS_CODE_END until this range. Set to 0 to search infinitely.
output: The size required to store all the CIS data, if CIS_CODE_END is found.
- 返回
ESP_OK: on success
ESP_ERR_INVALID_RESPONSE: if the card does not (correctly) support CIS.
ESP_ERR_INVALID_SIZE: CIS_CODE_END found, but buffer_size is less than required size, which is stored in the inout_cis_size then.
ESP_ERR_NOT_FOUND: if the CIS_CODE_END not found. Increase input value of inout_cis_size or set it to 0, if you still want to search for the end; output value of inout_cis_size is invalid in this case.
and other error code return from sdmmc_io_read_bytes
-
esp_err_t sdmmc_io_print_cis_info(uint8_t *buffer, size_t buffer_size, FILE *fp)
Parse and print the CIS information of an SDIO card.
备注
Not all the CIS codes and all kinds of tuples are supported. If you see some unresolved code, you can add the parsing of these code in sdmmc_io.c and contribute to the IDF through the Github repository.
using sdmmc_card_init
- 参数
buffer -- Buffer to parse
buffer_size -- Size of the buffer.
fp -- File pointer to print to, set to NULL to print to stdout.
- 返回
ESP_OK: on success
ESP_ERR_NOT_SUPPORTED: if the value from the card is not supported to be parsed.
ESP_ERR_INVALID_SIZE: if the CIS size fields are not correct.
Macros
-
SDMMC_IO_FIXED_ADDR
Call
sdmmc_io_read_bytes
,sdmmc_io_write_bytes
,sdmmc_io_read_blocks
orsdmmc_io_write_bocks
APIs with address ORed by this flag to send CMD53 with OP Code clear (fixed address)
Header File
This header file can be included with:
#include "driver/sdmmc_types.h"
This header file is a part of the API provided by the
esp_driver_sdmmc
component. To declare that your component depends onesp_driver_sdmmc
, add the following to your CMakeLists.txt:REQUIRES esp_driver_sdmmc
or
PRIV_REQUIRES esp_driver_sdmmc