mmcsd/v0/mmcsd.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2021-25 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 <stdbool.h>
#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>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
#define MMCSD_CARD_TYPE_SD                             (0U)
#define MMCSD_CARD_TYPE_EMMC                           (1U)
#define MMCSD_CARD_TYPE_MMC                            (2U)
 
/* useful in cases where SoC has MMCSD IP but no device attached to peripheral */
#define MMCSD_CARD_TYPE_NO_DEVICE                      (3U)
 
/*
* \brief Macros that can be used for selecting the bus/data width
*/
#define MMCSD_BUS_WIDTH_4BIT    (0x4U)
#define MMCSD_BUS_WIDTH_8BIT    (0x8U)
#define MMCSD_BUS_WIDTH_1BIT    (0x1U)
 
 
/*
* \brief Macros that can be used for selecting the media transfer speed
*/
#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_TRANSPEED_HS400           (0x4BU)
/*
* \brief Macros that can be used for selecting the bus voltage
*/
#define MMCSD_BUS_VOLT_1_8V    (0x5U) /* Embedded */
#define MMCSD_BUS_VOLT_3_0V    (0x6U) /* Typical */
#define MMCSD_BUS_VOLT_3_3V    (0x7U) /* Flattop */
 
/*
* \brief Macros that can be used for selecting command types
*/
#define MMCSD_CMD_TYPE_NORMAL          (0U)
#define MMCSD_CMD_TYPE_BUS_SUSPEND     (1U)
#define MMCSD_CMD_TYPE_FUNC_SEL        (2U)
#define MMCSD_CMD_TYPE_IO_ABORT        (3U)
 
/*
* \brief Macros that can be used for selecting command response types
*/
#define MMCSD_CMD_RSP_TYPE_NORSP            (0U)
#define MMCSD_CMD_RSP_TYPE_L136             (1U)
#define MMCSD_CMD_RSP_TYPE_L48              (2U)
#define MMCSD_CMD_RSP_TYPE_L48_BUSY         (3U)
 
/*
* \brief Macros that can be used for selecting transfer types
*/
#define MMCSD_CMD_XFER_TYPE_WRITE             (0U)
#define MMCSD_CMD_XFER_TYPE_READ              (1U)
 
/*
* \brief Macros that can be used for selecting supported MMC modes
*/
#define MMCSD_SUPPORT_MMC_DS       (0x01U) /* DS (Up to 26Mhz) */
#define MMCSD_SUPPORT_MMC_HS_SDR   (0x02U) /* HS (Up to 52Mhz) */
#define MMCSD_SUPPORT_MMC_HS_DDR   (0x04U) /* HS (Up to 52Mhz) */
#define MMCSD_SUPPORT_MMC_HS200    (0x08U) /* HS200 (Up to 200Mhz) */
#define MMCSD_SUPPORT_MMC_HS400    (0x10U) /* HS400 (Up to 400Mhz) */
#define MMCSD_SUPPORT_MMC_ALL      (0xFFU) /* All modes */
 
/*
* \brief Strobe select value for HS400 operating mode
*/
#define MMCSD_STRBSEL_MMC_HS400    (0x66U)
 
/*
* \brief Macros that can be used for selecting the OTAPDLYSEL value based on
* core voltage for HS400 operating mode
*/
#define MMCSD_OTAPDLYSEL_MMC_HS400_0_75V   (0x6U)
#define MMCSD_OTAPDLYSEL_MMC_HS400_0_85V   (0x5U)
 
/*
* \brief Macros that can be used for selecting supported SD modes
*/
#define MMCSD_SUPPORT_SD_DS       (0x01U)
#define MMCSD_SUPPORT_SD_HS       (0x02U)
#define MMCSD_SUPPORT_SD_SDR50    (0x04U)
#define MMCSD_SUPPORT_SD_SDR104   (0x08U)
#define MMCSD_SUPPORT_SD_DDR50    (0x10U)
#define MMCSD_SUPPORT_SD_ALL      (0xFFU) /* All modes */
 
/*
* \brief Macros that can be used for selecting PHY types
*/
#define MMCSD_PHY_TYPE_HW_PHY                 (0U)
#define MMCSD_PHY_TYPE_SW_PHY                 (1U)
#define MMCSD_PHY_TYPE_NO_PHY                 (2U)
 
/*
* \brief Macros that can be used for selecting PHY tuning type
*/
#define MMCSD_PHY_TUNING_TYPE_AUTO            (0U)
#define MMCSD_PHY_TUNING_TYPE_MANUAL          (1U)
 
/*
* \brief Macros that can be used for selecting PHY modes
*/
#define MMCSD_PHY_MODE_HS400                  (1U)
#define MMCSD_PHY_MODE_HS200                  (2U)
#define MMCSD_PHY_MODE_HSSDR50                (3U)
#define MMCSD_PHY_MODE_HSDDR50                (4U)
#define MMCSD_PHY_MODE_SDR104                 (5U)
#define MMCSD_PHY_MODE_SDR50                  (6U)
#define MMCSD_PHY_MODE_DDR50                  (7U)
#define MMCSD_PHY_MODE_SDR25                  (8U)
#define MMCSD_PHY_MODE_SDR12                  (9U)
#define MMCSD_PHY_MODE_HS                     (10U)
#define MMCSD_PHY_MODE_DS                     (11U)
 
/*
* \brief Macros that can be used for selecting UHS 1 modes
*/
#define MMCSD_UHS_MODE_SDR12                 (0U)
#define MMCSD_UHS_MODE_SDR25                 (1U)
#define MMCSD_UHS_MODE_SDR50                 (2U)
#define MMCSD_UHS_MODE_SDR104                (3U)
#define MMCSD_UHS_MODE_DDR50                 (4U)
#define MMCSD_UHS_MODE_HS400                 (5U)
#define MMCSD_UHS_MODE_UHS2                  (7U)
 
typedef void* MMCSD_Handle;
 
typedef enum{
    MMCSD_TRANS_SUCCESS = 0U,
    MMCSD_TRANS_FAILURE = 1U,
    MMCSD_TRANS_IRRECOVERABLE = 2U
} MMCSD_TransStatus;
 
/* ========================================================================== */
/*                         Structure Declarations                             */
/* ========================================================================== */
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 */
 
    uint16_t dsr;
    /* Driver stage register */
 
    bool impDsr;
    /* DSR implementation check value. Obtained from the CSD register read. */
 
    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 dir;
    uint32_t arg;
    void    *dataBuf;
    uint32_t blockSize;
    uint32_t blockCount;
    uint32_t autoCmdEn;
    /* AutoCMD12 or AutoCMD23 or no AutoCMD */
 
    uint32_t enableDma;
    /* Is DMA enabled for the command*/
 
    uint32_t isTuning;
    /* Is transaction used for tuning */
 
    uint32_t retries;
    /* Number of transaction retries */
 
    uint32_t response[4];
    uint32_t status;
    /* Status of the transaction */
 
} MMCSD_Transaction;
 
typedef struct
{
    uint32_t ctrlBaseAddr;
    uint32_t ssBaseAddr;
    uint32_t inputClkFreq;
    uint32_t outputClkFreq;
    uint32_t enableDma;
    uint32_t intrEnable;
    uint32_t intrNum;
    uint32_t eventId;
    uint32_t cardType;
    uint32_t busWidth;
    uint32_t supportedModes;
    uint32_t busVoltage;
    uint32_t isHS;
    uint32_t phyType;
    uint32_t tuningType;
} MMCSD_Attrs;
 
typedef struct
{
    MMCSD_Handle handle;
    uint32_t cardType;
    uint8_t *tempDataBuf;
    /* Temporary data buf for receiving tuning data, ecsd, scr etc. To be allocated in app and passed as MMCSD params to MMCSD_open */
 
    MMCSD_EmmcDeviceData *emmcData;
    /* EMMC device data structure. This has to be allocated in the app. Probably using sysconfig */
 
    MMCSD_SdDeviceData *sdData;
    /* SD device data structure. This has to be allocated in the app. Probably using sysconfig */
 
    uint8_t sdVer;
    uint8_t switchCmdTimeout;
    uint32_t busWidth;
    uint32_t transferSpeed;
    uint32_t isHC;
    uint32_t isUHS;
    uint32_t is1_8V;
    uint32_t isSwitch1_8V;
    uint32_t blockSize;
    uint64_t blockCount;
    uint64_t mediaSize;
    uint32_t enableDma;
    uint32_t intrEnable;
    volatile uint32_t cmdComp;
    volatile uint32_t cmdTimeout;
    /*< Command timeout flag */
 
    volatile uint32_t cmdCRCError;
    /*< Command CRC error flag */
 
    volatile uint32_t cmdEBError;
    /*< Command EndBit error flag */
 
    volatile uint32_t cmdIndexError;
    /*< Command Index error flag */
 
    volatile uint32_t dataTimeoutError;
    /*< Data Timeout error flag */
 
    volatile uint32_t dataCRCError;
    /*< Data CRC error flag */
 
    volatile uint32_t dataEBError;
    /*< Data end bit error */
 
    volatile uint32_t admaError;
    /*< ADMA error flag */
 
    volatile uint32_t cmdError;
    /*< Any error in processing of the command */
 
    volatile uint32_t xferInProgress;
    /*< Command completion flag */
 
    volatile uint32_t xferComp;
    /*< Transfer completion flag */
 
    volatile uint32_t xferTimeout;
    /*< Transfer timeout flag */
 
    uint8_t *dataBufIdx;
    uint32_t dataBlockCount;
    uint32_t dataBlockSize;
 
    uint8_t *readBufIdx;
    uint32_t readBlockCount;
 
    uint8_t *writeBufIdx;
    uint32_t writeBlockCount;
 
    uint32_t isManualTuning;
    uint32_t isOpen;
    uint32_t xferHighSpeedEn;
    uint32_t uhsmode;
    SemaphoreP_Object       cmdMutex;
    SemaphoreP_Object       xferMutex;
    SemaphoreP_Object       cmdCompleteSemObj;
    SemaphoreP_Object       dataCopyCompleteSemObj;
    SemaphoreP_Object       xferCompleteSemObj;
    HwiP_Object             hwiObj;
} MMCSD_Object;
 
typedef struct
{
    const MMCSD_Attrs *attrs;
    MMCSD_Object *object;
} MMCSD_Config;
 
typedef struct
{
    uint8_t start;
    uint8_t end;
    uint8_t length;
} MMCSD_TuningPassOrFailWindow;
 
/* ========================================================================== */
/*                                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);
 
uint32_t MMCSD_isHC(MMCSD_Handle handle);
 
int32_t MMCSD_enableBootPartition(MMCSD_Handle handle, uint32_t partitionNum);
 
int32_t MMCSD_disableBootPartition(MMCSD_Handle handle);
 
uint32_t MMCSD_getInputClk(MMCSD_Handle handle);
 
#ifdef __cplusplus
}
#endif
 
#endif /* MMCSD_H_ */