Detailed Description

Warning
This feature is experimental!
This API is experimental and in an early state - expect changes!

Overview

The SDIO/SD/MMC Device API (SDMMC) implements an SD host controller driver that provides a high-level API using a low-level SDIO/SD/MMC peripheral driver for accessing

In the context of this API, the term Card refers to either

The term slot refers to the interface for a removable card.

The SDIO/SD/MMC device API (SDMMC) is divided into two parts:

  1. The high-level API that implements the SD Host Controller driver and allows
    • to initialize and identify different types of cards,
    • to access them either blockwise or bytewise,
    • to get information about the used card, and
    • to send single commands or application specific commands to the card.
  2. The low-level SDIO/SD/MMC peripheral driver of type sdmmc_driver_t implements the low-level functions required by the high-level device API. It has to be implemented for each MCU. The support of the low-level SDIO/SD/MMC peripheral driver is indicated by the MCU or board by the periph_sdmmc feature.

Currently the SDIO/SD/MMC Device API supports the following card types:

Card Type Support Remark
MMC/eMMC in MultiMediaCard mode yes
MMC/eMMC in SPI mode no
SD Memory Card in SD mode yes SDSC, SDHC and SDXC with Default or High Speed
SD Memory Card in SPI mode no
SDIO in SD mode no
SDIO in SPI mode no

Limitations:

Features and Modules

A board that uses an MCU with an SDIO/SD/MMC peripheral and has a card slot or device connected has to indicate this as feature periph_sdmmc in order to use the SDIO/SD/MMC API or drivers based on it. Furthermore, specific features of the SDIO/SD/MMC peripheral or configurations of the board have to be defined by corresponding features.

These are in detail:

Some functionalities of the SDIO/SD/MMC Device API must be explicitly enabled via modules:

Files

file  sdmmc.h
 SDIO/SD/MMC device API using a low-level peripheral driver.
 

Data Structures

union  sdmmc_card_status_t
 SD/MMC Card status as structure. More...
 
struct  sdmmc_sd_status_t
 SD Status (SD Memory Card only) More...
 
struct  sdmmc_cid_sd_t
 CID register structure (SD Memory Cards) More...
 
struct  sdmmc_cid_mmc_t
 CID register structure (MMC) More...
 
union  sdmmc_cid_t
 CID register structure (SD Memory and MMC Cards) More...
 
struct  sdmmc_csd_v1_t
 CSD register structure Version 1.0. More...
 
struct  sdmmc_csd_v2_t
 CSD register structure Version 2.0 and Version 3.0. More...
 
struct  sdmmc_csd_mmc_t
 CSD register structure for MMC. More...
 
union  sdmmc_csd_t
 CSD register (SD Memory Card and MMC) More...
 
struct  sdmmc_ext_csd_t
 Extended CSD (EXT_CSD) register structure (MMC only) More...
 
struct  sdmmc_scr_t
 SCR register structure (SD Memory Card only) More...
 
struct  sdmmc_xfer_desc_t
 Transfer descriptor. More...
 
struct  sdmmc_driver_t
 Low-level SDIO/SD/MMC peripheral driver. More...
 
struct  sdmmc_dev
 SDIO/SD/MMC device descriptor. More...
 

Macros

#define SDMMC_CPU_DMA_REQUIREMENTS
 CPU-specific requirements for SDIO/SD/MMC buffers. More...
 
#define sdmmc_buf_t   SDMMC_CPU_DMA_REQUIREMENTS uint8_t
 Instantiation type for SDIO/SD/MMC buffers. More...
 
#define SDMMC_SDHC_BLOCK_SIZE   (512)
 Size of a single data block on SDHC/SDXC Cards in bytes. More...
 
#define SDMMC_CARD_TYPE_SD
 Mask for any type of SD Memory card. More...
 
#define SDMMC_NUMOF   XFA_LEN(sdmmc_dev_t *, sdmmc_devs)
 Number of SDIO/SD/MMC devices defined. More...
 

Typedefs

typedef struct sdmmc_dev sdmmc_dev_t
 sdmmc_dev_t forward declaration More...
 
typedef void(* sdmmc_event_cb_t) (sdmmc_dev_t *dev, sdmmc_event_t event)
 Event callback function type. More...
 

Enumerations

enum  sdmmc_card_type_t {
  SDMMC_CARD_TYPE_UNKNOWN = 0x00 , SDMMC_CARD_TYPE_SDSC_V1 = 0x01 , SDMMC_CARD_TYPE_SDSC_V2_V3 = 0x02 , SDMMC_CARD_TYPE_SDHC_SDXC = 0x04 ,
  SDMMC_CARD_TYPE_SDIO = 0x40 , SDMMC_CARD_TYPE_MMC = 0x80
}
 SDIO/SD/MMC Card types. More...
 
enum  sdmmc_bus_width_t { SDMMC_BUS_WIDTH_1BIT = 1 , SDMMC_BUS_WIDTH_4BIT = 4 , SDMMC_BUS_WIDTH_8BIT = 8 }
 SDIO/SD/MMC Card data bus widths. More...
 
enum  sdmmc_clock_rate_t {
  SDMMC_CLK_400K = KHZ(400) , SDMMC_CLK_20M = MHZ(20) , SDMMC_CLK_25M = MHZ(25) , SDMMC_CLK_26M = MHZ(26) ,
  SDMMC_CLK_50M = MHZ(50) , SDMMC_CLK_52M = MHZ(52)
}
 SDIO/SD/MMC Card clock rate types. More...
 
enum  sdmmc_xfer_type_t { SDMMC_MULTIBYTE , SDMMC_BLOCK , SDMMC_STREAM }
 Data transfer types. More...
 
enum  sdmmc_auto_cmd_t { SDMMC_AUTO_CMD_NONE = 0x00 , SDMMC_AUTO_CMD12 = 0x01 , SDMMC_AUTO_CMD23 = 0x02 , SDMMC_AUTO_CMD_BOTH = 0x03 }
 Auto Command features supported by the SDIO/SD/MMC peripheral. More...
 
enum  sdmmc_event_t { SDMMC_EVENT_CARD_INSERTED , SDMMC_EVENT_CARD_REMOVED }
 Events generated by SDIO/SD/MMC high level API. More...
 

Functions

static sdmmc_dev_tsdmmc_get_dev (unsigned num)
 Retrieve SDIO/SD/MMC device descriptor reference from device index. More...
 
static void sdmmc_init (sdmmc_dev_t *dev)
 Basic initialization of the given SDIO/SD/MMC device. More...
 
int sdmmc_send_cmd (sdmmc_dev_t *dev, sdmmc_cmd_t cmd_idx, uint32_t arg, sdmmc_resp_t resp_type, uint32_t *resp)
 Send command to SDIO/SD/MMC Card and optionally wait for response. More...
 
int sdmmc_send_acmd (sdmmc_dev_t *dev, sdmmc_cmd_t cmd_idx, uint32_t arg, sdmmc_resp_t resp_type, uint32_t *resp)
 Send application specific command optionally wait for response. More...
 
int sdmmc_card_init (sdmmc_dev_t *dev)
 Card Initialization and Identification. More...
 
int sdmmc_xfer (sdmmc_dev_t *dev, sdmmc_cmd_t cmd_idx, uint32_t arg, uint16_t block_size, uint16_t block_num, const void *data_wr, void *data_rd, uint16_t *done)
 Perform a data transfer with the selected card or embedded device. More...
 
int sdmmc_read_blocks (sdmmc_dev_t *dev, uint32_t block_addr, uint16_t block_size, uint16_t block_num, void *data, uint16_t *done)
 Read a number of blocks. More...
 
int sdmmc_write_blocks (sdmmc_dev_t *dev, uint32_t block_addr, uint16_t block_size, uint16_t block_num, const void *data, uint16_t *done)
 Write a number of blocks. More...
 
int sdmmc_erase_blocks (sdmmc_dev_t *dev, uint32_t block_addr, uint16_t block_num)
 Erase a number of blocks. More...
 
int sdmmc_read_sds (sdmmc_dev_t *dev, sdmmc_sd_status_t *sds)
 Read SD Status Register. More...
 
uint64_t sdmmc_get_capacity (sdmmc_dev_t *dev)
 Get Capacity of SD/MMC Card. More...
 

Variables

sdmmc_dev_t sdmmc_devs []
 SDIO/SD/MMC device descriptor references as read-only XFA. More...
 

Command and Response related definitions

enum  sdmmc_cmd_t {
  SDMMC_CMD0 = SDMMC_CMD(0) , SDMMC_CMD1 = SDMMC_CMD(1) , SDMMC_CMD2 = SDMMC_CMD(2) , SDMMC_CMD3 = SDMMC_CMD(3) ,
  SDMMC_CMD4 = SDMMC_CMD(4) , SDMMC_CMD5 = SDMMC_CMD(5) , SDMMC_CMD6 = SDMMC_CMD(6) , SDMMC_CMD7 = SDMMC_CMD(7) ,
  SDMMC_CMD8 = SDMMC_CMD(8) , SDMMC_CMD9 = SDMMC_CMD(9) , SDMMC_CMD10 = SDMMC_CMD(10) , SDMMC_CMD12 = SDMMC_CMD(12) ,
  SDMMC_CMD13 = SDMMC_CMD(13) , SDMMC_CMD16 = SDMMC_CMD(16) , SDMMC_CMD17 = SDMMC_CMD(17) , SDMMC_CMD18 = SDMMC_CMD(18) ,
  SDMMC_CMD23 = SDMMC_CMD(23) , SDMMC_CMD24 = SDMMC_CMD(24) , SDMMC_CMD25 = SDMMC_CMD(25) , SDMMC_CMD32 = SDMMC_CMD(32) ,
  SDMMC_CMD33 = SDMMC_CMD(33) , SDMMC_CMD38 = SDMMC_CMD(38) , SDMMC_CMD52 = SDMMC_CMD(52) , SDMMC_CMD53 = SDMMC_CMD(53) ,
  SDMMC_CMD55 = SDMMC_CMD(55) , SDMMC_CMD58 = SDMMC_CMD(58) , SDMMC_CMD59 = SDMMC_CMD(59) , SDMMC_ACMD6 = SDMMC_ACMD(6) ,
  SDMMC_ACMD13 = SDMMC_ACMD(13) , SDMMC_ACMD23 = SDMMC_ACMD(23) , SDMMC_ACMD41 = SDMMC_ACMD(41) , SDMMC_ACMD51 = SDMMC_ACMD(51)
}
 SDIO/SD/MMC Commands. More...
 
enum  sdmmc_resp_t {
  SDMMC_NO_R = 0 , SDMMC_R1 = 1 | SDMMC_RESP_CRC , SDMMC_R1B , SDMMC_R2 = 2 | SDMMC_RESP_CRC ,
  SDMMC_R3 = 3 , SDMMC_R4 = 4 , SDMMC_R5 = 5 | SDMMC_RESP_CRC , SDMMC_R6 = 6 | SDMMC_RESP_CRC ,
  SDMMC_R7 = 7 | SDMMC_RESP_CRC
}
 SDIO/SD/MMC Response types. More...
 
#define SDMMC_CMD(n)   (n)
 Command index. More...
 
#define SDMMC_ACMD_PREFIX   (1 << 7)
 Application specific command index prefix (Bit is 7 used) More...
 
#define SDMMC_ACMD(n)   (SDMMC_ACMD_PREFIX | SDMMC_CMD(n))
 Application specific command index. More...
 
#define SDMMC_CMD_NO_ARG   (0x00000000UL)
 Command argument if no argument is required. More...
 
#define SDMMC_CMD_ARG_RCA(n)   ((uint32_t)n << 16)
 Command argument if RCA is used in addressed commands. More...
 
#define SDMMC_RESP_CRC   (1UL << 4)
 Mask to check whether the response type uses CRC7. More...
 
#define SDMMC_RESP_BUSY   (1UL << 5)
 Mask to check whether the response includes busy status from card. More...
 
#define SDMMC_RESP_IDX   (0xf)
 Mask of response index. More...
 

SDIO/SD/MMC Card status as returned in responses R1 to CMD13 with b[15]=0

See also
Physical Layer Simplified Specification Version 9.00, Section 4.10.1, Table 4-42 [sdcard.org]
SDIO Simplified Specification Version 3.00, 4.10.8, Table 4-7, [sdcard.org]
JEDEC Standard No. JESD84-B42, MultiMediaCard (MMC) Electrical Standard, High Capacity (MMCA, 4.2), Section 7.11, Table 25 [jedec.org]
enum  {
  SDMMC_CARD_STATE_IDLE = 0 , SDMMC_CARD_STATE_READY = 1 , SDMMC_CARD_STATE_IDENT = 2 , SDMMC_CARD_STATE_STBY = 3 ,
  SDMMC_CARD_STATE_TRAN = 4 , SDMMC_CARD_STATE_DATA = 5 , SDMMC_CARD_STATE_RCV = 6 , SDMMC_CARD_STATE_PRG = 7 ,
  SDMMC_CARD_STATE_DIS = 8 , SDMMC_CARD_STATE_BTST = 9
}
 SD/MMC Card states. More...
 
#define SDMMC_CARD_STATUS_OUT_OF_RANGE   (1UL << 31)
 SD/SDIO and MMC. More...
 
#define SDMMC_CARD_STATUS_ADDRESS_ERROR   (1UL << 30)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_BLOCK_LEN_ERROR   (1UL << 29)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_ERASE_SEQ_ERROR   (1UL << 28)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_ERASE_PARAM   (1UL << 27)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_WP_VIOLATION   (1UL << 26)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_CARD_IS_LOCKED   (1UL << 25)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_LOCK_UNLOCK_FAILED   (1UL << 24)
 SD/SDIO and MMC. More...
 
#define SDMMC_CARD_STATUS_COM_CRC_ERROR   (1UL << 23)
 SD/SDIO and MMC. More...
 
#define SDMMC_CARD_STATUS_ILLEGAL_COMMAND   (1UL << 22)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_CARD_ECC_FAILED   (1UL << 21)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_CC_ERROR   (1UL << 20)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_ERROR   (1UL << 19)
 SD/SDIO and MMC. More...
 
#define SDMMC_CARD_STATUS_UNDERRUN   (1UL << 18)
 MMC only. More...
 
#define SDMMC_CARD_STATUS_OVERRUN   (1UL << 17)
 MMC only. More...
 
#define SDMMC_CARD_STATUS_CSD_OVERWRITE   (1UL << 16)
 SD (CSD), MMC (CSD and CID) More...
 
#define SDMMC_CARD_STATUS_WP_ERASE_SKIP   (1UL << 15)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_CARD_ECC_DISABLED   (1UL << 14)
 SD only. More...
 
#define SDMMC_CARD_STATUS_ERASE_RESET   (1UL << 13)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_READY_FOR_DATA   (1UL << 8)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_SWITCH_ERROR   (1UL << 7)
 MMC only. More...
 
#define SDMMC_CARD_STATUS_FX_EVENT   (1UL << 6)
 SD only. More...
 
#define SDMMC_CARD_STATUS_APP_CMD   (1UL << 5)
 SD and MMC. More...
 
#define SDMMC_CARD_STATUS_AKE_SEQ_ERROR   (1UL << 3)
 SD only. More...
 
#define SDMMC_CARD_STATUS_ERRORS
 SD/MMC Card status mask for error flags. More...
 
#define SDMMC_CARD_STATUS_CURRENT_STATE(n)   (((n) >> SDMMC_CARD_STATUS_CURRENT_STATE_Pos) & 0x0f)
 SD/MMC Card status mask for current state. More...
 
#define SDMMC_CARD_STATUS_CURRENT_STATE_Pos   (9)
 CURRENT_STATE position. More...
 

CSD Register Definitions

See also
Physical Layer Simplified Specification Version 9.00, Section 5.3, [sdcard.org]
JEDEC Standard No. JESD84-B42, MultiMediaCard (MMC) Electrical Standard, High Capacity (MMCA, 4.2), Section 8.3, Table 35 [jedec.org]
enum  sdmmc_csd_version_t { SDMMC_CSD_V1 = 0 , SDMMC_CSD_V2 = 1 , SDMMC_CSD_V3 = 2 , SDMMC_CSD_Vx = 3 }
 CSD Register Versions (SD Memory Card and MMC) More...
 
#define SDMMC_CSD_REG_SIZE   (16)
 CSD register size in byte (CSD is 128 bit) More...
 
#define SDMMC_EXT_CSD_REG_SIZE   (512)
 Extended CSD (EXT_CSD) register size in byte (EXT_CSD is 512 byte) More...
 

Definitions used for CMD8 - SEND_IF_COND (SD only)

See also
Physical Layer Simplified Specification Version 9.00, Section 4.3.13 [sdcard.org]
#define SDMMC_CMD8_CHECK_PATTERN   (0xaa)
 Check pattern, 0xAA recommended. More...
 
#define SDMMC_CMD8_VHS_27_36V   (0b0001 << 8)
 Voltage Supplied by host 2.7-3.6V. More...
 
#define SDMMC_CMD8_PCIE_AVAIL   (1 << 12)
 PCIe Availability (not yet used) More...
 
#define SDMMC_CMD8_PCIE_12V   (1 << 13)
 PCIe 1.2V Support (not yet used) More...
 
#define SDMMC_CMD8_CHECK   (SDMMC_CMD8_VHS_27_36V | SDMMC_CMD8_CHECK_PATTERN)
 Command argument used in CMD8. More...
 

OCR Register Definition

See also
Physical Layer Simplified Specification Version 9.00, Section 5.1, Table 5-1 [sdcard.org]
#define SDMMC_OCR_18V   (1UL << 7)
 Low Voltage Range. More...
 
#define SDMMC_OCR_27_28V   (1UL << 15)
 2.7V to 2.8V Range More...
 
#define SDMMC_OCR_28_29V   (1UL << 16)
 2.8V to 2.9V Range More...
 
#define SDMMC_OCR_29_30V   (1UL << 17)
 2.9V to 3.0V Range More...
 
#define SDMMC_OCR_30_31V   (1UL << 18)
 3.0V to 3.1V Range More...
 
#define SDMMC_OCR_31_32V   (1UL << 19)
 3.1V to 3.2V Range More...
 
#define SDMMC_OCR_32_33V   (1UL << 20)
 3.2V to 3.3V Range More...
 
#define SDMMC_OCR_33_34V   (1UL << 21)
 3.3V to 3.4V Range More...
 
#define SDMMC_OCR_34_35V   (1UL << 22)
 3.4V to 3.5V Range More...
 
#define SDMMC_OCR_35_36V   (1UL << 23)
 3.5V to 3.6V Range More...
 
#define SDMMC_OCR_S18A   (1UL << 24)
 Switching to 1.8V Accepted. More...
 
#define SDMMC_OCR_OVER_2TB   (1UL << 27)
 Over 2TB support status (CO2T) More...
 
#define SDMMC_OCR_UHS_II   (1UL << 29)
 UHS-II Card Status. More...
 
#define SDMMC_OCR_CCS   (1UL << 30)
 Card Capacity Status (CCS) More...
 
#define SDMMC_OCR_POWER_UP   (1UL << 31)
 Card power up status bit (busy) More...
 
#define SDMMC_OCR_ALL_VOLTAGES
 Voltage profile for the range 2.7-3.6V as defined for MMC. More...
 

SD Status register (SD Memory Cards)

#define SDMMC_SD_STATUS_SIZE   (64)
 SD status register size. More...
 

CID register (SD Memory and MMC Cards)

#define SDMMC_CID_REG_SIZE   (16)
 CID register size in bytes (CID is 128 bit) More...
 
#define SDMMC_CID_OID_SIZE_SD   (2)
 OID (OEM/Application ID) size in byte (SD) More...
 
#define SDMMC_CID_PNM_SIZE_SD   (5)
 PNM (Product name) size in byte (SD) More...
 
#define SDMMC_CID_PNM_SIZE_MMC   (6)
 PNM (Product name) size in byte (MMC) More...
 

SCR Register Definitions (SD Memory Card only)

See also
Physical Layer Simplified Specification Version 9.00, Section 5.6, Table 5-17 [sdcard.org]
#define SDMMC_SCR_REG_SIZE   (8)
 SCR register size in byte (SCR is 64 bit) More...
 
#define SDMMC_SCR_ACMD_53_54_SUPPORT   (0b10000)
 sdmmc_scr_t::CMD_SUPPORT Secure Receive/Send supported More...
 
#define SDMMC_SCR_ACMD_58_59_SUPPORT   (0b01000)
 sdmmc_scr_t::CMD_SUPPORT Extension Register Multi-Block More...
 
#define SDMMC_SCR_ACMD_48_49_SUPPORT   (0b00100)
 sdmmc_scr_t::CMD_SUPPORT Extension Register Single-Block More...
 
#define SDMMC_SCR_ACMD_23_SUPPORT   (0b00010)
 sdmmc_scr_t::CMD_SUPPORT Set Block Count More...
 
#define SDMMC_SCR_ACMD_20_SUPPORT   (0b00001)
 sdmmc_scr_t::CMD_SUPPORT Speed Class Control More...
 
#define SDMMC_SCR_SD_SPEC(scr)    (scr.SD_SPEC + scr.SD_SPEC3 + (scr.SD_SPECX ? scr.SD_SPECX + 1 : scr.SD_SPEC4))
 Get Physical Layer Specification Version value from SCR value. More...
 
#define SDMMC_DEV(x)   (sdmmc_get_dev(x))
 SD/MMC device access macro. More...
 

Macro Definition Documentation

◆ SDMMC_ACMD

#define SDMMC_ACMD (   n)    (SDMMC_ACMD_PREFIX | SDMMC_CMD(n))

Application specific command index.

Definition at line 191 of file sdmmc.h.

◆ SDMMC_ACMD_PREFIX

#define SDMMC_ACMD_PREFIX   (1 << 7)

Application specific command index prefix (Bit is 7 used)

Definition at line 186 of file sdmmc.h.

◆ sdmmc_buf_t

#define sdmmc_buf_t   SDMMC_CPU_DMA_REQUIREMENTS uint8_t

Instantiation type for SDIO/SD/MMC buffers.

Example usage:

#define sdmmc_buf_t
Instantiation type for SDIO/SD/MMC buffers.
Definition: sdmmc.h:163
#define SDMMC_SDHC_BLOCK_SIZE
Size of a single data block on SDHC/SDXC Cards in bytes.
Definition: sdmmc.h:171

Definition at line 163 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_ADDRESS_ERROR

#define SDMMC_CARD_STATUS_ADDRESS_ERROR   (1UL << 30)

SD and MMC.

Definition at line 410 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_AKE_SEQ_ERROR

#define SDMMC_CARD_STATUS_AKE_SEQ_ERROR   (1UL << 3)

SD only.

Definition at line 432 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_APP_CMD

#define SDMMC_CARD_STATUS_APP_CMD   (1UL << 5)

SD and MMC.

Definition at line 431 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_BLOCK_LEN_ERROR

#define SDMMC_CARD_STATUS_BLOCK_LEN_ERROR   (1UL << 29)

SD and MMC.

Definition at line 411 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_CARD_ECC_DISABLED

#define SDMMC_CARD_STATUS_CARD_ECC_DISABLED   (1UL << 14)

SD only.

Definition at line 426 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_CARD_ECC_FAILED

#define SDMMC_CARD_STATUS_CARD_ECC_FAILED   (1UL << 21)

SD and MMC.

Definition at line 419 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_CARD_IS_LOCKED

#define SDMMC_CARD_STATUS_CARD_IS_LOCKED   (1UL << 25)

SD and MMC.

Definition at line 415 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_CC_ERROR

#define SDMMC_CARD_STATUS_CC_ERROR   (1UL << 20)

SD and MMC.

Definition at line 420 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_COM_CRC_ERROR

#define SDMMC_CARD_STATUS_COM_CRC_ERROR   (1UL << 23)

SD/SDIO and MMC.

Definition at line 417 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_CSD_OVERWRITE

#define SDMMC_CARD_STATUS_CSD_OVERWRITE   (1UL << 16)

SD (CSD), MMC (CSD and CID)

Definition at line 424 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_CURRENT_STATE

#define SDMMC_CARD_STATUS_CURRENT_STATE (   n)    (((n) >> SDMMC_CARD_STATUS_CURRENT_STATE_Pos) & 0x0f)

SD/MMC Card status mask for current state.

Definition at line 455 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_CURRENT_STATE_Pos

#define SDMMC_CARD_STATUS_CURRENT_STATE_Pos   (9)

CURRENT_STATE position.

Definition at line 456 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_ERASE_PARAM

#define SDMMC_CARD_STATUS_ERASE_PARAM   (1UL << 27)

SD and MMC.

Definition at line 413 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_ERASE_RESET

#define SDMMC_CARD_STATUS_ERASE_RESET   (1UL << 13)

SD and MMC.

Definition at line 427 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_ERASE_SEQ_ERROR

#define SDMMC_CARD_STATUS_ERASE_SEQ_ERROR   (1UL << 28)

SD and MMC.

Definition at line 412 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_ERROR

#define SDMMC_CARD_STATUS_ERROR   (1UL << 19)

SD/SDIO and MMC.

Definition at line 421 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_ERRORS

#define SDMMC_CARD_STATUS_ERRORS
Value:
SDMMC_CARD_STATUS_ADDRESS_ERROR | \
SDMMC_CARD_STATUS_BLOCK_LEN_ERROR | \
SDMMC_CARD_STATUS_ERASE_SEQ_ERROR | \
SDMMC_CARD_STATUS_ERASE_PARAM | \
SDMMC_CARD_STATUS_WP_VIOLATION | \
SDMMC_CARD_STATUS_LOCK_UNLOCK_FAILED | \
SDMMC_CARD_STATUS_COM_CRC_ERROR | \
SDMMC_CARD_STATUS_ILLEGAL_COMMAND | \
SDMMC_CARD_STATUS_CARD_ECC_FAILED | \
SDMMC_CARD_STATUS_CC_ERROR | \
SDMMC_CARD_STATUS_ERROR | \
SDMMC_CARD_STATUS_UNDERRUN | \
SDMMC_CARD_STATUS_OVERRUN | \
SDMMC_CARD_STATUS_CSD_OVERWRITE | \
SDMMC_CARD_STATUS_WP_ERASE_SKIP | \
SDMMC_CARD_STATUS_SWITCH_ERROR | \
SDMMC_CARD_STATUS_AKE_SEQ_ERROR)
#define SDMMC_CARD_STATUS_OUT_OF_RANGE
SD/SDIO and MMC.
Definition: sdmmc.h:409

SD/MMC Card status mask for error flags.

Definition at line 435 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_FX_EVENT

#define SDMMC_CARD_STATUS_FX_EVENT   (1UL << 6)

SD only.

Definition at line 430 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_ILLEGAL_COMMAND

#define SDMMC_CARD_STATUS_ILLEGAL_COMMAND   (1UL << 22)

SD and MMC.

Definition at line 418 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_LOCK_UNLOCK_FAILED

#define SDMMC_CARD_STATUS_LOCK_UNLOCK_FAILED   (1UL << 24)

SD/SDIO and MMC.

Definition at line 416 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_OUT_OF_RANGE

#define SDMMC_CARD_STATUS_OUT_OF_RANGE   (1UL << 31)

SD/SDIO and MMC.

Definition at line 409 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_OVERRUN

#define SDMMC_CARD_STATUS_OVERRUN   (1UL << 17)

MMC only.

Definition at line 423 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_READY_FOR_DATA

#define SDMMC_CARD_STATUS_READY_FOR_DATA   (1UL << 8)

SD and MMC.

Definition at line 428 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_SWITCH_ERROR

#define SDMMC_CARD_STATUS_SWITCH_ERROR   (1UL << 7)

MMC only.

Definition at line 429 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_UNDERRUN

#define SDMMC_CARD_STATUS_UNDERRUN   (1UL << 18)

MMC only.

Definition at line 422 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_WP_ERASE_SKIP

#define SDMMC_CARD_STATUS_WP_ERASE_SKIP   (1UL << 15)

SD and MMC.

Definition at line 425 of file sdmmc.h.

◆ SDMMC_CARD_STATUS_WP_VIOLATION

#define SDMMC_CARD_STATUS_WP_VIOLATION   (1UL << 26)

SD and MMC.

Definition at line 414 of file sdmmc.h.

◆ SDMMC_CARD_TYPE_SD

#define SDMMC_CARD_TYPE_SD
Value:
SDMMC_CARD_TYPE_SDSC_V2_V3 | \
SDMMC_CARD_TYPE_SDHC_SDXC)
@ SDMMC_CARD_TYPE_SDSC_V1
SD Memory Card Standard Capacity (SDSC) Version 1.x.
Definition: sdmmc.h:345

Mask for any type of SD Memory card.

Definition at line 356 of file sdmmc.h.

◆ SDMMC_CID_OID_SIZE_SD

#define SDMMC_CID_OID_SIZE_SD   (2)

OID (OEM/Application ID) size in byte (SD)

Definition at line 561 of file sdmmc.h.

◆ SDMMC_CID_PNM_SIZE_MMC

#define SDMMC_CID_PNM_SIZE_MMC   (6)

PNM (Product name) size in byte (MMC)

Definition at line 563 of file sdmmc.h.

◆ SDMMC_CID_PNM_SIZE_SD

#define SDMMC_CID_PNM_SIZE_SD   (5)

PNM (Product name) size in byte (SD)

Definition at line 562 of file sdmmc.h.

◆ SDMMC_CID_REG_SIZE

#define SDMMC_CID_REG_SIZE   (16)

CID register size in bytes (CID is 128 bit)

Definition at line 559 of file sdmmc.h.

◆ SDMMC_CMD

#define SDMMC_CMD (   n)    (n)

Command index.

Definition at line 181 of file sdmmc.h.

◆ SDMMC_CMD8_CHECK

#define SDMMC_CMD8_CHECK   (SDMMC_CMD8_VHS_27_36V | SDMMC_CMD8_CHECK_PATTERN)

Command argument used in CMD8.

Definition at line 292 of file sdmmc.h.

◆ SDMMC_CMD8_CHECK_PATTERN

#define SDMMC_CMD8_CHECK_PATTERN   (0xaa)

Check pattern, 0xAA recommended.

Definition at line 286 of file sdmmc.h.

◆ SDMMC_CMD8_PCIE_12V

#define SDMMC_CMD8_PCIE_12V   (1 << 13)

PCIe 1.2V Support (not yet used)

Definition at line 289 of file sdmmc.h.

◆ SDMMC_CMD8_PCIE_AVAIL

#define SDMMC_CMD8_PCIE_AVAIL   (1 << 12)

PCIe Availability (not yet used)

Definition at line 288 of file sdmmc.h.

◆ SDMMC_CMD8_VHS_27_36V

#define SDMMC_CMD8_VHS_27_36V   (0b0001 << 8)

Voltage Supplied by host 2.7-3.6V.

Definition at line 287 of file sdmmc.h.

◆ SDMMC_CMD_ARG_RCA

#define SDMMC_CMD_ARG_RCA (   n)    ((uint32_t)n << 16)

Command argument if RCA is used in addressed commands.

Definition at line 241 of file sdmmc.h.

◆ SDMMC_CMD_NO_ARG

#define SDMMC_CMD_NO_ARG   (0x00000000UL)

Command argument if no argument is required.

Definition at line 238 of file sdmmc.h.

◆ SDMMC_CPU_DMA_REQUIREMENTS

#define SDMMC_CPU_DMA_REQUIREMENTS

CPU-specific requirements for SDIO/SD/MMC buffers.

Can be overridden by periph_cpu if needed by the SDMMC/SDIO peripheral. Example usage:

SDMMC_CPU_DMA_REQUIREMENTS uint8_t buffer[64];
#define SDMMC_CPU_DMA_REQUIREMENTS
SDIO/SDMMC buffer instantiation requirement for SDHC.
Definition: periph_cpu.h:729

Definition at line 152 of file sdmmc.h.

◆ SDMMC_CSD_REG_SIZE

#define SDMMC_CSD_REG_SIZE   (16)

CSD register size in byte (CSD is 128 bit)

Definition at line 630 of file sdmmc.h.

◆ SDMMC_DEV

#define SDMMC_DEV (   x)    (sdmmc_get_dev(x))

SD/MMC device access macro.

Definition at line 875 of file sdmmc.h.

◆ SDMMC_EXT_CSD_REG_SIZE

#define SDMMC_EXT_CSD_REG_SIZE   (512)

Extended CSD (EXT_CSD) register size in byte (EXT_CSD is 512 byte)

Definition at line 776 of file sdmmc.h.

◆ SDMMC_NUMOF

#define SDMMC_NUMOF   XFA_LEN(sdmmc_dev_t *, sdmmc_devs)

Number of SDIO/SD/MMC devices defined.

Definition at line 1439 of file sdmmc.h.

◆ SDMMC_OCR_18V

#define SDMMC_OCR_18V   (1UL << 7)

Low Voltage Range.

Definition at line 302 of file sdmmc.h.

◆ SDMMC_OCR_27_28V

#define SDMMC_OCR_27_28V   (1UL << 15)

2.7V to 2.8V Range

Definition at line 303 of file sdmmc.h.

◆ SDMMC_OCR_28_29V

#define SDMMC_OCR_28_29V   (1UL << 16)

2.8V to 2.9V Range

Definition at line 304 of file sdmmc.h.

◆ SDMMC_OCR_29_30V

#define SDMMC_OCR_29_30V   (1UL << 17)

2.9V to 3.0V Range

Definition at line 305 of file sdmmc.h.

◆ SDMMC_OCR_30_31V

#define SDMMC_OCR_30_31V   (1UL << 18)

3.0V to 3.1V Range

Definition at line 306 of file sdmmc.h.

◆ SDMMC_OCR_31_32V

#define SDMMC_OCR_31_32V   (1UL << 19)

3.1V to 3.2V Range

Definition at line 307 of file sdmmc.h.

◆ SDMMC_OCR_32_33V

#define SDMMC_OCR_32_33V   (1UL << 20)

3.2V to 3.3V Range

Definition at line 308 of file sdmmc.h.

◆ SDMMC_OCR_33_34V

#define SDMMC_OCR_33_34V   (1UL << 21)

3.3V to 3.4V Range

Definition at line 309 of file sdmmc.h.

◆ SDMMC_OCR_34_35V

#define SDMMC_OCR_34_35V   (1UL << 22)

3.4V to 3.5V Range

Definition at line 310 of file sdmmc.h.

◆ SDMMC_OCR_35_36V

#define SDMMC_OCR_35_36V   (1UL << 23)

3.5V to 3.6V Range

Definition at line 311 of file sdmmc.h.

◆ SDMMC_OCR_ALL_VOLTAGES

#define SDMMC_OCR_ALL_VOLTAGES
Value:
SDMMC_OCR_29_30V | SDMMC_OCR_30_31V | \
SDMMC_OCR_31_32V | SDMMC_OCR_32_33V | \
SDMMC_OCR_33_34V | SDMMC_OCR_34_35V | \
SDMMC_OCR_35_36V)
#define SDMMC_OCR_32_33V
3.2V to 3.3V Range
Definition: sdmmc.h:308
#define SDMMC_OCR_30_31V
3.0V to 3.1V Range
Definition: sdmmc.h:306
#define SDMMC_OCR_27_28V
2.7V to 2.8V Range
Definition: sdmmc.h:303
#define SDMMC_OCR_28_29V
2.8V to 2.9V Range
Definition: sdmmc.h:304
#define SDMMC_OCR_34_35V
3.4V to 3.5V Range
Definition: sdmmc.h:310

Voltage profile for the range 2.7-3.6V as defined for MMC.

See also
JEDEC Standard No. JESD84-B42, MultiMediaCard (MMC) Electrical Standard, High Capacity (MMCA, 4.2), Section 8, Table 29 [jedec.org]

Definition at line 326 of file sdmmc.h.

◆ SDMMC_OCR_CCS

#define SDMMC_OCR_CCS   (1UL << 30)

Card Capacity Status (CCS)

Definition at line 316 of file sdmmc.h.

◆ SDMMC_OCR_OVER_2TB

#define SDMMC_OCR_OVER_2TB   (1UL << 27)

Over 2TB support status (CO2T)

Definition at line 314 of file sdmmc.h.

◆ SDMMC_OCR_POWER_UP

#define SDMMC_OCR_POWER_UP   (1UL << 31)

Card power up status bit (busy)

Definition at line 317 of file sdmmc.h.

◆ SDMMC_OCR_S18A

#define SDMMC_OCR_S18A   (1UL << 24)

Switching to 1.8V Accepted.

Definition at line 313 of file sdmmc.h.

◆ SDMMC_OCR_UHS_II

#define SDMMC_OCR_UHS_II   (1UL << 29)

UHS-II Card Status.

Definition at line 315 of file sdmmc.h.

◆ SDMMC_RESP_BUSY

#define SDMMC_RESP_BUSY   (1UL << 5)

Mask to check whether the response includes busy status from card.

Definition at line 246 of file sdmmc.h.

◆ SDMMC_RESP_CRC

#define SDMMC_RESP_CRC   (1UL << 4)

Mask to check whether the response type uses CRC7.

Definition at line 244 of file sdmmc.h.

◆ SDMMC_RESP_IDX

#define SDMMC_RESP_IDX   (0xf)

Mask of response index.

Definition at line 248 of file sdmmc.h.

◆ SDMMC_SCR_ACMD_20_SUPPORT

#define SDMMC_SCR_ACMD_20_SUPPORT   (0b00001)

sdmmc_scr_t::CMD_SUPPORT Speed Class Control

Definition at line 846 of file sdmmc.h.

◆ SDMMC_SCR_ACMD_23_SUPPORT

#define SDMMC_SCR_ACMD_23_SUPPORT   (0b00010)

sdmmc_scr_t::CMD_SUPPORT Set Block Count

Definition at line 844 of file sdmmc.h.

◆ SDMMC_SCR_ACMD_48_49_SUPPORT

#define SDMMC_SCR_ACMD_48_49_SUPPORT   (0b00100)

sdmmc_scr_t::CMD_SUPPORT Extension Register Single-Block

Definition at line 842 of file sdmmc.h.

◆ SDMMC_SCR_ACMD_53_54_SUPPORT

#define SDMMC_SCR_ACMD_53_54_SUPPORT   (0b10000)

sdmmc_scr_t::CMD_SUPPORT Secure Receive/Send supported

Definition at line 838 of file sdmmc.h.

◆ SDMMC_SCR_ACMD_58_59_SUPPORT

#define SDMMC_SCR_ACMD_58_59_SUPPORT   (0b01000)

sdmmc_scr_t::CMD_SUPPORT Extension Register Multi-Block

Definition at line 840 of file sdmmc.h.

◆ SDMMC_SCR_REG_SIZE

#define SDMMC_SCR_REG_SIZE   (8)

SCR register size in byte (SCR is 64 bit)

Definition at line 807 of file sdmmc.h.

◆ SDMMC_SCR_SD_SPEC

#define SDMMC_SCR_SD_SPEC (   scr)     (scr.SD_SPEC + scr.SD_SPEC3 + (scr.SD_SPECX ? scr.SD_SPECX + 1 : scr.SD_SPEC4))

Get Physical Layer Specification Version value from SCR value.

Parameters
scrSCR register value of type sdmmc_scr_t
Value Physical Layer Specification Version Number
0 Version 1.0 and 1.01
1 Version 1.10
2 Version 2.00
3 Version 3.0X
4 Version 4.XX
5 Version 5.XX
6 Version 6.XX
7 Version 7.XX
8 Version 8.XX
9 Version 9.XX

Definition at line 866 of file sdmmc.h.

◆ SDMMC_SD_STATUS_SIZE

#define SDMMC_SD_STATUS_SIZE   (64)

SD status register size.

Definition at line 519 of file sdmmc.h.

◆ SDMMC_SDHC_BLOCK_SIZE

#define SDMMC_SDHC_BLOCK_SIZE   (512)

Size of a single data block on SDHC/SDXC Cards in bytes.

The size of a data block depend on type and mode of the card. SDSC/SDXC use a fix size of 512 bytes.

Definition at line 171 of file sdmmc.h.

Typedef Documentation

◆ sdmmc_dev_t

typedef struct sdmmc_dev sdmmc_dev_t

sdmmc_dev_t forward declaration

SDIO/SD/MMC device descriptor.

The device descriptor holds all required information about the SDIO/SD/MMC device and the card that is used by this decive.

Note
Most of the information is determined or collected during the card initialization and identification procedure by the sdmmc_card_init function. However, some information must be determined and collected by the low-level SDIO/SD/MMC peripheral driver. These are

Definition at line 881 of file sdmmc.h.

◆ sdmmc_event_cb_t

typedef void(* sdmmc_event_cb_t) (sdmmc_dev_t *dev, sdmmc_event_t event)

Event callback function type.

Parameters
[in]devSDIO/SD/MMC device to be used
[in]eventEvent
Warning
The function is called in the ISR context. Do not do anything comprehensive or time-consuming. Instead, use thread_flags, event_queue or msg mechanism to inform a thread about the event, which then handles the event asynchronously in thread context.

Definition at line 943 of file sdmmc.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

SD/MMC Card states.

Enumerator
SDMMC_CARD_STATE_IDLE 

Idle.

SDMMC_CARD_STATE_READY 

Ready.

SDMMC_CARD_STATE_IDENT 

Identification.

SDMMC_CARD_STATE_STBY 

Stand-by.

SDMMC_CARD_STATE_TRAN 

Transfer.

SDMMC_CARD_STATE_DATA 

Data.

SDMMC_CARD_STATE_RCV 

Receive.

SDMMC_CARD_STATE_PRG 

Programming.

SDMMC_CARD_STATE_DIS 

Disconnect.

SDMMC_CARD_STATE_BTST 

Bus Test.

Definition at line 461 of file sdmmc.h.

◆ sdmmc_auto_cmd_t

Auto Command features supported by the SDIO/SD/MMC peripheral.

Most SDIO/SD/MMC peripherals support the Auto-Command feature for CMD12 and CMD23. The low-level SDIO/SD/MMC peripheral driver defines in sdmmc_driver_t::init which Auto-Command features are supported by the peripheral. To be able to specify a combination of these features, the enumeration values are defined bitwise.

Definition at line 917 of file sdmmc.h.

◆ sdmmc_bus_width_t

SDIO/SD/MMC Card data bus widths.

Possible bus widths are given as integer values as defined in SD Status register and the SCR register for SD Cards.

Warning
The values differ from the bus widths used in ACMD6 for SD Cards and the CCC register in SDIO Cards.
See also
Physical Layer Simplified Specification Version 9.00, 4.10.2, Table 4-44, SD Status [sdcard.org]
Enumerator
SDMMC_BUS_WIDTH_1BIT 

Data bus width is 1 bit (default)

SDMMC_BUS_WIDTH_4BIT 

Data bus width is 4 bit.

SDMMC_BUS_WIDTH_8BIT 

Data bus width is 8 bit.

Definition at line 372 of file sdmmc.h.

◆ sdmmc_card_type_t

SDIO/SD/MMC Card types.

To be able to specify a Combo card (combined SD Memory and SDIO card), the enumeration values are defined bitwise so that they can be ORed to represent a Combo card with different versions of the SD Memory part. For example, SDMMC_CARD_TYPE_SDIO | SDMMC_CARD_TYPE_SDSC_V2_V3 represents a Combo card with SDIO function and SD Memory Card Standard Capacity (SDSC) Version 2.x+.

Enumerator
SDMMC_CARD_TYPE_UNKNOWN 

Card type unknown.

SDMMC_CARD_TYPE_SDSC_V1 

SD Memory Card Standard Capacity (SDSC) Version 1.x.

SDMMC_CARD_TYPE_SDSC_V2_V3 

SD Memory Card Standard Capacity (SDSC) Version 2.x+.

SDMMC_CARD_TYPE_SDHC_SDXC 

SD Memory Card High or Extended Capacity (SDHC/SDXC)

SDMMC_CARD_TYPE_SDIO 

SDIO Card.

SDMMC_CARD_TYPE_MMC 

MultiMedia Card.

Definition at line 343 of file sdmmc.h.

◆ sdmmc_clock_rate_t

SDIO/SD/MMC Card clock rate types.

Identifies the clock frequency to be used. The clock frequency in identification mode f_OD (Open Drain mode) is fixed and is f_OD = 400 kHz. The actual clock frequency in data transfer mode f_PP (Push-Pull mode) depends on the SDIO/SD/MMC device and the card used. The low-level SDIO/SD/MMC peripheral driver sets the actual clock rate in function sdmmc_driver_t::set_clock_rate.

Enumerator
SDMMC_CLK_400K 

Identification Mode f_OD (400 kHz)

SDMMC_CLK_20M 

MMC Card in Data Transfer Mode (Backward Compatibility)

SDMMC_CLK_25M 

SD/SDIO Card in Data Transfer Mode (Default Speed)

SDMMC_CLK_26M 

MMC/eMMC Card in Data Transfer Mode (Default Speed)

SDMMC_CLK_50M 

SD/SDIO Card in Data Transfer Mode (High Speed)

SDMMC_CLK_52M 

MMC/eMMC in Data Transfer Mode (High Speed)

Definition at line 388 of file sdmmc.h.

◆ sdmmc_cmd_t

SDIO/SD/MMC Commands.

Commands used by the driver. Command indices are in range [0..63]. Application specific command indices are ORed with SDMMC_ACMD_PREFIX (0x80) and thus marked as application specific. SDMMC_ACMD_PREFIX can be used to check whether a given command index specifies an application specific command.

Enumerator
SDMMC_CMD0 

GO_IDLE_STATE.

SDMMC_CMD1 

SEND_OP_COND.

SDMMC_CMD2 

ALL_SEND_CID.

SDMMC_CMD3 

SET_RELATIVE_ADDR.

SDMMC_CMD4 

SET_DSR.

SDMMC_CMD5 

SD_APP_OP_COND (SDIO only)

SDMMC_CMD6 

SWITCH.

SDMMC_CMD7 

SELECT/DESELECT_CARD.

SDMMC_CMD8 

SEND_IF_COND (SD), SEND_EXT_CSD (MMC)

SDMMC_CMD9 

SEND_CSD.

SDMMC_CMD10 

SEND_CID.

SDMMC_CMD12 

STOP_TRANSMISSION.

SDMMC_CMD13 

SEND_STATUS.

SDMMC_CMD16 

SET_BLOCKLEN.

SDMMC_CMD17 

READ_SINGLE_BLOCK.

SDMMC_CMD18 

READ_MULTIPLE_BLOCK.

SDMMC_CMD23 

SET_BLOCK_COUNT.

SDMMC_CMD24 

WRITE_BLOCK.

SDMMC_CMD25 

WRITE_MULTIPLE_BLOCK.

SDMMC_CMD32 

ERASE_WR_BLK_START.

SDMMC_CMD33 

ERASE_WR_BLK_END.

SDMMC_CMD38 

ERASE.

SDMMC_CMD52 

IO_RW_DIRECT (SDIO only)

SDMMC_CMD53 

IO_RW_EXTENDED (SDIO only)

SDMMC_CMD55 

APP_CMD.

SDMMC_CMD58 

READ_OCR (SPI mode only)

SDMMC_CMD59 

CRC_ON_OFF (SPI mode only)

SDMMC_ACMD6 

SET_BUS_WIDTH.

SDMMC_ACMD13 

SD_STATUS.

SDMMC_ACMD23 

SET_WR_BLK_ERASE_COUNT.

SDMMC_ACMD41 

SD_APP_OP_COND.

SDMMC_ACMD51 

SEND_SCR.

Definition at line 202 of file sdmmc.h.

◆ sdmmc_csd_version_t

CSD Register Versions (SD Memory Card and MMC)

Enumerator
SDMMC_CSD_V1 

CSD Version 1.0 (SDSC and MMC)

SDMMC_CSD_V2 

CSD Version 2.0 (SDHC/SDXC) or Version 1.1 (MMC)

SDMMC_CSD_V3 

CSD Version 3.0 (SDUC) or Version 1.2 (MMC)

SDMMC_CSD_Vx 

Reserved (SD) or Version in EXT_CSD (MMC)

Definition at line 622 of file sdmmc.h.

◆ sdmmc_event_t

Events generated by SDIO/SD/MMC high level API.

Definition at line 927 of file sdmmc.h.

◆ sdmmc_resp_t

SDIO/SD/MMC Response types.

See also
Physical Layer Simplified Specification Version 9.00, Section 9.00 [sdcard.org] and
JEDEC Standard No. JESD84-B42, MultiMediaCard (MMC) Electrical Standard, High Capacity (MMCA, 4.2), Section 7.10 for R4 and R5 [jedec.org]
Enumerator
SDMMC_NO_R 

No response expected.

SDMMC_R1 

Normal Response [48 bit (32 bit card status)].

SDMMC_R1B 

Normal Response [48 bit (R1 with optional busy signal on DAT0)].

SDMMC_R2 

CID/CSD [136 bit (128 bit CID or CSD)].

SDMMC_R3 

OCR Resister [48 bit (32 bit OCR)].

SDMMC_R4 

Fast I/O [48 bit (16 bit RCA, 1 bit status, 7 bit addr, 8 bit reg)].

SDMMC_R5 

Interrupt Request [48 bit (16 bit RCA, 16 bit not defined)

SDMMC_R6 

Published RCA Response [48 bit (16 bit RCA, 16 bit card status)

SDMMC_R7 

Card Interface Condition [48 bit] (32 bit data, see section 4.9.6)

Definition at line 259 of file sdmmc.h.

◆ sdmmc_xfer_type_t

Data transfer types.

Enumerator
SDMMC_MULTIBYTE 

Transfer 1 to READ_BL_LEN/WRITE_BL_LEN bytes.

SDMMC_BLOCK 

Transfer block with size of READ_BL_LEN/WRITE_BL_LEN.

SDMMC_STREAM 

Transfer until CMD12 is sent (MMC and 1-bit bus only)

Definition at line 886 of file sdmmc.h.

Function Documentation

◆ sdmmc_card_init()

int sdmmc_card_init ( sdmmc_dev_t dev)

Card Initialization and Identification.

This function identifies the type of used SDIO/SD/MMC Cards and initializes them according to the standardized procedure specified in:

  • Physical Layer Simplified Specification Version 9.00, Section 4.2.3 Card Initialization and Identification Process, pp. 43 [sdcard.org]
  • SDIO Simplified Specification Version 3.00, Section 3.1.2 Initialization by I/O Aware Host, pp. 17 [sdcard.org]
  • SD Host Controller Simplified Specification Version 4.20, Section 3.6 Card Initialization and Identification (for SD I/F), pp. 160 [sdcard.org]
  • JEDEC Standard No. JESD84-B42, MultiMediaCard (MMC) Electrical Standard, High Capacity (MMCA, 4.2), Section 7.2 Card Identification Mode, p. 24 and Figure 16 on p. 16 [jedec.org]

Identified card types are:

  • SD Memory Cards with Standard Capacity (SDSC) Version 1.x, Version 2.x+
  • SD Memory Cards with High or Extended Capacity (SDHC/SDXC)
  • SDIO Cards, not supported yet
  • Combined SDIO/SD Memory Cards (Combo Cards), SDIO part not supported yet
  • MultiMedia Cards (MMC) and Embedded Multimedia Cards (eMMC)
Warning
If the low-level SDIO/SD/MMC peripheral driver defines its own sdmmc_driver_t::card_init function, this function is used instead.
However, the low-level SDIO/SD/MMC peripheral driver should define its own sdmmc_driver_t::card_init function only in very special cases, e.g. when special hardware handling is required. Otherwise it is strongly recommended to set sdmmc_driver_t::card_init to NULL and to use the default procedure implemented by sdmmc_send_acmd.
See also
sdmmc_driver_t::card_init
Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
Return values
0on success
-ENODEVif card is not present or not usable
-ENOTSUPif card is not supported or can't operate under supplied voltage
-EFAULTon card status error
-ETIMEDOUTon card initialization and identification timeout
-EBADMSGon CRC7 error
-EIOon not further specified error incl. hardware errors

◆ sdmmc_erase_blocks()

int sdmmc_erase_blocks ( sdmmc_dev_t dev,
uint32_t  block_addr,
uint16_t  block_num 
)

Erase a number of blocks.

Erase block_num blocks starting at block address block_addr on SD/MMC Card device.

The starting block address is always specified as block address independent on the actual addressing scheme of used card. The driver takes care of mapping to byte addressing if needed.

Note
This function is only available for SD Memory Cards, MMC Cards or the SD Memory Card portion of a combined SDIO/SD Memory Card (Combo Card). Calling this function for a SDIO only card returns the -ENOTSUP error.
sdmmc_card_init is called implicitly if necessary.
Precondition
dev must not be NULL. block_num has to be greater than 0.
Parameters
[in]devSD/MMC device to be used
[in]block_addrStart address for erase given as block address
[in]block_numNumber of blocks to be erased
Return values
0on success, block_num blocks were erased successfully
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support erase operation or a command used
-EBUSYif card is busy
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EBADMSGon CRC7 error in response
-EINVALon invalid erase parameters
-EIOon not further specified error incl. hardware errors

◆ sdmmc_get_capacity()

uint64_t sdmmc_get_capacity ( sdmmc_dev_t dev)

Get Capacity of SD/MMC Card.

Get the capacity of a SD/MMC Card device.

Note
This function is only available for SD Memory Cards, MMC Cards or the SD Memory Card portion of a combined SDIO/SD Memory Card (Combo Card). Calling this function for a SDIO only card returns the -ENOTSUP error.
sdmmc_card_init is called implicitly if necessary.
Precondition
dev must not be NULL.
Parameters
[in]devSD/MMC device to be used
Returns
the capacity in in byte or 0 on error

◆ sdmmc_get_dev()

static sdmmc_dev_t * sdmmc_get_dev ( unsigned  num)
inlinestatic

Retrieve SDIO/SD/MMC device descriptor reference from device index.

The function converts the device index to the corresponding SDIO/SD/MMC device descriptor. See also sdmmc_devs.

Parameters
[in]numSDIO/SD/MMC peripheral index
Return values
pointerto the SDIO/SD/MMC device descriptor at index num on success
NULLif num is greater than the number of SDIO/SD/MMC device descriptors

Definition at line 1453 of file sdmmc.h.

◆ sdmmc_init()

static void sdmmc_init ( sdmmc_dev_t dev)
inlinestatic

Basic initialization of the given SDIO/SD/MMC device.

The function calls the low-level SDIO/SD/MMC peripheral driver function sdmmc_driver_t::init for the basic initialization of the SDIO/SD/MMC peripheral including the configuration of used pins.

If the auto_init module is enabled, it is called automatically during the startup. Otherwise, it has to be called before the SDIO/SD/MMC device is used for the first time.

Errors like configuration parameter problems are not signaled by return values, but by using the assert().

See also
sdmmc_driver_t::init
Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to initialize

Definition at line 1477 of file sdmmc.h.

◆ sdmmc_read_blocks()

int sdmmc_read_blocks ( sdmmc_dev_t dev,
uint32_t  block_addr,
uint16_t  block_size,
uint16_t  block_num,
void *  data,
uint16_t *  done 
)

Read a number of blocks.

Read block_num blocks with size block_size from dev starting at block address block_addr to buffer data.

The starting block address is always specified as block address independent on the actual addressing scheme of used card. The driver takes care of mapping to byte addressing if needed.

If the parameter done is not NULL, the function returns the number of read blocks.

Warning
The buffer data may need to be word-aligned depending on CPU-specific requirements. sdmmc_buf_t or SDMMC_CPU_DMA_REQUIREMENTS have to be used to define the buffer:
...
SDMMC_CPU_DMA_REQUIREMENTS uint8_t buffer[SDMMC_SDHC_BLOCK_SIZE];
Note
sdmmc_card_init is called implicitly if necessary.
Precondition
dev and data must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]block_addrStart address to read from given as block address
[in]block_sizeBlock size dependent on card and mode used
  • 512 bytes for block-oriented transfers (SDSC V2.x/SDHC/SDXC)
  • 1, 2, 4, ... 4096 for block-oriented transfers (MMC)
  • 512, 1024, 2048 for block-oriented transfers (SDSC V1.x)
  • 1...512 bytes in byte/multibyte mode (SDIO only)
  • 0 in stream mode (MMC only)
[in]block_numNumber of blocks:
  • 1, ... for block-oriented transfers (SD Card/MMC)
  • 1 in byte/multibyte mode (SDIO only)
  • 0 in stream mode (MMC only)
[out]dataBuffer for read data
[out]doneNumber of read blocks, can be NULL
Return values
0on success, block_num blocks were read successfully
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support a used command or is in wrong state
-EBUSYif card is busy
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EINVALon invalid transfer parameters
-EBADMSGon CRC7 error
-ENOMEMon RX FIFO overflow error
-EIOon not further specified error incl. hardware errors

◆ sdmmc_read_sds()

int sdmmc_read_sds ( sdmmc_dev_t dev,
sdmmc_sd_status_t sds 
)

Read SD Status Register.

Read the SD Status register of a SD Memory Card using ACMD13 and stores the results in the sds of type sdmmc_sd_status_t.

Note
This function is only available for SD Memory Cards or the SD Memory Card portion of a combined SDIO/SD Memory Card (Combo Card). Calling this function for a SDIO only card returns the -ENOTSUP error.
sdmmc_card_init is called implicitly if necessary.
Precondition
dev and sds must not be NULL.
Parameters
[in]devSD device to be used
[out]sdsSD Status register content
Return values
0on success
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support the operation
-EBUSYif card is busy
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EINVALon invalid transfer parameters
-EBADMSGon CRC7 error
-ENOMEMon RX FIFO overflow error
-EIOon not further specified error incl. hardware errors

◆ sdmmc_send_acmd()

int sdmmc_send_acmd ( sdmmc_dev_t dev,
sdmmc_cmd_t  cmd_idx,
uint32_t  arg,
sdmmc_resp_t  resp_type,
uint32_t *  resp 
)

Send application specific command optionally wait for response.

Send an application specific command cmd_idx with argument arg to the SDIO/SD/MMC Card. This function is a convenience function that uses the low-level SDIO/SD/MMC peripheral driver function sdmmc_driver_t::send_cmd. It just sends CMD55 before sending the command with index cmd_idx to the card. Addressed (point-to-point) commands are sent to the card that is currently selected.

Instead of using this function, the following could also be used:

sdmmc_send_cmd(dev, cmd_idx & ~SDMMC_ACMD_PREFIX, arg, resp_type, resp);
#define SDMMC_ACMD_PREFIX
Application specific command index prefix (Bit is 7 used)
Definition: sdmmc.h:186
int sdmmc_send_cmd(sdmmc_dev_t *dev, sdmmc_cmd_t cmd_idx, uint32_t arg, sdmmc_resp_t resp_type, uint32_t *resp)
Send command to SDIO/SD/MMC Card and optionally wait for response.
@ SDMMC_CMD55
APP_CMD.
Definition: sdmmc.h:227
@ SDMMC_R1
Normal Response [48 bit (32 bit card status)].
Definition: sdmmc.h:261
Note
sdmmc_card_init is called implicitly if necessary.
Warning
The command index must be an ACMD command index, i.e. the command index ORed with SDMMC_ACMD_PREFIX. Otherwise the function fails because of an assertion.

resp_type specifies the response expected.

The response is stored word-wise in host byte order in the buffer provided by resp as follows:

  • resp_type = SDMMC_NO_R (No Response): resp can be NULL
  • resp_tpye = SDMMC_R2 (Long Response): resp = { R[127:96], R[95:64], R[63:32], R[31:0] }
  • resp_type = anything else (Short Response): resp = { R[39:8] }

The buffer provided by resp can be NULL if the response is not needed. However, the low-level SDIO/SD/MMC peripheral driver must receive the expected response, but does not store it in resp in that case.

Note
R3 does not use CRC7 in CRC field but a fixed value of 0b111111. The low-level SDIO/SD/MMC peripheral driver must not check the CRC field for this response.
Precondition
dev must not be NULL. cmd_idx must be in range 0 to 63.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]cmd_idxCommand index of an application specific command
[in]argCommand argument
[in]resp_typeType of response expected
[out]respBuffer of 32-bit words to store the response
Return values
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support the command or is in wrong state
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EBADMSGon CRC7 error in response
-EIOon not further specified error incl. hardware errors

◆ sdmmc_send_cmd()

int sdmmc_send_cmd ( sdmmc_dev_t dev,
sdmmc_cmd_t  cmd_idx,
uint32_t  arg,
sdmmc_resp_t  resp_type,
uint32_t *  resp 
)

Send command to SDIO/SD/MMC Card and optionally wait for response.

Send the command cmd_idx with argument arg to the SDIO/SD/MMC card. resp_type specifies the type of the response expected. Addressed (point-to-point) commands are sent to the card that is currently selected.

This function just calls the low-level SDIO/SD/MMC peripheral driver function sdmmc_driver_t::send_cmd.

Note
sdmmc_card_init is called implicitly if necessary.
Warning
For application specific commands, the sdmmc_send_acmd function MUST to be used.

The response is stored word-wise in host byte order in the buffer provided by resp as follows:

  • resp_type = SDMMC_NO_R (No Response): resp can be NULL
  • resp_tpye = SDMMC_R2 (Long Response): resp = { R[127:96], R[95:64], R[63:32], R[31:0] }
  • resp_type = anything else (Short Response): resp = { R[39:8] }

The buffer provided by resp can be NULL if the response is not needed.

Note
R3 does not use CRC7 in CRC field but a fixed value of 0b111111. The low-level SDIO/SD/MMC peripheral driver must not check the CRC field for this response.
See also
sdmmc_driver_t::send_cmd
Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]cmd_idxCommand index
[in]argCommand argument
[in]resp_typeType of response expected
[out]respBuffer of 32-bit words to store the response if needed, otherwise NULL
Return values
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support the command or is in wrong state
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EBADMSGon CRC7 error in response
-EIOon not further specified error incl. hardware errors

◆ sdmmc_write_blocks()

int sdmmc_write_blocks ( sdmmc_dev_t dev,
uint32_t  block_addr,
uint16_t  block_size,
uint16_t  block_num,
const void *  data,
uint16_t *  done 
)

Write a number of blocks.

Write block_num blocks with size block_size to dev starting at block address block_addr from buffer data.

The starting block address is always specified as block address independent on the actual addressing scheme of used card. The driver takes care of mapping to byte addressing if needed.

If the parameter done is not NULL, the function returns the number of written blocks.

Warning
The buffer data may need to be word-aligned depending on CPU-specific requirements. sdmmc_buf_t or SDMMC_CPU_DMA_REQUIREMENTS have to be used to define the buffer:
...
SDMMC_CPU_DMA_REQUIREMENTS uint8_t buffer[SDMMC_SDHC_BLOCK_SIZE];
Note
sdmmc_card_init is called implicitly if necessary.
Precondition
dev and data must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]block_addrStart address to write to given as block address
[in]block_sizeBlock size dependent on card and mode used
  • 512 bytes for block-oriented transfers (SDSC V2.x/SDHC/SDXC)
  • 1, 2, 4, ... 4096 for block-oriented transfers (MMC)
  • 512, 1024, 2048 for block-oriented transfers (SDSC V1.x)
  • 1...512 bytes in byte/multibyte mode (SDIO only)
  • 0 in stream mode (MMC only)
[in]block_numNumber of blocks:
  • 1, ... for block-oriented transfers (SD and MMC)
  • 1 in byte/multibyte mode (SDIO only)
  • 0 in stream mode (MMC only)
[in]dataBuffer with data to write
[out]doneNumber of blocks written, can be NULL
Return values
0on success, block_num blocks were read successfully
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support a used command or is in wrong state
-EBUSYif card is busy
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EINVALon invalid transfer parameters
-EBADMSGon CRC7 error
-ENOMEMon TX FIFO underrun error
-EIOon not further specified error incl. hardware errors

◆ sdmmc_xfer()

int sdmmc_xfer ( sdmmc_dev_t dev,
sdmmc_cmd_t  cmd_idx,
uint32_t  arg,
uint16_t  block_size,
uint16_t  block_num,
const void *  data_wr,
void *  data_rd,
uint16_t *  done 
)

Perform a data transfer with the selected card or embedded device.

This high-level SDIO/SD/MMC device API function performs a read or write data transfer either

  • block-oriented with a number of blocks of the same size (SD and MMC)
  • as stream until the stop command (CMD12) is sent by the host (MMC only)
  • in byte or multi-byte mode (SDIO only)

The possible block sizes block_size depend on the card and mode used. For block-oriented data transfers, the block size is usually 512 bytes, but may differ for MMCs and SD Cards with Standard Capacity Version 1.x (SDSC):

  • MMC: block size can be 1, 2, 4, ..., 4096 bytes (as power of 2)
  • SDSC V1.x: block size can be 512, 1024 or 2048 bytes
  • SDSC V2.x and later, SDSC/SDHC: block size is 512 bytes

The block size for SDIO transfers in byte or multi-byte mode, if supported, can be in the range of 1 to 512 bytes. The number of blocks block_num MUST be 1 in this case.

For a data transfer as a stream, the block size block_size and the number of blocks block_num are 0.

Note
Some block-oriented data transfers such as reading the SD Card Configuration register (SCR) with ACMD51 may use the sdmmc_xfer function with smaller block size, for example only 8 bytes. The low-level SDIO/SD/MMC peripheral driver MUST support block sizes smaller than the usual block size used for block-oriented operations.

The sdmmc_xfer function uses the low-level SDIO/SD/MMC peripheral driver functions sdmmc_driver_t::xfer_prepare to prepare the data transfer, sdmmc_driver_t::xfer_execute to perform the data transfer, and sdmmc_driver_t::xfer_finish to complete the data transfer. In detail:

_wait_for_ready(dev);
if (cmd_idx & SDMMC_ACMD_PREFIX) {
}
dev->driver->xfer_prepare(dev, xfer);
sdmmc_send_cmd(dev, cmd_idx, ...);
dev->driver->xfer_execute(dev, xfer, ...);
if (block_num > 1) {
}
dev->driver->xfer_finish(dev, xfer);
@ SDMMC_CMD12
STOP_TRANSMISSION.
Definition: sdmmc.h:214

xfer is the transfer descriptor of type sdmmc_xfer_desc_t that contains all transfer parameters.

If the parameter done is not NULL, the function returns the number of transferred blocks.

Warning
The buffers specified by data_wr and data_rd may need to be word-aligned depending on CPU-specific requirements. sdmmc_buf_t or SDMMC_CPU_DMA_REQUIREMENTS have to be used to define such buffers:
...
SDMMC_CPU_DMA_REQUIREMENTS uint8_t buffer[SDMMC_SDHC_BLOCK_SIZE];
Note
sdmmc_card_init is called implicitly if necessary.
See also
sdmmc_driver_t::xfer_prepare, sdmmc_driver_t::xfer_execute and sdmmc_driver_t::xfer_finish
Precondition
dev must not be NULL.
data_rd must not be NULL for read transfers and data_wr must not be NULL for write transfers.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]cmd_idxCommand index or application specific command index
[in]argCommand argument
[in]block_sizeBlock size dependent on card and mode used
  • 512 bytes for block-oriented transfers (SDSC V2.x/SDHC/SDXC)
  • 1, 2, 4, ... 4096 for block-oriented transfers (MMC)
  • 512, 1024, 2048 for block-oriented transfers (SDSC V1.x)
  • 1...512 bytes in byte/multibyte mode (SDIO)
  • 0 in stream mode (SDIO)
[in]block_numNumber of blocks:
  • 1, ... for block-oriented transfers (SD Card/MMC)
  • 1 in byte/multibyte mode (SDIO)
  • 0 in stream mode (MMC)
[in]data_wrBuffer with data to write in write transfers, NULL otherwise
[out]data_rdBuffer for data to read in read transfers, NULL otherwise
[out]doneNumber of transferred blocks, can be NULL
Return values
0on success
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support a used command or is in wrong state
-EBUSYif card is busy
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EINVALon invalid transfer parameters
-EBADMSGon CRC7 error
-ENOMEMon RX FIFO overflow or TX FIFO underrun error
-EIOon not further specified error incl. hardware errors

Variable Documentation

◆ sdmmc_devs

sdmmc_dev_t sdmmc_devs[]

SDIO/SD/MMC device descriptor references as read-only XFA.

The array contains the references to all SDIO/SD/MMC device descriptors. The i-th device in this array can then be accessed with sdmmc_devs[i]. The number of SDIO/SD/MMC device descriptor references defined in this array is XFA_LEN(sdmmc_devs), see SDMMC_NUMOF.

Warning
To ensure to have the references to all SDIO/SD/MMC device descriptors in this array, the low-level SDIO/SD/MMC peripheral drivers must define the references to their SDIO/SD/MMC device descriptors as XFA members by using the macro XFA_CONST(sdmmc_devs, 0) as shown in the example below.

For example, if the low-level SDIO/SD/MMC peripheral driver defines an MCU-specific SDIO/SD/MMC device descriptor structure _mcu_sdmmc_dev_t and defines the device descriptors in an array _mcu_sdmmc_dev, it must define the references to them as members of the XFA sdmmc_devs as follows:

typedef struct {
sdmmc_dev_t sdmmc_dev; // Inherited sdmmc_dev_t struct
const sdmmc_conf_t *config; // SDIO/SD/MMC peripheral config
...
} _mcu_sdmmc_dev_t;
static _mcu_sdmmc_dev_t _mcu_sdmmc_devs[] = {
{
...
},
{
...
},
};
XFA_CONST(sdmmc_devs, 0) sdmmc_dev_t * const _sdmmc_1 = (sdmmc_dev_t * const)&_mcu_sdmmc_devs[0];
XFA_CONST(sdmmc_devs, 0) sdmmc_dev_t * const _sdmmc_2 = (sdmmc_dev_t * const)&_mcu_sdmmc_devs[1];
sdmmc_dev_t sdmmc_devs[]
SDIO/SD/MMC device descriptor references as read-only XFA.
Definition: sdmmc.h:1433
SDMMC slot configuration.
Definition: periph_cpu.h:704
SDIO/SD/MMC device descriptor.
Definition: sdmmc.h:1269
#define XFA_CONST(xfa_name, prio)
Define variable in read-only cross-file array.
Definition: xfa.h:158

Definition at line 1433 of file sdmmc.h.