- Generated on Thu Mar 27 2025 18:21:01 by
1.9.1
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:
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 |
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:
periph_sdmmc (HAS_PERIPH_SDMMC in Kconfig) indicates that an SDIO/SD/MMC peripheral is present and used by the board. This feature shall be provided by the board configuration.periph_sdmmc_8bit (HAS_PERIPH_SDMMC_8BIT in Kconfig) indicates that the SDIO/SD/MMC peripheral supports the 8-bit bus width and at least one component of the board is connected with 8 data lines. This feature shall be provided by the board configuration, if available.periph_sdmmc_auto_clk (HAS_PERIPH_SDMMC_AUTO_CLK in Kconfig) indicates that the SDIO/SD/MMC peripheral supports the Auto-CLK feature, i.e. the automatic activation and deactivation of the SD CLK signal when required to save power. This function shall be provided by the MCU if supported.periph_sdmmc_auto_cmd12 (HAS_PERIPH_SDMMC_AUTO_CMD12 in Kconfig) indicates that the SDIO/SD/MMC peripheral supports the Auto-CMD12 feature, i.e. CMD12 is sent automatically to stop the transmission in multiple block operations. This feature shall be provided by the MCU if supported.periph_sdmmc_hs (HAS_PERIPH_SDMMC_HS in Kconfig) indicates that the SDIO/SD/MMC peripheral supports the high speed access, that is 50 MHz for SD and 52 MHz for MMC. This feature shall be provided by the MCU if supported.periph_sdmmc_mmc (HAS_PERIPH_SDMMC_MMC in Kconfig) indicates that the SDIO/SD/MMC peripheral supports MMC/eMMCs. This feature shall be provided by the MCU if supported.Some functionalities of the SDIO/SD/MMC Device API must be explicitly enabled via modules:
sdmmc_mmc (MODULE_SDMMC_MMC in Kconfig) enables the support for MMCs/eMMCs.periph_sdmmc_8bit (MODULE_PERIPH_SDMMC_8BIT in Kconfig) enables the 8-bit bus width support. It requires the corresponding feature of the board. 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. | |
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. | |
Functions | |
| static sdmmc_dev_t * | sdmmc_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. | |
| #define | SDMMC_ACMD_PREFIX (1 << 7) |
| Application specific command index prefix (Bit is 7 used) | |
| #define | SDMMC_ACMD(n) (SDMMC_ACMD_PREFIX | SDMMC_CMD(n)) |
| Application specific command index. | |
| #define | SDMMC_CMD_NO_ARG (0x00000000UL) |
| Command argument if no argument is required. | |
| #define | SDMMC_CMD_ARG_RCA(n) ((uint32_t)n << 16) |
| Command argument if RCA is used in addressed commands. | |
| #define | SDMMC_RESP_CRC (1UL << 4) |
| Mask to check whether the response type uses CRC7. | |
| #define | SDMMC_RESP_BUSY (1UL << 5) |
| Mask to check whether the response includes busy status from card. | |
| #define | SDMMC_RESP_IDX (0xf) |
| Mask of response index. | |
SDIO/SD/MMC Card status as returned in responses R1 to CMD13 with b[15]=0 | |
| |
| 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. | |
| #define | SDMMC_CARD_STATUS_ADDRESS_ERROR (1UL << 30) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_BLOCK_LEN_ERROR (1UL << 29) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_ERASE_SEQ_ERROR (1UL << 28) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_ERASE_PARAM (1UL << 27) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_WP_VIOLATION (1UL << 26) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_CARD_IS_LOCKED (1UL << 25) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_LOCK_UNLOCK_FAILED (1UL << 24) |
| SD/SDIO and MMC. | |
| #define | SDMMC_CARD_STATUS_COM_CRC_ERROR (1UL << 23) |
| SD/SDIO and MMC. | |
| #define | SDMMC_CARD_STATUS_ILLEGAL_COMMAND (1UL << 22) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_CARD_ECC_FAILED (1UL << 21) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_CC_ERROR (1UL << 20) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_ERROR (1UL << 19) |
| SD/SDIO and MMC. | |
| #define | SDMMC_CARD_STATUS_UNDERRUN (1UL << 18) |
| MMC only. | |
| #define | SDMMC_CARD_STATUS_OVERRUN (1UL << 17) |
| MMC only. | |
| #define | SDMMC_CARD_STATUS_CSD_OVERWRITE (1UL << 16) |
| SD (CSD), MMC (CSD and CID) | |
| #define | SDMMC_CARD_STATUS_WP_ERASE_SKIP (1UL << 15) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_CARD_ECC_DISABLED (1UL << 14) |
| SD only. | |
| #define | SDMMC_CARD_STATUS_ERASE_RESET (1UL << 13) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_READY_FOR_DATA (1UL << 8) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_SWITCH_ERROR (1UL << 7) |
| MMC only. | |
| #define | SDMMC_CARD_STATUS_FX_EVENT (1UL << 6) |
| SD only. | |
| #define | SDMMC_CARD_STATUS_APP_CMD (1UL << 5) |
| SD and MMC. | |
| #define | SDMMC_CARD_STATUS_AKE_SEQ_ERROR (1UL << 3) |
| SD only. | |
| #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. | |
| #define | SDMMC_CARD_STATUS_CURRENT_STATE_Pos (9) |
| CURRENT_STATE position. | |
CSD Register Definitions | |
| |
| 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) | |
| #define | SDMMC_EXT_CSD_REG_SIZE (512) |
| Extended CSD (EXT_CSD) register size in byte (EXT_CSD is 512 byte) | |
Definitions used for CMD8 - SEND_IF_COND (SD only) | |
| |
| #define | SDMMC_CMD8_CHECK_PATTERN (0xaa) |
| Check pattern, 0xAA recommended. | |
| #define | SDMMC_CMD8_VHS_27_36V (0b0001 << 8) |
| Voltage Supplied by host 2.7-3.6V. | |
| #define | SDMMC_CMD8_PCIE_AVAIL (1 << 12) |
| PCIe Availability (not yet used) | |
| #define | SDMMC_CMD8_PCIE_12V (1 << 13) |
| PCIe 1.2V Support (not yet used) | |
| #define | SDMMC_CMD8_CHECK (SDMMC_CMD8_VHS_27_36V | SDMMC_CMD8_CHECK_PATTERN) |
| Command argument used in CMD8. | |
OCR Register Definition | |
| |
| #define | SDMMC_OCR_18V (1UL << 7) |
| Low Voltage Range. | |
| #define | SDMMC_OCR_27_28V (1UL << 15) |
| 2.7V to 2.8V Range | |
| #define | SDMMC_OCR_28_29V (1UL << 16) |
| 2.8V to 2.9V Range | |
| #define | SDMMC_OCR_29_30V (1UL << 17) |
| 2.9V to 3.0V Range | |
| #define | SDMMC_OCR_30_31V (1UL << 18) |
| 3.0V to 3.1V Range | |
| #define | SDMMC_OCR_31_32V (1UL << 19) |
| 3.1V to 3.2V Range | |
| #define | SDMMC_OCR_32_33V (1UL << 20) |
| 3.2V to 3.3V Range | |
| #define | SDMMC_OCR_33_34V (1UL << 21) |
| 3.3V to 3.4V Range | |
| #define | SDMMC_OCR_34_35V (1UL << 22) |
| 3.4V to 3.5V Range | |
| #define | SDMMC_OCR_35_36V (1UL << 23) |
| 3.5V to 3.6V Range | |
| #define | SDMMC_OCR_S18A (1UL << 24) |
| Switching to 1.8V Accepted. | |
| #define | SDMMC_OCR_OVER_2TB (1UL << 27) |
| Over 2TB support status (CO2T) | |
| #define | SDMMC_OCR_UHS_II (1UL << 29) |
| UHS-II Card Status. | |
| #define | SDMMC_OCR_CCS (1UL << 30) |
| Card Capacity Status (CCS) | |
| #define | SDMMC_OCR_POWER_UP (1UL << 31) |
| Card power up status bit (busy) | |
| #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. | |
CID register (SD Memory and MMC Cards) | |
| #define | SDMMC_CID_REG_SIZE (16) |
| CID register size in bytes (CID is 128 bit) | |
| #define | SDMMC_CID_OID_SIZE_SD (2) |
| OID (OEM/Application ID) size in byte (SD) | |
| #define | SDMMC_CID_PNM_SIZE_SD (5) |
| PNM (Product name) size in byte (SD) | |
| #define | SDMMC_CID_PNM_SIZE_MMC (6) |
| PNM (Product name) size in byte (MMC) | |
SCR Register Definitions (SD Memory Card only) | |
| |
| #define | SDMMC_SCR_REG_SIZE (8) |
| SCR register size in byte (SCR is 64 bit) | |
| #define | SDMMC_SCR_ACMD_53_54_SUPPORT (0b10000) |
| sdmmc_scr_t::CMD_SUPPORT Secure Receive/Send supported | |
| #define | SDMMC_SCR_ACMD_58_59_SUPPORT (0b01000) |
| sdmmc_scr_t::CMD_SUPPORT Extension Register Multi-Block | |
| #define | SDMMC_SCR_ACMD_48_49_SUPPORT (0b00100) |
| sdmmc_scr_t::CMD_SUPPORT Extension Register Single-Block | |
| #define | SDMMC_SCR_ACMD_23_SUPPORT (0b00010) |
| sdmmc_scr_t::CMD_SUPPORT Set Block Count | |
| #define | SDMMC_SCR_ACMD_20_SUPPORT (0b00001) |
| sdmmc_scr_t::CMD_SUPPORT Speed Class Control | |
| #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. | |
| #define sdmmc_buf_t SDMMC_CPU_DMA_REQUIREMENTS uint8_t |
Instantiation type for SDIO/SD/MMC buffers.
Example usage:
| #define SDMMC_CARD_STATUS_ERRORS |
SD/MMC Card status mask for error flags.
| #define SDMMC_CARD_TYPE_SD |
Mask for any type of SD Memory card.
| #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:
| #define SDMMC_OCR_ALL_VOLTAGES |
Voltage profile for the range 2.7-3.6V as defined for MMC.
| #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.
| scr | SCR 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 |
| #define SDMMC_SDHC_BLOCK_SIZE (512) |
| 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.
| typedef void(* sdmmc_event_cb_t) (sdmmc_dev_t *dev, sdmmc_event_t event) |
Event callback function type.
| [in] | dev | SDIO/SD/MMC device to be used |
| [in] | event | Event |
thread_flags, event_queue or msg mechanism to inform a thread about the event, which then handles the event asynchronously in thread context. | anonymous enum |
SD/MMC Card states.
| enum 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.
| enum 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.
| 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. |
| enum 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+.
| enum 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.
| enum 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.
| enum sdmmc_csd_version_t |
| enum sdmmc_resp_t |
SDIO/SD/MMC Response types.
| 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 |
| enum sdmmc_xfer_type_t |
| 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:
Identified card types are:
NULL and to use the default procedure implemented by sdmmc_send_acmd.dev must not be NULL.| [in] | dev | SDIO/SD/MMC device to be used |
| 0 | on success |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card is not supported or can't operate under supplied voltage |
| -EFAULT | on card status error |
| -ETIMEDOUT | on card initialization and identification timeout |
| -EBADMSG | on CRC7 error |
| -EIO | on not further specified error incl. hardware errors |
| 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.
-ENOTSUP error.dev must not be NULL. block_num has to be greater than 0.| [in] | dev | SD/MMC device to be used |
| [in] | block_addr | Start address for erase given as block address |
| [in] | block_num | Number of blocks to be erased |
| 0 | on success, block_num blocks were erased successfully |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card does not support erase operation or a command used |
| -EBUSY | if card is busy |
| -EFAULT | on card status error |
| -ETIMEDOUT | on timeout condition |
| -EBADMSG | on CRC7 error in response |
| -EINVAL | on invalid erase parameters |
| -EIO | on not further specified error incl. hardware errors |
| uint64_t sdmmc_get_capacity | ( | sdmmc_dev_t * | dev | ) |
Get Capacity of SD/MMC Card.
Get the capacity of a SD/MMC Card device.
-ENOTSUP error.dev must not be NULL.| [in] | dev | SD/MMC device to be used |
|
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.
| [in] | num | SDIO/SD/MMC peripheral index |
| pointer | to the SDIO/SD/MMC device descriptor at index num on success |
| NULL | if num is greater than the number of SDIO/SD/MMC device descriptors |
|
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().
dev must not be NULL.| [in] | dev | SDIO/SD/MMC device to initialize |
| 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.
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: dev and data must not be NULL.| [in] | dev | SDIO/SD/MMC device to be used |
| [in] | block_addr | Start address to read from given as block address |
| [in] | block_size | Block size dependent on card and mode used
|
| [in] | block_num | Number of blocks:
|
| [out] | data | Buffer for read data |
| [out] | done | Number of read blocks, can be NULL |
| 0 | on success, block_num blocks were read successfully |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card does not support a used command or is in wrong state |
| -EBUSY | if card is busy |
| -EFAULT | on card status error |
| -ETIMEDOUT | on timeout condition |
| -EINVAL | on invalid transfer parameters |
| -EBADMSG | on CRC7 error |
| -ENOMEM | on RX FIFO overflow error |
| -EIO | on not further specified error incl. hardware errors |
| 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.
-ENOTSUP error.dev and sds must not be NULL.| [in] | dev | SD device to be used |
| [out] | sds | SD Status register content |
| 0 | on success |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card does not support the operation |
| -EBUSY | if card is busy |
| -EFAULT | on card status error |
| -ETIMEDOUT | on timeout condition |
| -EINVAL | on invalid transfer parameters |
| -EBADMSG | on CRC7 error |
| -ENOMEM | on RX FIFO overflow error |
| -EIO | on not further specified error incl. hardware errors |
| 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:
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 NULLresp_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.
0b111111. The low-level SDIO/SD/MMC peripheral driver must not check the CRC field for this response.dev must not be NULL. cmd_idx must be in range 0 to 63.| [in] | dev | SDIO/SD/MMC device to be used |
| [in] | cmd_idx | Command index of an application specific command |
| [in] | arg | Command argument |
| [in] | resp_type | Type of response expected |
| [out] | resp | Buffer of 32-bit words to store the response |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card does not support the command or is in wrong state |
| -EFAULT | on card status error |
| -ETIMEDOUT | on timeout condition |
| -EBADMSG | on CRC7 error in response |
| -EIO | on not further specified error incl. hardware errors |
| 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.
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 NULLresp_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.
0b111111. The low-level SDIO/SD/MMC peripheral driver must not check the CRC field for this response.dev must not be NULL.| [in] | dev | SDIO/SD/MMC device to be used |
| [in] | cmd_idx | Command index |
| [in] | arg | Command argument |
| [in] | resp_type | Type of response expected |
| [out] | resp | Buffer of 32-bit words to store the response if needed, otherwise NULL |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card does not support the command or is in wrong state |
| -EFAULT | on card status error |
| -ETIMEDOUT | on timeout condition |
| -EBADMSG | on CRC7 error in response |
| -EIO | on not further specified error incl. hardware errors |
| 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.
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: dev and data must not be NULL.| [in] | dev | SDIO/SD/MMC device to be used |
| [in] | block_addr | Start address to write to given as block address |
| [in] | block_size | Block size dependent on card and mode used
|
| [in] | block_num | Number of blocks:
|
| [in] | data | Buffer with data to write |
| [out] | done | Number of blocks written, can be NULL |
| 0 | on success, block_num blocks were read successfully |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card does not support a used command or is in wrong state |
| -EBUSY | if card is busy |
| -EFAULT | on card status error |
| -ETIMEDOUT | on timeout condition |
| -EINVAL | on invalid transfer parameters |
| -EBADMSG | on CRC7 error |
| -ENOMEM | on TX FIFO underrun error |
| -EIO | on not further specified error incl. hardware errors |
| 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
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):
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.
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:
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.
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: dev must not be NULL. data_rd must not be NULL for read transfers and data_wr must not be NULL for write transfers.| [in] | dev | SDIO/SD/MMC device to be used |
| [in] | cmd_idx | Command index or application specific command index |
| [in] | arg | Command argument |
| [in] | block_size | Block size dependent on card and mode used
|
| [in] | block_num | Number of blocks:
|
| [in] | data_wr | Buffer with data to write in write transfers, NULL otherwise |
| [out] | data_rd | Buffer for data to read in read transfers, NULL otherwise |
| [out] | done | Number of transferred blocks, can be NULL |
| 0 | on success |
| -ENODEV | if card is not present or not usable |
| -ENOTSUP | if card does not support a used command or is in wrong state |
| -EBUSY | if card is busy |
| -EFAULT | on card status error |
| -ETIMEDOUT | on timeout condition |
| -EINVAL | on invalid transfer parameters |
| -EBADMSG | on CRC7 error |
| -ENOMEM | on RX FIFO overflow or TX FIFO underrun error |
| -EIO | on not further specified error incl. hardware errors |
| 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.
XFA_CONST(sdmmc_dev_t *, 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:
1.9.1