SDMMC Host Peripheral

Overview

SDMMC peripheral supports SD and MMC memory cards and SDIO cards. SDMMC software builds on top of SDMMC driver and consists of the following parts:

  1. SDMMC host driver (driver/sdmmc_host.h) — this driver provides APIs to send commands to the slave device(s), send and receive data, and handling error conditions on the bus.
  2. SDMMC protocol layer (sdmmc_cmd.h) — this component handles specifics of SD protocol such as card initialization and data transfer commands. Despite the name, only SD (SDSC/SDHC/SDXC) cards are supported at the moment. Support for MCC/eMMC cards can be added in the future.

Protocol layer works with the host via sdmmc_host_t structure. This structure contains pointers to various functions of the host. This design makes it possible to implement an SD host using SPI interface later.

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.

Normal usage of the protocol layer is as follows:

  1. Call the host driver functions to initialize the host (e.g. sdmmc_host_init, sdmmc_host_init_slot).
  2. 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).
  3. To read and write sectors of the card, use sdmmc_read_sectors and sdmmc_write_sectors, passing the pointer to card information structure (card).
  4. When card is not used anymore, call the host driver function to disable SDMMC host peripheral and free resources allocated by the driver (e.g. sdmmc_host_deinit).

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 host driver. Such locking has to be implemented in the higher layer, if necessary (e.g. in the filesystem driver).

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

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

SDMMC_HOST_FLAG_1BIT BIT(0)

host supports 1-line SD and MMC protocol

SDMMC_HOST_FLAG_4BIT BIT(1)

host supports 4-line SD and MMC protocol

SDMMC_HOST_FLAG_8BIT BIT(2)

host supports 8-line MMC protocol

SDMMC_HOST_FLAG_SPI BIT(3)

host supports SPI protocol

SDMMC_FREQ_DEFAULT 20000

SD/MMC Default speed (limited by clock divider)

SDMMC_FREQ_HIGHSPEED 40000

SD High speed (limited by clock divider)

SDMMC_FREQ_PROBING 4000

SD/MMC probing speed

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

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

uint16_t rca

RCA (Relative Card Address)

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

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

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

SDMMC host driver APIs

On the ESP32, SDMMC host peripheral has two slots:

  • Slot 0 (SDMMC_HOST_SLOT_0) is an 8-bit slot. It uses HS1_* signals in the PIN MUX.
  • Slot 1 (SDMMC_HOST_SLOT_1) is a 4-bit slot. It uses HS2_* signals in the PIN MUX.

Card Detect and Write Protect signals can be routed to arbitrary pins using GPIO matrix. To use these pins, set gpio_cd and gpio_wp members of sdmmc_slot_config_t structure when calling sdmmc_host_init_slot.

Of all the funtions listed below, only sdmmc_host_init, sdmmc_host_init_slot, and sdmmc_host_deinit will be used directly by most applications. Other functions, such as sdmmc_host_set_bus_width, sdmmc_host_set_card_clk, and sdmmc_host_do_transaction will be called by the SD/MMC protocol layer via function pointers in sdmmc_host_t structure.

esp_err_t sdmmc_host_init()

Initialize SDMMC host peripheral.

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_STATE if sdmmc_host_init was already called
  • ESP_ERR_NO_MEM if memory can not be allocated

SDMMC_HOST_SLOT_0 0

SDMMC slot 0.

SDMMC_HOST_SLOT_1 1

SDMMC slot 1.

SDMMC_HOST_DEFAULT {\ .flags = SDMMC_HOST_FLAG_4BIT, \ .slot = SDMMC_HOST_SLOT_1, \ .max_freq_khz = SDMMC_FREQ_DEFAULT, \ .io_voltage = 3.3f, \ .init = &sdmmc_host_init, \ .set_bus_width = &sdmmc_host_set_bus_width, \ .set_card_clk = &sdmmc_host_set_card_clk, \ .do_transaction = &sdmmc_host_do_transaction, \ .deinit = &sdmmc_host_deinit, \ }

Default sdmmc_host_t structure initializer for SDMMC peripheral.

Uses SDMMC peripheral, with 4-bit mode enabled, and max frequency set to 20MHz

SDMMC_SLOT_WIDTH_DEFAULT 0

use the default width for the slot (8 for slot 0, 4 for slot 1)

esp_err_t sdmmc_host_init_slot(int slot, const sdmmc_slot_config_t *slot_config)

Initialize given slot of SDMMC peripheral.

On the ESP32, SDMMC peripheral has two slots:

  • Slot 0: 8-bit wide, maps to HS1_* signals in PIN MUX
  • Slot 1: 4-bit wide, maps to HS2_* signals in PIN MUX

Card detect and write protect signals can be routed to arbitrary GPIOs using GPIO matrix.

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_STATE if host has not been initialized using sdmmc_host_init
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • slot_config: additional configuration for the slot

struct sdmmc_slot_config_t

Extra configuration for SDMMC peripheral slot

Public Members

gpio_num_t gpio_cd

GPIO number of card detect signal.

gpio_num_t gpio_wp

GPIO number of write protect signal.

uint8_t width

Bus width used by the slot (might be less than the max width supported)

SDMMC_SLOT_NO_CD ((gpio_num_t) -1)

indicates that card detect line is not used

SDMMC_SLOT_NO_WP ((gpio_num_t) -1)

indicates that write protect line is not used

SDMMC_SLOT_CONFIG_DEFAULT {\ .gpio_cd = SDMMC_SLOT_NO_CD, \ .gpio_wp = SDMMC_SLOT_NO_WP, \ .width = SDMMC_SLOT_WIDTH_DEFAULT, \ }

Macro defining default configuration of SDMMC host slot

esp_err_t sdmmc_host_set_bus_width(int slot, size_t width)

Select bus width to be used for data transfer.

SD/MMC card must be initialized prior to this command, and a command to set bus width has to be sent to the card (e.g. SD_APP_SET_BUS_WIDTH)

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_ARG if slot number or width is not valid
Parameters
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • width: bus width (1, 4, or 8 for slot 0; 1 or 4 for slot 1)

esp_err_t sdmmc_host_set_card_clk(int slot, 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
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • freq_khz: card clock frequency, in kHz

esp_err_t sdmmc_host_do_transaction(int slot, 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 sdmmc_host_do_transaction as long as other sdmmc_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
  • slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
  • cmdinfo: pointer to structure describing command and data to transfer

esp_err_t sdmmc_host_deinit()

Disable SDMMC host and release allocated resources.

Note
This function is not thread safe
Return
  • ESP_OK on success
  • ESP_ERR_INVALID_STATE if sdmmc_host_init function has not been called