MMC Driver¶

Overview¶

SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This protocol level driver builds on top of SDMMC and SD SPI host drivers.

SDMMC and SD SPI host drivers (driver/sdmmc_host.h) provide APIs to send commands to the slave device(s), send and receive data, and handle error conditions on the bus.

See SDMMC Host API for functions used to initialize and configure SDMMC host.
See SD SPI Host API for functions used to initialize and configure SD SPI host.

SDMMC protocol layer (sdmmc_cmd.h), described in this document, handles specifics of SD protocol such as card initialization and data transfer commands.

Protocol layer works with the host via sdmmc_host_t structure. This structure contains pointers to various functions of the host.

Application Example¶

An example which combines SDMMC driver with FATFS library is provided in examples/storage/sd_card directory. This example initializes the card, writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.

Protocol layer APIs¶

Protocol layer is given sdmmc_host_t structure which describes the SD/MMC host driver, lists its capabilites, and provides pointers to functions of the driver. Protocol layer stores card-specific information in sdmmc_card_t structure. When sending commands to the SD/MMC host driver, protocol layer uses sdmmc_command_t structure to describe the command, argument, expected return value, and data to transfer, if any.

Usage with SD memory cards¶

Call the host driver functions to initialize the host (e.g. sdmmc_host_init(), sdmmc_host_init_slot()).
Call sdmmc_card_init() to initialize the card, passing it host driver information (host) and a pointer to sdmmc_card_t structure which will be filled in (card).
To read and write sectors of the card, use sdmmc_read_sectors() and sdmmc_write_sectors(), passing the pointer to card information structure (card).
When card is not used anymore, call the host driver function to disable the host peripheral and free resources allocated by the driver (e.g. sdmmc_host_deinit()).

Usage with eMMC chips¶

From the perspective of the protocol layer, eMMC memory chips behave the same way as SD memory cards. Because of similarity of the protocol, even though eMMC are chips don’t have the “card” form factor, same terminology is used as for SD cards (sdmmc_card_t, sdmmc_card_init). Note that eMMC chips can not be used over SPI, therefore are incompatible with SD SPI host driver.

To initialize eMMC memory and do read/write operations, follow the steps listed above for SD cards.

Usage with SDIO cards¶

Initialization an probing process is the same as with SD memory cards. Only data transfer commands differ in SDIO mode.

During probing and card initialization (done by sdmmc_card_init()), the driver only configures the following registers of the IO card:

The IO portion of the card is reset by setting RES bit in “I/O Abort” (0x06) register.
If 4-line mode is enalbed in host and slot configuration, driver attempts to set “Bus width” field in “Bus Interface Control” (0x07) register. If that succeeds (which means that slave supports 4-line mode), host is also switched to 4-line mode.
If high-speed mode is enabled in host configuration, SHS bit is set in “High Speed” (0x13) register.

In particular, the driver does not set any of the bits in I/O Enable, Int Enable registers, IO block sizes, etc. Applications can set these by calling sdmmc_io_write_byte().

For card configuration and data transfer, use one of the following functions:

sdmmc_io_read_byte(), sdmmc_io_write_byte() — read and write single byte using IO_RW_DIRECT (CMD52).
sdmmc_io_read_bytes(), sdmmc_io_write_bytes() — read and write multiple bytes using IO_RW_EXTENDED (CMD53), in byte mode.
sdmmc_io_read_blocks(), sdmmc_io_write_blocks() — read and write blocks of data using IO_RW_EXTENDED (CMD53), in block mode.

SDIO interrupts can be enabled by the application using sdmmc_io_enable_int() function. When using SDIO in 1-line mode, D1 line also needs to be connected to use SDIO interrupts.

The application can wait for SDIO interrupt to occur using sdmmc_io_wait_int().

Combo (memory + IO) cards¶

The driver does not support SD combo cards. Combo cards will be treated as IO cards.

Thread safety¶

Most applications need to use the protocol layer only in one task; therefore the protocol layer doesn’t implement any kind of locking on the sdmmc_card_t structure, or when accessing SDMMC or SD SPI host drivers. Such locking is usually implemented in the higher layer (e.g. in the filesystem driver).

API Reference¶

Header File¶

sdmmc/include/sdmmc_cmd.h

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

Note

Only SD cards (SDSC and SDHC/SDXC) are supported now. Support for MMC/eMMC cards will be added later.

Return

ESP_OK on success
One of the error codes from SDMMC host controller

Parameters

host: pointer to structure defining host controller
out_card: pointer to structure which will receive information about the card when the function completes

void sdmmc_card_print_info(FILE *stream, const sdmmc_card_t *card)¶

Print information about the card to a stream.

Parameters

stream: stream obtained using fopen or fdopen
card: card information structure initialized using sdmmc_card_init

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

Return

ESP_OK on success
One of the error codes from SDMMC host controller

Parameters

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_err_t sdmmc_read_sectors(sdmmc_card_t *card, void *dst, size_t start_sector, size_t sector_count)¶

Write given number of sectors to SD/MMC card

Return

ESP_OK on success
One of the error codes from SDMMC host controller

Parameters

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_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)

Return

ESP_OK on success
One of the error codes from SDMMC host controller

Parameters

card: pointer to card information structure previously initialized using sdmmc_card_init
function: IO function number
reg: byte address within IO function
[out] out_byte: output, receives the value read from the card

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)

Return

ESP_OK on success
One of the error codes from SDMMC host controller

Parameters

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] out_byte: if not NULL, receives new byte value read from the card (read-after-write).

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.

Return

ESP_OK on success
ESP_ERR_INVALID_SIZE if size exceeds 512 bytes
One of the error codes from SDMMC host controller

Parameters

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
size: number of bytes to read

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.

Return

ESP_OK on success
ESP_ERR_INVALID_SIZE if size exceeds 512 bytes
One of the error codes from SDMMC host controller

Parameters

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
size: number of bytes to write

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.

Return

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

Parameters

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
size: number of bytes to read, must be divisible by the card block size.

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.

Return

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

Parameters

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
size: number of bytes to read, must be divisible by the card block size.

esp_err_t sdmmc_io_enable_int(sdmmc_card_t *card)¶

Enable SDIO interrupt in the SDMMC host

Return

ESP_OK on success
ESP_ERR_NOT_SUPPORTED if the host controller does not support IO interrupts

Parameters

card: pointer to card information structure previously initialized using sdmmc_card_init

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.

Return

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

Parameters

card: pointer to card information structure previously initialized using sdmmc_card_init
timeout_ticks: time to wait for the interrupt, in RTOS ticks

Header File¶

driver/include/driver/sdmmc_types.h

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

Public Members

int sd_spec¶: SD Physical layer specification version, reported by card

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

struct sdmmc_ext_csd_t¶

Decoded values of Extended Card Specific Data

Public Members

uint8_t power_class¶: Power class used 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 buffer

size_t blklen¶: block length

int flags¶: see below

esp_err_t error¶: error returned from transfer

int timeout_ms¶: response timeout, in milliseconds

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)

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 (*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 (*io_int_enable)(int slot)¶: Host function to enable SDIO interrupt line

esp_err_t (*io_int_wait)(int slot, TickType_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.

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_csd_t csd¶: decoded CSD (Card-Specific Data) register value

sdmmc_scr_t scr¶: decoded SCR (SD card Configuration Register) value

sdmmc_ext_csd_t ext_csd¶: decoded EXT_CSD (Extended Card Specific Data) register value

uint16_t rca¶: RCA (Relative Card Address)

uint16_t max_freq_khz¶: Maximum frequency, in kHz, supported by the card

uint32_t is_mem : 1¶: Bit indicates if the card is a memory card

uint32_t is_sdio : 1¶: Bit indicates if the card is an IO card

uint32_t is_mmc : 1¶: Bit indicates if the card is MMC

uint32_t num_io_functions : 3¶: If is_sdio is 1, contains the number of IO functions on the card

uint32_t log_bus_width : 2¶: log2(bus width supported by card)

uint32_t is_ddr : 1¶: Card supports DDR mode

uint32_t reserved : 23¶: 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_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

Type Definitions¶

typedef uint32_t sdmmc_response_t[4]¶: SD/MMC command response buffer