sdmmc.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2023 Gunar Schorcht
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once

 
#include <errno.h>
 
#include "assert.h"
#include "byteorder.h"
#include "macros/units.h"
#include "periph_conf.h"
#include "xfa.h"
 
#ifdef __cplusplus
extern "C" {
#endif

#ifndef SDMMC_CPU_DMA_REQUIREMENTS
#define SDMMC_CPU_DMA_REQUIREMENTS
#endif

#define sdmmc_buf_t     SDMMC_CPU_DMA_REQUIREMENTS uint8_t

#define SDMMC_SDHC_BLOCK_SIZE   (512)


#define SDMMC_CMD(n)        (n)

#define SDMMC_ACMD_PREFIX   (1 << 7)

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

typedef enum {
    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), 
} sdmmc_cmd_t;

#define SDMMC_CMD_NO_ARG        (0x00000000UL)

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

#define SDMMC_RESP_CRC          (1UL << 4)
#define SDMMC_RESP_BUSY         (1UL << 5)
#define SDMMC_RESP_IDX          (0xf)

typedef enum {
    SDMMC_NO_R = 0,                     
    SDMMC_R1  = 1 | SDMMC_RESP_CRC,     
    SDMMC_R1B = 1 | SDMMC_RESP_CRC
                  | SDMMC_RESP_BUSY,    
    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,     
} sdmmc_resp_t;


 
#define SDMMC_CMD8_CHECK_PATTERN    (0xaa)          
#define SDMMC_CMD8_VHS_27_36V       (0b0001 << 8)   
#define SDMMC_CMD8_PCIE_AVAIL       (1 << 12)       
#define SDMMC_CMD8_PCIE_12V         (1 << 13)       

#define SDMMC_CMD8_CHECK  (SDMMC_CMD8_VHS_27_36V | SDMMC_CMD8_CHECK_PATTERN)

#define SDMMC_OCR_18V           (1UL << 7)  
#define SDMMC_OCR_27_28V        (1UL << 15) 
#define SDMMC_OCR_28_29V        (1UL << 16) 
#define SDMMC_OCR_29_30V        (1UL << 17) 
#define SDMMC_OCR_30_31V        (1UL << 18) 
#define SDMMC_OCR_31_32V        (1UL << 19) 
#define SDMMC_OCR_32_33V        (1UL << 20) 
#define SDMMC_OCR_33_34V        (1UL << 21) 
#define SDMMC_OCR_34_35V        (1UL << 22) 
#define SDMMC_OCR_35_36V        (1UL << 23) 
 
#define SDMMC_OCR_S18A          (1UL << 24) 
#define SDMMC_OCR_OVER_2TB      (1UL << 27) 
#define SDMMC_OCR_UHS_II        (1UL << 29) 
#define SDMMC_OCR_CCS           (1UL << 30) 
#define SDMMC_OCR_POWER_UP      (1UL << 31) 

#define SDMMC_OCR_ALL_VOLTAGES  (SDMMC_OCR_27_28V | SDMMC_OCR_28_29V | \
                                 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)


typedef enum {
    SDMMC_CARD_TYPE_UNKNOWN = 0x00,    
    SDMMC_CARD_TYPE_SDSC_V1 = 0x01,    
    SDMMC_CARD_TYPE_SDSC_V2_V3 = 0x02, 
    SDMMC_CARD_TYPE_SDHC_SDXC = 0x04,  
    /* bits 3..5 are left unused for later extensions of SD Memory Card types */
    SDMMC_CARD_TYPE_SDIO = 0x40,       
    SDMMC_CARD_TYPE_MMC = 0x80,        
} sdmmc_card_type_t;

#define SDMMC_CARD_TYPE_SD  (SDMMC_CARD_TYPE_SDSC_V1 | \
                             SDMMC_CARD_TYPE_SDSC_V2_V3 | \
                             SDMMC_CARD_TYPE_SDHC_SDXC)

typedef enum {
    SDMMC_BUS_WIDTH_1BIT = 1,   
    SDMMC_BUS_WIDTH_4BIT = 4,   
    SDMMC_BUS_WIDTH_8BIT = 8,   
} sdmmc_bus_width_t;

typedef enum {
    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),  
} sdmmc_clock_rate_t;

#define SDMMC_CARD_STATUS_OUT_OF_RANGE          (1UL << 31)     
#define SDMMC_CARD_STATUS_ADDRESS_ERROR         (1UL << 30)     
#define SDMMC_CARD_STATUS_BLOCK_LEN_ERROR       (1UL << 29)     
#define SDMMC_CARD_STATUS_ERASE_SEQ_ERROR       (1UL << 28)     
#define SDMMC_CARD_STATUS_ERASE_PARAM           (1UL << 27)     
#define SDMMC_CARD_STATUS_WP_VIOLATION          (1UL << 26)     
#define SDMMC_CARD_STATUS_CARD_IS_LOCKED        (1UL << 25)     
#define SDMMC_CARD_STATUS_LOCK_UNLOCK_FAILED    (1UL << 24)     
#define SDMMC_CARD_STATUS_COM_CRC_ERROR         (1UL << 23)     
#define SDMMC_CARD_STATUS_ILLEGAL_COMMAND       (1UL << 22)     
#define SDMMC_CARD_STATUS_CARD_ECC_FAILED       (1UL << 21)     
#define SDMMC_CARD_STATUS_CC_ERROR              (1UL << 20)     
#define SDMMC_CARD_STATUS_ERROR                 (1UL << 19)     
#define SDMMC_CARD_STATUS_UNDERRUN              (1UL << 18)     
#define SDMMC_CARD_STATUS_OVERRUN               (1UL << 17)     
#define SDMMC_CARD_STATUS_CSD_OVERWRITE         (1UL << 16)     
#define SDMMC_CARD_STATUS_WP_ERASE_SKIP         (1UL << 15)     
#define SDMMC_CARD_STATUS_CARD_ECC_DISABLED     (1UL << 14)     
#define SDMMC_CARD_STATUS_ERASE_RESET           (1UL << 13)     
#define SDMMC_CARD_STATUS_READY_FOR_DATA        (1UL << 8)      
#define SDMMC_CARD_STATUS_SWITCH_ERROR          (1UL << 7)      
#define SDMMC_CARD_STATUS_FX_EVENT              (1UL << 6)      
#define SDMMC_CARD_STATUS_APP_CMD               (1UL << 5)      
#define SDMMC_CARD_STATUS_AKE_SEQ_ERROR         (1UL << 3)      

#define SDMMC_CARD_STATUS_ERRORS   (SDMMC_CARD_STATUS_OUT_OF_RANGE | \
                                    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_CURRENT_STATE(n)  (((n) >> SDMMC_CARD_STATUS_CURRENT_STATE_Pos) & 0x0f)
#define SDMMC_CARD_STATUS_CURRENT_STATE_Pos (9) 

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,      
};

typedef union {
    struct {
        uint32_t reserved0         :2;  
        uint32_t reserved2         :1;  
        uint32_t AKE_SEQ_ERROR     :1;  
        uint32_t reserved4         :1;  
        uint32_t APP_CMD           :1;  
        uint32_t FX_EVENT          :1;  
        uint32_t SWITCH_ERROR      :1;  
        uint32_t READY_FOR_DATA    :1;  
        uint32_t CURRENT_STATE     :4;  
        uint32_t ERASE_RESET       :1;  
        uint32_t CARD_ECC_DISABLED :1;  
        uint32_t WP_ERASE_SKIP     :1;  
        uint32_t CSD_OVERWRITE     :1;  
        uint32_t OVERRUN           :1;  
        uint32_t UNDERRUN          :1;  
        uint32_t ERROR             :1;  
        uint32_t CC_ERROR          :1;  
        uint32_t CARD_ECC_FAILED   :1;  
        uint32_t ILLEGAL_COMMAND   :1;  
        uint32_t COM_CRC_ERROR     :1;  
        uint32_t LOCK_UNLOCK_FAILED:1;  
        uint32_t CARD_IS_LOCKED    :1;  
        uint32_t WP_VIOLATION      :1;  
        uint32_t ERASE_PARAM       :1;  
        uint32_t ERASE_SEQ_ERROR   :1;  
        uint32_t BLOCK_LEN_ERROR   :1;  
        uint32_t ADDRESS_ERROR     :1;  
        uint32_t OUT_OF_RANGE      :1;  
    };
    uint32_t value; 
} sdmmc_card_status_t;



#define SDMMC_SD_STATUS_SIZE    (64)

typedef struct __attribute__((packed)) {
    uint32_t SIZE_OF_PROTECTED_AREA:32; 
    uint32_t SUS_ADDR:22;               
    uint32_t VSC_AU_SIZE:10;            
    uint16_t SD_CARD_TYPE:16;           
    uint16_t ERASE_SIZE:16;             
    uint8_t  SPEED_CLASS:8;             
    uint8_t  PERFORMANCE_MOVE:8;        
    uint8_t  VIDEO_SPEED_CLASS:8;       
    uint8_t  ERASE_TIMEOUT:6;           
    uint8_t  ERASE_OFFSET:2;            
    uint8_t  UHS_SPEED_GRADE:4;         
    uint8_t  UHS_AU_SIZE:4;             
    uint8_t  AU_SIZE:4;                 
    uint8_t  DAT_BUS_WIDTH:2;           
    uint8_t  SECURED_MODE:1;            
} sdmmc_sd_status_t;



#define SDMMC_CID_REG_SIZE      (16)
 
#define SDMMC_CID_OID_SIZE_SD   (2)   
#define SDMMC_CID_PNM_SIZE_SD   (5)   
#define SDMMC_CID_PNM_SIZE_MMC  (6)   

typedef struct __attribute__((packed)) {
    uint8_t MID;                      
    char OID[SDMMC_CID_OID_SIZE_SD];  
    char PNM[SDMMC_CID_PNM_SIZE_SD];  
    uint8_t PRV;                      
    be_uint32_t PSN;                  
    be_uint16_t MDT;                  
    uint8_t CID_CRC;                  
} sdmmc_cid_sd_t;

typedef struct __attribute__((packed)) {
    uint8_t MID;                      
    be_uint16_t OID;                  
    char PNM[SDMMC_CID_PNM_SIZE_MMC]; 
    uint8_t PRV;                      
    be_uint32_t PSN;                  
    uint8_t MDT;                      
    uint8_t CID_CRC;                  
} sdmmc_cid_mmc_t;

typedef union {
    sdmmc_cid_sd_t  sd;     
    sdmmc_cid_mmc_t mmc;    
} sdmmc_cid_t;



typedef enum {
    SDMMC_CSD_V1 = 0,   
    SDMMC_CSD_V2 = 1,   
    SDMMC_CSD_V3 = 2,   
    SDMMC_CSD_Vx = 3,   
} sdmmc_csd_version_t;

#define SDMMC_CSD_REG_SIZE  (16)

typedef struct __attribute__((packed)) {
    uint32_t CSD_CRC:8;             
    uint32_t reserved5:1;           
    uint32_t WP_UPC:1;              
    uint32_t FILE_FORMAT:2;         
    uint32_t TMP_WRITE_PROTECT:1;   
    uint32_t PERM_WRITE_PROTECT:1;  
    uint32_t COPY:1;                
    uint32_t FILE_FORMAT_GRP:1;     
    uint32_t reserved4:5;           
    uint32_t WRITE_BL_PARTIAL:1;    
    uint32_t WRITE_BL_LEN:4;        
    uint32_t R2W_FACTOR:3;          
    uint32_t reserved3:2;           
    uint32_t WP_GRP_ENABLE:1;       
    uint32_t WP_GRP_SIZE:7;         
    uint32_t SECTOR_SIZE:7;         
    uint32_t ERASE_BLK_EN:1;        
    uint32_t C_SIZE_MULT:3;         
    uint32_t VDD_W_CURR_MAX:3;      
    uint32_t VDD_W_CURR_MIN:3;      
    uint32_t VDD_R_CURR_MAX:3;      
    uint32_t VDD_R_CURR_MIN:3;      
    uint32_t C_SIZE:12;             
    uint32_t reserved2:2;           
    uint32_t DSR_IMP:1;             
    uint32_t READ_BLK_MISALIGN:1;   
    uint32_t WRITE_BLK_MISALIGN:1;  
    uint32_t READ_BL_PARTIAL:1;     
    uint32_t READ_BL_LEN:4;         
    uint32_t CCC:12;                
    uint32_t TRAN_SPEED:8;          
    uint32_t NSAC:8;                
    uint32_t TAAC:8;                
    uint32_t reserved1:6;           
    uint32_t CSD_STRUCTURE:2;       
} sdmmc_csd_v1_t;

typedef struct __attribute__((packed)) {
    uint32_t CSD_CRC:8;             
    uint32_t reserved5:1;           
    uint32_t WP_UPC:1;              
    uint32_t FILE_FORMAT:2;         
    uint32_t TMP_WRITE_PROTECT:1;   
    uint32_t PERM_WRITE_PROTECT:1;  
    uint32_t COPY:1;                
    uint32_t FILE_FORMAT_GRP:1;     
    uint32_t reserved4:5;           
    uint32_t WRITE_BL_PARTIAL:1;    
    uint32_t WRITE_BL_LEN:4;        
    uint32_t R2W_FACTOR:3;          
    uint32_t reserved3:2;           
    uint32_t WP_GRP_ENABLE:1;       
    uint32_t WP_GRP_SIZE:7;         
    uint32_t SECTOR_SIZE:7;         
    uint32_t ERASE_BLK_EN:1;        
    uint32_t reserved2:1;           
    uint32_t C_SIZE:28;             
    uint32_t DSR_IMP:1;             
    uint32_t READ_BLK_MISALIGN:1;   
    uint32_t WRITE_BLK_MISALIGN:1;  
    uint32_t READ_BL_PARTIAL:1;     
    uint32_t READ_BL_LEN:4;         
    uint32_t CCC:12;                
    uint32_t TRAN_SPEED:8;          
    uint32_t NSAC:8;                
    uint32_t TAAC:8;                
    uint32_t reserved1:6;           
    uint32_t CSD_STRUCTURE:2;       
} sdmmc_csd_v2_t;

typedef struct __attribute__((packed)) {
    uint32_t CSD_CRC:8;             
    uint32_t ECC:2;                 
    uint32_t FILE_FORMAT:2;         
    uint32_t TMP_WRITE_PROTECT:1;   
    uint32_t PERM_WRITE_PROTECT:1;  
    uint32_t COPY:1;                
    uint32_t FILE_FORMAT_GRP:1;     
    uint32_t CONTENT_PROT_APP:1;    
    uint32_t reserved4:4;           
    uint32_t WRITE_BL_PARTIAL:1;    
    uint32_t WRITE_BL_LEN:4;        
    uint32_t R2W_FACTOR:3;          
    uint32_t DEFAULT_ECC:2;         
    uint32_t WP_GRP_ENABLE:1;       
    uint32_t WP_GRP_SIZE:5;         
    uint32_t ERASE_GRP_MULT:5;      
    uint32_t ERASE_GRP_SIZE:5;      
    uint32_t C_SIZE_MULT:3;         
    uint32_t VDD_W_CURR_MAX:3;      
    uint32_t VDD_W_CURR_MIN:3;      
    uint32_t VDD_R_CURR_MAX:3;      
    uint32_t VDD_R_CURR_MIN:3;      
    uint16_t C_SIZE:12;             
    uint32_t reserved2:2;           
    uint32_t DSR_IMP:1;             
    uint32_t READ_BLK_MISALIGN:1;   
    uint32_t WRITE_BLK_MISALIGN:1;  
    uint32_t READ_BL_PARTIAL:1;     
    uint32_t READ_BL_LEN:4;         
    uint32_t CCC:12;                
    uint32_t TRAN_SPEED:8;          
    uint32_t NSAC:8;                
    uint32_t TAAC:8;                
    uint32_t reserved1:2;           
    uint32_t SPEC_VERS:4;           
    uint32_t CSD_STRUCTURE:2;       
} sdmmc_csd_mmc_t;

typedef union {
    sdmmc_csd_v1_t v1;      
    sdmmc_csd_v2_t v2;      
    sdmmc_csd_mmc_t mmc;    
} sdmmc_csd_t;

#define SDMMC_EXT_CSD_REG_SIZE  (512)

typedef struct {
    uint32_t SEC_COUNT;                 
    uint8_t CARD_TYPE;                  
    uint8_t CSD_STRUCTURE;              
    uint8_t BUS_WIDTH;                  
} sdmmc_ext_csd_t;



#define SDMMC_SCR_REG_SIZE          (8)

typedef struct {
    /* first 32-bit word */
    uint32_t reserved0;                 
    /* second 32-bit word */
    union {
        struct {
            uint32_t CMD_SUPPORT:5;             
            uint32_t reserved37:1;              
            uint32_t SD_SPECX:4;                
            uint32_t SD_SPEC4:1;                
            uint32_t EX_SECURITY:4;             
            uint32_t SD_SPEC3:1;                
            uint32_t SD_BUS_WIDTHS:4;           
            uint32_t SD_SECURITY:3;             
            uint32_t DATA_STAT_AFTER_ERASE:1;   
            uint32_t SD_SPEC:4;                 
            uint32_t SCR_STRUCTURE:4;           
        };
        uint32_t value;
    };
} sdmmc_scr_t;
 
#define SDMMC_SCR_ACMD_53_54_SUPPORT    (0b10000)   
#define SDMMC_SCR_ACMD_58_59_SUPPORT    (0b01000)   
#define SDMMC_SCR_ACMD_48_49_SUPPORT    (0b00100)   
#define SDMMC_SCR_ACMD_23_SUPPORT       (0b00010)   
#define SDMMC_SCR_ACMD_20_SUPPORT       (0b00001)   

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


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

typedef struct sdmmc_dev sdmmc_dev_t;

typedef enum {
    SDMMC_MULTIBYTE, 
    SDMMC_BLOCK,     
    SDMMC_STREAM,    
} sdmmc_xfer_type_t;

typedef struct {
    sdmmc_xfer_type_t type;     
    bool write;                 
    sdmmc_cmd_t cmd_idx;        
    sdmmc_resp_t resp_type;     
    uint32_t arg;               
    uint16_t block_size;        
    uint16_t block_num;         
} sdmmc_xfer_desc_t;

typedef enum {
    SDMMC_AUTO_CMD_NONE = 0x00,
    SDMMC_AUTO_CMD12 = 0x01,
    SDMMC_AUTO_CMD23 = 0x02,
    SDMMC_AUTO_CMD_BOTH = 0x03,
} sdmmc_auto_cmd_t;

typedef enum {
    SDMMC_EVENT_CARD_INSERTED,
    SDMMC_EVENT_CARD_REMOVED,
} sdmmc_event_t;

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

typedef struct {
    void (*init)(sdmmc_dev_t *dev);

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

    int (*card_init)(sdmmc_dev_t *dev);

    int (*set_bus_width)(sdmmc_dev_t *dev, sdmmc_bus_width_t width);

    int (*set_clock_rate)(sdmmc_dev_t *dev, sdmmc_clock_rate_t rate);
 
#if !IS_USED(MODULE_PERIPH_SDMMC_AUTO_CLK) || DOXYGEN
    int (*enable_clock)(sdmmc_dev_t *dev, bool enable);
#endif

    int (*xfer_prepare)(sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer);

    int (*xfer_execute)(sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer,
                        const void *data_wr, void *data_rd,
                        uint16_t *done);

    int (*xfer_finish)(sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer);
 
} sdmmc_driver_t;

typedef struct sdmmc_dev {
    const sdmmc_driver_t *driver;

    sdmmc_event_cb_t event_cb;

    sdmmc_cid_t cid;

    sdmmc_scr_t scr;

    sdmmc_csd_t csd;
 
#if IS_USED(MODULE_SDMMC_MMC)
    sdmmc_ext_csd_t ext_csd;
#endif

    uint32_t status;

    uint16_t rca;

    sdmmc_card_type_t type;

    sdmmc_bus_width_t bus_width;

    bool present;

    bool init_done;

    bool s18v_support;

    bool s18v_allowed;

    bool spi_mode;
 
} sdmmc_dev_t;

#if !DOXYGEN
XFA_USE_CONST(sdmmc_dev_t * const, sdmmc_devs);
#else
sdmmc_dev_t sdmmc_devs[];
#endif

#define SDMMC_NUMOF   XFA_LEN(sdmmc_dev_t *, sdmmc_devs)

static inline sdmmc_dev_t *sdmmc_get_dev(unsigned num)
{
    return (num < SDMMC_NUMOF) ? sdmmc_devs[num] : NULL;
}

static inline void sdmmc_init(sdmmc_dev_t *dev)
{
    assert(dev);
    assert(dev->driver);
 
    dev->driver->init(dev);
}

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

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

int sdmmc_card_init(sdmmc_dev_t *dev);

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

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

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

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

int sdmmc_read_sds(sdmmc_dev_t *dev, sdmmc_sd_status_t *sds);

uint64_t sdmmc_get_capacity(sdmmc_dev_t *dev);

 
#ifdef __cplusplus
}
#endif