# SD/SDIO/MMC 驱动程序

[English]

## 概述

SD/SDIO/MMC 驱动支持 SD 存储器、SDIO 卡和 eMMC 芯片。这是一个协议层驱动 (sdmmc/include/sdmmc_cmd.h)，可以与以下驱动配合使用：

- SDMMC 主机驱动 (esp_driver_sdmmc/legacy/include/driver/sdmmc_host.h)，详情请参阅 SDMMC Host API。

- SDSPI 主机驱动 (esp_driver_sdspi/include/driver/sdspi_host.h)，详情请参阅 SD SPI Host API。

### 协议层与主机层

本文中的 SDMMC 协议层能处理 SD 协议的具体细节，例如卡初始化流程和各种数据传输命令流程。该协议层通过 `sdmmc_host_t` 结构体与主机通信。该结构体包含指向主机各种功能的指针。

主机驱动通过支持以下功能来实现协议驱动：

- 发送命令至从设备

- 接收和发送数据

- 处理总线错误

SD 主机端组件架构

## 应用示例

- storage/sd_card/sdmmc 演示了如何通过 SDMMC 接口操作使用 FatFS 文件系统格式化的 SD 卡。

- storage/emmc 演示了如何通过 SDMMC 接口操作使用 FatFS 文件系统格式化的 eMMC 芯片。

- storage/sd_card/sdspi 演示了如何通过 SPI 接口操作使用 FatFS 文件系统格式化的 SD 卡。

## 协议层 API

协议层具备 `sdmmc_host_t` 结构体，此结构体描述了 SD/MMC 主机驱动，列出了其功能，并提供指向驱动程序函数的指针。协议层将卡信息储存于 `sdmmc_card_t` 结构体中。向 SD/MMC 主机发送命令时，协议层使用 `sdmmc_command_t` 结构体来描述命令、参数、预期返回值和需传输的数据（如有）。

### 用于 SD 存储卡的 API

- 初始化 SDMMC 主机，请调用主机驱动函数，例如 `sdmmc_host_init()` 和 `sdmmc_host_init_slot()`。

- 初始化 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 芯片的 API

从协议层的角度而言，eMMC 存储芯片与 SD 存储卡相同。尽管 eMMC 是芯片，不具备卡的外形，但由于协议相似 (sdmmc_card_t, sdmmc_card_init)，用于 SD 卡的一些概念同样适用于 eMMC 芯片。注意，eMMC 芯片不可通过 SPI 使用，因此它与 SD SPI 主机驱动不兼容。

如需初始化 eMMC 内存并执行读/写操作，请参照上一章节 SD 卡操作步骤。

### 用于 SDIO 卡的 API

SDIO 卡初始化和检测过程与 SD 存储卡相同，唯一的区别是 SDIO 模式下数据传输命令不同。

在卡初始化和卡检测（通过运行 `sdmmc_card_init()`）期间，驱动仅配置 IO 卡如下寄存器：

1. I/O 中止 (0x06) 寄存器：在该寄存器中设置 RES 位可重置卡的 IO 部分；

2. 总线接口控制 (0x07) 寄存器：如果主机和插槽配置中启用 4 线模式，则驱动程序会尝试在该寄存器中设置总线宽度字段。如果字段设置成功，则从机支持 4 线模式，主机也切换至 4 线模式；

3. 高速 (0x13) 寄存器：如果主机配置中启用高速模式，则该寄存器的 SHS 位会被设置。

注意，驱动程序不会在 (1) I/O 使能寄存器和 Int 使能寄存器，及 (2) I/O 块大小中，设置任何位。应用程序可通过调用 `sdmmc_io_write_byte()` 来设置相关位。

如需卡配置或传输数据，请根据具体情况，选择下表函数：

操作 | 函数读取 | 函数写入
--- | --- | ---
使用 IO_RW_DIRECT (CMD52) 读写单个字节 | `sdmmc_io_read_byte()` | `sdmmc_io_write_byte()`
使用 IO_RW_EXTENDED (CMD53) 的字节模式读写多个字节 | `sdmmc_io_read_bytes()` | `sdmmc_io_write_bytes()`
块模式下，使用 IO_RW_EXTENDED (CMD53) 读写数据块 | `sdmmc_io_read_blocks()` | `sdmmc_io_write_blocks()`

使用 `sdmmc_io_enable_int()` 函数，应用程序可启用 SDIO 中断。在单线模式下使用 SDIO 时，还需要连接 D1 线来启用 SDIO 中断。

如果需要应用程序保持等待直至发生 SDIO 中断，请使用 `sdmmc_io_wait_int()` 函数。

如果需要与 ESP32 的 SDIO 从设备通信，请使用 ESSL 组件（ESP 串行从设备链接）。请参阅示例 peripherals/sdio/host。

### 复合卡（存储 + IO）

该驱动程序不支持 SD 复合卡，复合卡会被视为 IO 卡。

### 线程安全

多数应用程序仅需在一个任务中使用协议层。因此，协议层在 `sdmmc_card_t` 结构体或在访问 SDMMC 或 SD SPI 主机驱动程序时不使用任何类型的锁。这种锁通常在较高层级实现，例如文件系统驱动程序。

## API 参考

### Header File

- components/sdmmc/include/sdmmc_cmd.h

- 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 on `sdmmc`, 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` with `SDMMC_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 calling `sdmmc_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` with `SDMMC_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 calling `sdmmc_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` with `SDMMC_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` with `SDMMC_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, uint32_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.

esp_err_t sdmmc_get_blockdev(sdmmc_card_t *card, esp_blockdev_handle_t *out_handle)

  Get a block device handle for the SD/MMC card

  This function allocates a block device handle and initializes it with the card information.

  参数:

    - card -- [in] Pointer to card information structure previously initialized using sdmmc_card_init.

    - out_handle -- [inout] Pointer to variable which will receive the block device handle.

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if card or out_handle is NULL

    - ESP_ERR_NO_MEM if memory allocation fails

### Macros

SDMMC_IO_FIXED_ADDR

  Call `sdmmc_io_read_bytes`, `sdmmc_io_write_bytes`, `sdmmc_io_read_blocks` or `sdmmc_io_write_bocks` APIs with address ORed by this flag to send CMD53 with OP Code clear (fixed address)

### Header File

- components/sdmmc/include/sd_protocol_types.h

- This header file can be included with:

  >     #include "sd_protocol_types.h"

- This header file is a part of the API provided by the `sdmmc` component. To declare that your component depends on `sdmmc`, add the following to your CMakeLists.txt:

  >     REQUIRES sdmmc

  > or

  >     PRIV_REQUIRES sdmmc

### Structures

struct sdmmc_csd_t

  Decoded values from SD card Card Specific Data register

  Public Members

  int csd_ver

    CSD structure format

  int mmc_ver

    MMC version (for CID format)

  int capacity

    total number of sectors

  int sector_size

    sector size in bytes

  int read_block_len

    block length for reads

  int card_command_class

    Card Command Class for SD

  int tr_speed

    Max transfer speed

struct sdmmc_cid_t

  Decoded values from SD card Card IDentification register

  Public Members

  int mfg_id

    manufacturer identification number

  int oem_id

    OEM/product identification number

  char name[8]

    product name (MMC v1 has the longest)

  int revision

    product revision

  int serial

    product serial number

  int date

    manufacturing date

struct sdmmc_scr_t

  Decoded values from SD Configuration Register Note: When new member is added, update reserved bits accordingly

  Public Members

  uint32_t sd_spec

    SD Physical layer specification version, reported by card

  uint32_t erase_mem_state

    data state on card after erase whether 0 or 1 (card vendor dependent)

  uint32_t bus_width

    bus widths supported by card: BIT(0) — 1-bit bus, BIT(2) — 4-bit bus

  uint32_t reserved

    reserved for future expansion

  uint32_t rsvd_mnf

    reserved for manufacturer usage

struct sdmmc_ssr_t

  Decoded values from SD Status Register Note: When new member is added, update reserved bits accordingly

  Public Members

  uint32_t alloc_unit_kb

    Allocation unit of the card, in multiples of kB (1024 bytes)

  uint32_t erase_size_au

    Erase size for the purpose of timeout calculation, in multiples of allocation unit

  uint32_t cur_bus_width

    SD current bus width

  uint32_t discard_support

    SD discard feature support

  uint32_t fule_support

    SD FILE (Full User Area Logical Erase) feature support

  uint32_t erase_timeout

    Timeout (in seconds) for erase of a single allocation unit

  uint32_t erase_offset

    Constant timeout offset (in seconds) for any erase operation

  uint32_t reserved

    reserved for future expansion

struct sdmmc_ext_csd_t

  Decoded values of Extended Card Specific Data

  Public Members

  uint8_t rev

    Extended CSD Revision

  uint8_t power_class

    Power class used by the card

  uint8_t erase_mem_state

    data state on card after erase whether 0 or 1 (card vendor dependent)

  uint8_t sec_feature

    secure data management features supported by the card

struct sdmmc_switch_func_rsp_t

  SD SWITCH_FUNC response buffer

  Public Members

  uint32_t data[512 / 8 / sizeof(uint32_t)]

    response data

struct sdmmc_command_t

  SD/MMC command information

  Public Members

  uint32_t opcode

    SD or MMC command index

  uint32_t arg

    SD/MMC command argument

  sdmmc_response_t response

    response buffer

  void *data

    buffer to send or read into

  size_t datalen

    length of data in the buffer

  size_t buflen

    length of the buffer

  size_t blklen

    block length

  int flags

    see below

  esp_err_t error

    error returned from transfer

  uint32_t timeout_ms

    response timeout, in milliseconds

  esp_err_t (*volt_switch_cb)(void*, int)

    callback to be called during CMD11 to switch voltage

  void *volt_switch_cb_arg

    argument to be passed to the CMD11 callback

struct sdmmc_host_t

  SD/MMC Host description

  This structure defines properties of SD/MMC host and functions of SD/MMC host which can be used by upper layers.

  Public Members

  uint32_t flags

    flags defining host properties

  int slot

    slot number, to be passed to host functions

  int max_freq_khz

    max frequency supported by the host

  float io_voltage

    I/O voltage used by the controller (voltage switching is not supported)

  sdmmc_driver_strength_t driver_strength

    Driver Strength

  sdmmc_current_limit_t current_limit

    Current Limit

  esp_err_t (*init)(void)

    Host function to initialize the driver

  esp_err_t (*set_bus_width)(int slot, size_t width)

    host function to set bus width

  size_t (*get_bus_width)(int slot)

    host function to get bus width

  esp_err_t (*set_bus_ddr_mode)(int slot, bool ddr_enable)

    host function to set DDR mode

  esp_err_t (*set_card_clk)(int slot, uint32_t freq_khz)

    host function to set card clock frequency

  esp_err_t (*set_cclk_always_on)(int slot, bool cclk_always_on)

    host function to set whether the clock is always enabled

  esp_err_t (*do_transaction)(int slot, sdmmc_command_t *cmdinfo)

    host function to do a transaction

  esp_err_t (*deinit)(void)

    host function to deinitialize the driver

  esp_err_t (*deinit_p)(int slot)

    host function to deinitialize the driver, called with the `slot`

  esp_err_t (*io_int_enable)(int slot)

    Host function to enable SDIO interrupt line

  esp_err_t (*io_int_wait)(int slot, uint32_t timeout_ticks)

    Host function to wait for SDIO interrupt line to be active

  int command_timeout_ms

    timeout, in milliseconds, of a single command. Set to 0 to use the default value.

  esp_err_t (*get_real_freq)(int slot, int *real_freq)

    Host function to provide real working freq, based on SDMMC controller setup

  sdmmc_delay_phase_t input_delay_phase

    input delay phase, this will only take into effect when the host works in SDMMC_FREQ_HIGHSPEED or SDMMC_FREQ_52M. Driver will print out how long the delay is

  esp_err_t (*set_input_delay)(int slot, sdmmc_delay_phase_t delay_phase)

    set input delay phase

  esp_err_t (*set_input_delayline)(int slot, sdmmc_delay_line_t delay_line)

    set input delay line

  void *dma_aligned_buffer

    Leave it NULL. Reserved for cache aligned buffers for SDIO mode

  sd_pwr_ctrl_handle_t pwr_ctrl_handle

    Power control handle

  bool (*check_buffer_alignment)(int slot, const void *buf, size_t size)

    Check if buffer meets alignment requirements

  esp_err_t (*is_slot_set_to_uhs1)(int slot, bool *is_uhs1)

    host slot is set to uhs1 or not

struct sdmmc_card_t

  SD/MMC card information structure

  Public Members

  sdmmc_host_t host

    Host with which the card is associated

  uint32_t ocr

    OCR (Operation Conditions Register) value

  sdmmc_cid_t cid

    decoded CID (Card IDentification) register value

  sdmmc_response_t raw_cid

    raw CID of MMC card to be decoded after the CSD is fetched in the data transfer mode

  sdmmc_csd_t csd

    decoded CSD (Card-Specific Data) register value

  sdmmc_scr_t scr

    decoded SCR (SD card Configuration Register) value

  sdmmc_ssr_t ssr

    decoded SSR (SD Status Register) value

  sdmmc_ext_csd_t ext_csd

    decoded EXT_CSD (Extended Card Specific Data) register value

  uint16_t rca

    RCA (Relative Card Address)

  uint32_t max_freq_khz

    Maximum frequency, in kHz, supported by the card

  int real_freq_khz

    Real working frequency, in kHz, configured on the host controller

  uint32_t is_mem

    Bit indicates if the card is a memory card

  uint32_t is_sdio

    Bit indicates if the card is an IO card

  uint32_t is_mmc

    Bit indicates if the card is MMC

  uint32_t num_io_functions

    If is_sdio is 1, contains the number of IO functions on the card

  uint32_t log_bus_width

    log2(bus width supported by card)

  uint32_t is_ddr

    Card supports DDR mode

  uint32_t is_uhs1

    Card supports UHS-1 mode

  uint32_t reserved

    Reserved for future expansion

### Macros

SDMMC_HOST_FLAG_1BIT

  host supports 1-line SD and MMC protocol

SDMMC_HOST_FLAG_4BIT

  host supports 4-line SD and MMC protocol

SDMMC_HOST_FLAG_8BIT

  host supports 8-line MMC protocol

SDMMC_HOST_FLAG_SPI

  host supports SPI protocol

SDMMC_HOST_FLAG_DDR

  host supports DDR mode for SD/MMC

SDMMC_HOST_FLAG_DEINIT_ARG

  host `deinit` function called with the slot argument

SDMMC_HOST_FLAG_ALLOC_ALIGNED_BUF

  Allocate internal buffer of 512 bytes that meets DMA's requirements. Currently this is only used by the SDIO driver. Set this flag when using SDIO CMD53 byte mode, with user buffer that is behind the cache or not aligned to 4 byte boundary.

SDMMC_FREQ_DEFAULT

  SD/MMC Default speed (limited by clock divider)

SDMMC_FREQ_HIGHSPEED

  SD High speed (limited by clock divider)

SDMMC_FREQ_PROBING

  SD/MMC probing speed

SDMMC_FREQ_52M

  MMC 52MHz speed

SDMMC_FREQ_26M

  MMC 26MHz speed

SDMMC_FREQ_DDR50

  MMC 50MHz speed

SDMMC_FREQ_SDR50

  MMC 100MHz speed

SDMMC_FREQ_SDR104

  MMC 200MHz speed

### Type Definitions

typedef uint32_t sdmmc_response_t[4]

  SD/MMC command response buffer

### Enumerations

enum sdmmc_driver_strength_t

  SD/MMC Driver Strength.

  Values:

  enumerator SDMMC_DRIVER_STRENGTH_B

    Type B

  enumerator SDMMC_DRIVER_STRENGTH_A

    Type A

  enumerator SDMMC_DRIVER_STRENGTH_C

    Type C

  enumerator SDMMC_DRIVER_STRENGTH_D

    Type D

enum sdmmc_current_limit_t

  SD/MMC Current Limit.

  Values:

  enumerator SDMMC_CURRENT_LIMIT_200MA

    200 mA

  enumerator SDMMC_CURRENT_LIMIT_400MA

    400 mA

  enumerator SDMMC_CURRENT_LIMIT_600MA

    600 mA

  enumerator SDMMC_CURRENT_LIMIT_800MA

    800 mA

enum sdmmc_erase_arg_t

  SD/MMC erase command(38) arguments SD: ERASE: Erase the write blocks, physical/hard erase.

  DISCARD: Card may deallocate the discarded blocks partially or completely. After discard operation the previously written data may be partially or fully read by the host depending on card implementation.

  MMC: ERASE: Does TRIM, applies erase operation to write blocks instead of Erase Group.

  DISCARD: The Discard function allows the host to identify data that is no longer required so that the device can erase the data if necessary during background erase events. Applies to write blocks instead of Erase Group After discard operation, the original data may be remained partially or fully accessible to the host dependent on device.

  Values:

  enumerator SDMMC_ERASE_ARG

    Erase operation on SD, Trim operation on MMC

  enumerator SDMMC_DISCARD_ARG

    Discard operation for SD/MMC

### Header File

- components/esp_driver_sdmmc/legacy/include/driver/sdmmc_types.h

- 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 on `esp_driver_sdmmc`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_sdmmc

  > or

  >     PRIV_REQUIRES esp_driver_sdmmc

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。