mmcsd/v1/mmcsd.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2022 Texas Instruments Incorporated
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *    Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 *    Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the
 *    distribution.
 *
 *    Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef MMCSD_H_
#define MMCSD_H_
 
/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
 
#include <stdint.h>
#include <kernel/dpl/SystemP.h>
#include <kernel/dpl/SemaphoreP.h>
#include <kernel/dpl/HwiP.h>
#include <drivers/hw_include/csl_types.h>
#include <drivers/hw_include/cslr_mmcsd.h>
#include <drivers/hw_include/hw_types.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
#define MMCSD_CARD_SD                   (0U)
 
#define MMCSD_CARD_MMC                  (1U)
 
#define MMCSD_CARD_EMMC                 (2U)
 
/* useful in cases where SoC has MMCSD IP but no device attached to peripheral */
#define MMCSD_CARD_TYPE_NO_DEVICE       (3U)
 
#define MMCSD_CMD_SETBUSWIDTH        (MMCSD_CMD_RESERVED + 0U)
 
#define MMCSD_CMD_SETFREQUENCY       (MMCSD_CMD_RESERVED + 1U)
 
#define MMCSD_CMD_GETBUSWIDTH        (MMCSD_CMD_RESERVED + 2U)
 
#define MMCSD_CMD_GETFREQUENCY       (MMCSD_CMD_RESERVED + 3U)
 
#define MMCSD_CMD_GETMEDIAPARAMS     (MMCSD_CMD_RESERVED + 4U)
 
#define MMCSD_INVALID_MUXNUM            (-1)
 
#define MMCSD_INVALID_MUX_EVENTNUM      (-1)
 
#define MMCSD_BUS_WIDTH_1BIT            (1U)
 
#define MMCSD_BUS_WIDTH_4BIT            (4U)
 
#define MMCSD_BUS_WIDTH_8BIT            (8U)
 
#define MMCSD_TRANSPEED_25MBPS          (0x32U)
 
#define MMCSD_TRANSPEED_50MBPS          (0x5AU)
 
#define MMCSD_TRANSPEED_DEFAULT         (0x32U)
 
#define MMCSD_TRANSPEED_HS              (0x5AU)
 
#define MMCSD_TRANSPEED_SDR12           (0x32U)
 
#define MMCSD_TRANSPEED_SDR25           (0x5AU)
 
#define MMCSD_TRANSPEED_SDR50           (0xBU)
 
#define MMCSD_TRANSPEED_SDR104          (0x2BU)
 
#define MMCSD_TRANSPEED_DDR50           (0x3BU)
 
#define MMCSD_TRANSPEED_HS200           (0x2BU)
 
#define MMCSD_LOOPBACK_ANY              (0x0U)
 
#define MMCSD_LOOPBACK_INTERNAL         (0x1U)
 
#define MMCSD_LOOPBACK_PAD              (0x2U)
 
#define MMCSD_VOLTAGE_ANY               (0x0U)
 
 
typedef void* MMCSD_Handle;
 
/* ========================================================================== */
/*                         Structures and Enums                               */
/* ========================================================================== */
typedef enum hsMmcsdResetLineMask
{
    MMCSD_RESET_LINE_MASK_DATA  = CSL_MMC_SYSCTL_SRD_MASK,
    MMCSD_RESET_LINE_MASK_CMD = CSL_MMC_SYSCTL_SRC_MASK,
    MMCSD_RESET_LINE_MASK_ALL  = CSL_MMC_SYSCTL_SRA_MASK
}MMCSD_resetLineMask;
 
typedef enum MMCSD_clkAct_t
{
    MMCSD_CLK_ACT_ICLK_FCLK_OFF = CSL_MMC_SYSCONFIG_CLOCKACTIVITY_NONE,
    MMCSD_CLK_ACT_FCLK_OFF = CSL_MMC_SYSCONFIG_CLOCKACTIVITY_FUNC,
    MMCSD_CLK_ACT_ICLK_OFF = CSL_MMC_SYSCONFIG_CLOCKACTIVITY_OCP,
    MMCSD_CLK_ACT_ICLK_FLCK_ON  = CSL_MMC_SYSCONFIG_CLOCKACTIVITY_BOTH
}MMCSD_clkAct;
 
typedef enum MMCSD_standbyMode_t
{
    MMCSD_STANDBY_MODE_FORCE = CSL_MMC_SYSCONFIG_STANDBYMODE_FORCE,
    MMCSD_STANDBY_MODE_NONE = CSL_MMC_SYSCONFIG_STANDBYMODE_NOIDLE,
    MMCSD_STANDBY_MODE_SMART = CSL_MMC_SYSCONFIG_STANDBYMODE_SMART,
    MMCSD_STANDBY_MODE_SMART_WAKEUP =
        CSL_MMC_SYSCONFIG_STANDBYMODE_SMARTWAKE
}MMCSD_standbyMode;
 
typedef enum MMCSD_pwrCtrl_t
{
    MMCSD_PWR_CTRL_ON  = CSL_MMC_HCTL_SDBP_PWRON,
    MMCSD_PWR_CTRL_OFF = CSL_MMC_HCTL_SDBP_PWROFF
}MMCSD_pwrCtrl;
 
typedef enum MMCSD_suppVolt_t
{
    MMCSD_SUPP_VOLT_1P8 = CSL_MMC_CAPA_VS18_MASK,
    MMCSD_SUPP_VOLT_3P0 = CSL_MMC_CAPA_VS30_MASK,
    MMCSD_SUPP_VOLT_3P3 = CSL_MMC_CAPA_VS33_MASK
}MMCSD_suppVolt;
 
typedef enum MMCSD_cmdType_t
{
    MMCSD_CMD_TYPE_OTHER = CSL_MMC_CMD_CMD_TYPE_NORMAL,
    MMCSD_CMD_TYPE_BUS_SUSPEND = CSL_MMC_CMD_CMD_TYPE_SUSPEND,
    MMCSD_CMD_TYPE_FUNC_SEL = CSL_MMC_CMD_CMD_TYPE_RESUME,
    MMCSD_CMD_TYPE_IO_ABORT = CSL_MMC_CMD_CMD_TYPE_ABORT
}MMCSD_cmdType;
 
typedef enum MMCSD_rspType_t
{
    MMCSD_RSP_TYPE_NONE = CSL_MMC_CMD_RSP_TYPE_NORSP,
    MMCSD_RSP_TYPE_LEN_136 = CSL_MMC_CMD_RSP_TYPE_LGHT36,
    MMCSD_RSP_TYPE_LEN_48 = CSL_MMC_CMD_RSP_TYPE_LGHT48,
    MMCSD_RSP_TYPE_LEN_48_BUSY = CSL_MMC_CMD_RSP_TYPE_LGHT48B
}MMCSD_rspType;
 
typedef enum MMCSD_xFerType_t
{
    MMCSD_XFER_TYPE_TX = CSL_MMC_CMD_DDIR_WRITE,
    MMCSD_XFER_TYPE_RX = CSL_MMC_CMD_DDIR_READ
}MMCSD_xFerType;
 
typedef enum MMCSD_intrMask_t
{
    MMCSD_INTR_MASK_BADACCESS = CSL_MMC_IE_BADA_ENABLE_MASK,
    MMCSD_INTR_MASK_CARDERROR = CSL_MMC_IE_CERR_ENABLE_MASK,
    MMCSD_INTR_MASK_ADMAERROR = CSL_MMC_IE_ADMAE_ENABLE_MASK,
    MMCSD_INTR_MASK_ACMD12ERR = CSL_MMC_IE_ACE_ENABLE_MASK,
    MMCSD_INTR_MASK_DATABITERR = CSL_MMC_IE_DEB_ENABLE_MASK,
    MMCSD_INTR_MASK_DATACRCERR = CSL_MMC_IE_DCRC_ENABLE_MASK,
    MMCSD_INTR_MASK_DATATIMEOUT = CSL_MMC_IE_DTO_ENABLE_MASK,
    MMCSD_INTR_MASK_CMDINDXERR = CSL_MMC_IE_CIE_ENABLE_MASK,
    MMCSD_INTR_MASK_CMDBITERR = CSL_MMC_IE_CEB_ENABLE_MASK,
    MMCSD_INTR_MASK_CMDCRCERR = CSL_MMC_IE_CCRC_ENABLE_MASK,
    MMCSD_INTR_MASK_CMDTIMEOUT = CSL_MMC_IE_CTO_ENABLE_MASK,
    MMCSD_INTR_MASK_ERR = CSL_MMC_IE_NULL_MASK,
    MMCSD_INTR_MASK_CARDREM = CSL_MMC_IE_CREM_ENABLE_MASK,
    MMCSD_INTR_MASK_CARDINS = CSL_MMC_IE_CINS_ENABLE_MASK,
    MMCSD_INTR_MASK_BUFRDRDY = CSL_MMC_IE_BRR_ENABLE_MASK,
    MMCSD_INTR_MASK_BUFWRRDY = CSL_MMC_IE_BWR_ENABLE_MASK,
    MMCSD_INTR_MASK_TRNFCOMP = CSL_MMC_IE_TC_ENABLE_MASK,
    MMCSD_INTR_MASK_CMDCOMP = CSL_MMC_IE_CC_ENABLE_MASK
}MMCSD_intrMask;
 
typedef struct MMCSD_sysCfg_t
{
    uint32_t clockActivity;
    uint32_t standbyMode;
    uint32_t idleMode;
    uint32_t enableWakeup;
    uint32_t enableAutoIdle;
}MMCSD_sysCfg;
 
typedef struct MMCSD_cmd_t{
    uint32_t cmdId;
    uint32_t cmdType;
    uint32_t rspType;
    uint32_t xferType;
} MMCSD_cmd;
 
typedef struct MMCSD_cmdObj_t
{
    MMCSD_cmd cmd;
    uint32_t cmdArg;
    uint32_t enableData;
    uint32_t numBlks;
    uint32_t enableDma;
}MMCSD_cmdObj;
 
typedef enum MMCSD_idleMode_t
{
    MMCSD_IDLE_MODE_FORCE = CSL_MMC_SYSCONFIG_SIDLEMODE_FORCE,
    MMCSD_IDLE_MODE_NONE = CSL_MMC_SYSCONFIG_SIDLEMODE_NOIDLE,
    MMCSD_IDLE_MODE_SMART = CSL_MMC_SYSCONFIG_SIDLEMODE_SMART
}MMCSD_idleMode;
 
typedef enum MMCSD_busVolt_t
{
    MMCSD_BUS_VOLT_1P8 = CSL_MMC_HCTL_SDVS__1V8,
    MMCSD_BUS_VOLT_3P0 = CSL_MMC_HCTL_SDVS__3V0,
    MMCSD_BUS_VOLT_3P3 = CSL_MMC_HCTL_SDVS__3V3
}MMCSD_busVolt;
 
typedef struct MMCSD_iodelayParams_s {
    uint32_t deviceType;       
    uint32_t transferSpeed;    
    uint32_t operatingVoltage; 
    uint32_t loopBackType;     
} MMCSD_ioDelayParams;
 
typedef enum {
    MMCSD_BUS_VOLTAGE_1_8V = 0x1U,
    MMCSD_BUS_VOLTAGE_3_0V = 0x2U,
    MMCSD_BUS_VOLTAGE_3_3V = 0x4U
} MMCSD_BusVoltage;
 
typedef enum {
   MMCSD_INPUT_CLOCK_CTRL_GET, /* Returns the input clock to MMC'n' */
   MMCSD_INPUT_CLOCK_CTRL_SET  /* Sets the input clock to MMC'n' as per a value */
} MMCSD_inputClkCtrlMode_e;
 
typedef int32_t (*MMCSD_iodelayFxn) (uint32_t instanceNum, MMCSD_ioDelayParams *iodelayParams);
 
typedef int32_t (*MMCSD_switchVoltage) (uint32_t controllerNum, MMCSD_BusVoltage voltage);
 
typedef uint32_t (*MMCSD_inputClockControl) (uint32_t instNum, uint32_t *clkFreq, MMCSD_inputClkCtrlMode_e);
 
typedef struct
{
    void* deviceData;
    /* Pointer to eMMC/SD device data structure. Memory for this structure has to be allocated in application */
 
    uint8_t *dataBuf;
    /* Pointer to a 512 byte dataBuffer used for temporary data transactions internal to driver like ECSD read, tuning etc. To be allocated by application */
 
} MMCSD_Params;
 
typedef struct
{
    uint32_t ocr;
    /* Operating conditions register */
 
    uint32_t rca;
    /* Relative card address register */
 
    uint16_t maxReadBlockLen;
    /* Maximum supported block length for read */
 
    uint16_t maxWriteBlockLen;
    /* Maximum supported block length for read */
 
    char manuDate[9];
    /* ASCII string with the date of manufacture */
 
    uint8_t manuID;
    /* Card manufacturer ID */
 
    char productName[7];
    /* Product name */
 
    /* From CSD */
    uint8_t specVersion;
    /* eMMC specification version */
 
    uint32_t blockCount;
    /* Number of blocks in the eMMC */
 
    uint8_t transferSpeed;
    /* Transfer speed in code - Freq Unit x Mult Factor */
 
    uint8_t supportedModes;
    /* Supported speed modes by the device - HS200, HS400 etc */
 
    uint8_t eStrobeSupport;
    /* Support of enhanced strobe */
 
    uint8_t driveStrength;
    /* Drive strength of the device */
 
} MMCSD_EmmcDeviceData;
 
typedef struct
{
    uint32_t ocr;
    /* Operating conditions register */
 
    uint32_t rca;
    /* Relative card address register */
 
    uint16_t maxReadBlockLen;
    /* Maximum supported block length for read */
 
    uint16_t maxWriteBlockLen;
    /* Maximum supported block length for read */
 
    char manuDate[9];
    /* ASCII string with the date of manufacture */
 
    uint8_t manuID;
    /* Card manufacturer ID */
 
    char productName[6];
    /* Product name */
 
    /* From CSD */
    uint8_t specVersion;
    /* SD card specification version */
 
    uint32_t blockCount;
    /* Number of blocks in the SD */
 
    uint8_t transferSpeed;
    /* Transfer speed in code - Freq Unit x Mult Factor */
 
    uint32_t isCmd23;
    /* CMD23 support */
 
    uint32_t supportedDataWidths;
    /* Supported data widths by the device */
 
} MMCSD_SdDeviceData;
 
typedef struct
{
    uint32_t cmd;
    uint32_t flags;
    uint32_t arg;
    void    *dataBuf;
    uint32_t blockSize;
    uint32_t blockCount;
    uint32_t response[4];
} MMCSD_Transaction;
 
typedef struct
{
    uint32_t instNum;
    /*< MMC Peripheral instance number */
 
    uint32_t baseAddr;
    uint32_t intrNum;
    uint32_t inputClk;
    /*< MMC input functional clock */
 
    uint32_t outputClk;
    /*< MMC output clock */
 
    uint32_t cardType;
    uint32_t supportedBusWidth;
    uint32_t supportedBusVoltages;
    uint32_t intrEnable;
    /*< MMC enable interrupt */
 
    MMCSD_iodelayFxn iodelayFxn;
    /*< MMC Voltage Switch function */
 
    MMCSD_switchVoltage switchVoltageFxn;
    MMCSD_inputClockControl inputClockControl;
 
    uint32_t dmaEnable;
   /*EDMA related Hardware configuration details*/
 
} MMCSD_Attrs;
 
typedef struct
{
    uint32_t cardType;
    /*< Type of card. */
 
    MMCSD_Handle handle;
    uint32_t isOpen;
    /*< flag to indicate module is open */
 
    uint32_t ocr;
    /*< Operation condition register. */
 
    uint8_t switched_to_v18;
    /*< Has the card switched to 1.8V */
 
    uint32_t rca;
    /*< Relative card address. */
 
    uint32_t blockCount;
    /*< Number of blocks. */
 
    uint32_t dataBlockCount;
    /*< Data dec. block counter */
 
    uint32_t dataBlockSize;
    uint8_t support1_8V;
    /*< Does card support 1.8V. */
 
    uint64_t size;
    /*< Size of the card in bytes. */
 
    uint8_t highCap;
    /*< Is card of high capacity. */
 
    uint8_t *dataBufIdx;
    /*< Data buffer index */
 
    uint32_t cid[4];
    volatile uint32_t cmdComp;
    /*< Command completion flag */
 
    volatile uint32_t cmdTimeout;
    /*< Command timeout flag */
 
    volatile uint32_t xferInProgress;
    /*< Command completion flag */
 
    volatile uint32_t xferComp;
    /*< Transfer completion flag */
 
    uint8_t tranSpeed;
    /*< Transfer speed. */
 
    uint32_t csd[4];
    /*< Card specific data. */
 
    uint32_t scr[2];
    /*< First value of enumeration. Can be used for validation. */
 
    volatile uint32_t xferTimeout;
    /*< Transfer timeout flag */
 
    uint8_t sdVer;
    /*< Version of card. */
 
    uint32_t intrEnable;
    /*< MMC enable interrupt */
 
    uint32_t dmaEnable;
    HwiP_Object hwiObj;
    uint8_t ecsd[512];
    /*< eMMC specific data. */
 
    uint32_t blockSize;
    uint8_t busWidth;
    /*< Bus width. */
 
    uint8_t *writeBufIdx;        /*< Internal inc. dataBuf index */
 
    uint32_t writeBlockCount;    /*< Internal dec. blockCounter */
 
    uint8_t *readBufIdx;    /*< Internal inc. dataBuf index */
 
    uint32_t readBlockCount;    /*< Internal dec. blockCounter */
 
    uint32_t isHC;
    SemaphoreP_Object       cmdMutex;
    SemaphoreP_Object       xferMutex;
    SemaphoreP_Object       cmdCompleteSemObj;
    SemaphoreP_Object       dataCopyCompleteSemObj;
    SemaphoreP_Object       xferCompleteSemObj;
} MMCSD_Object;
 
typedef struct
{
    MMCSD_Attrs *attrs;
    MMCSD_Object *object;
} MMCSD_Config;
 
/* ========================================================================== */
/*                                Externs                                     */
/* ========================================================================== */
 
extern MMCSD_Config gMmcsdConfig[];
extern uint32_t    gMmcsdConfigNum;
 
/* ========================================================================== */
/*                  Internal/Private Structure Declarations                   */
/* ========================================================================== */
 
/* ========================================================================== */
/*                       Function Declarations                                */
/* ========================================================================== */
 
void MMCSD_init(void);
 
void MMCSD_deinit(void);
 
void MMCSD_Params_init(MMCSD_Params *mmcsdParams);
 
MMCSD_Handle MMCSD_open(uint32_t index, const MMCSD_Params *openParams);
 
void MMCSD_close(MMCSD_Handle handle);
 
MMCSD_Handle MMCSD_getHandle(uint32_t index);
 
int32_t MMCSD_read(MMCSD_Handle handle, uint8_t *buf, uint32_t startBlk, uint32_t numBlks);
 
int32_t MMCSD_write(MMCSD_Handle handle, uint8_t *buf, uint32_t startBlk, uint32_t numBlks);
 
uint32_t MMCSD_getBlockSize(MMCSD_Handle handle);
 
uint32_t MMCSD_getBlockCount(MMCSD_Handle handle);
 
#ifdef __cplusplus
}
#endif
 
#endif /* MMCSD_H_ */