ospi_lld.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2024 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 OSPI_LLD_H_
#define OSPI_LLD_H_
 
/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
 
#include <stdint.h>
#include <stdbool.h>
#include <drivers/hw_include/csl_types.h>
#include <drivers/hw_include/cslr_ospi.h>
#include <drivers/ospi/v0/cslr_ospi.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
typedef void *OSPI_DmaHandle;
 
typedef void *OSPI_DmaChConfig;
 
typedef void *OSPI_DrvHandle;
 
#define OSPI_TRANSFER_COMPLETED        (0U)
#define OSPI_TRANSFER_STARTED          (1U)
#define OSPI_TRANSFER_CANCELLED        (2U)
#define OSPI_TRANSFER_FAILED           (3U)
#define OSPI_TRANSFER_CSN_DEASSERT     (4U)
#define OSPI_TRANSFER_TIMEOUT          (5U)
 
#define OSPI_TRANSFER_MODE_BLOCKING    (0U)
 
#define OSPI_TRANSFER_MODE_CALLBACK    (1U)
 
#define OSPI_TRANSFER_MODE_POLLING     (2U)
 
#define OSPI_FF_POL0_PHA0  (0U)
#define OSPI_FF_POL0_PHA1  (CSL_OSPI_FLASH_CFG_CONFIG_REG_SEL_CLK_PHASE_FLD_MASK | 0U)
#define OSPI_FF_POL1_PHA0  (0U | CSL_OSPI_FLASH_CFG_CONFIG_REG_SEL_CLK_POL_FLD_MASK)
#define OSPI_FF_POL1_PHA1  (CSL_OSPI_FLASH_CFG_CONFIG_REG_SEL_CLK_PHASE_FLD_MASK | \
                               CSL_OSPI_FLASH_CFG_CONFIG_REG_SEL_CLK_POL_FLD_MASK)
 
#define OSPI_CMD_INVALID_OPCODE  (0xFFU)
#define OSPI_CMD_INVALID_DUMMY   (0xFFU)
#define OSPI_CMD_INVALID_ADDR    (0xFFFFFFFFU)
 
#define OSPI_CMD_EXT_TYPE_REPEAT  (0x00U)
#define OSPI_CMD_EXT_TYPE_INVERSE (0x01U)
#define OSPI_CMD_EXT_TYPE_NONE    (0x02U)
 
#define OSPI_NOR_PROTOCOL(cmd, addr, data, dtr) (uint32_t)(((uint32_t)(dtr) << 24) | \
                                                           ((uint32_t)(cmd) << 16) | \
                                                           ((uint32_t)(addr) << 8) | \
                                                           ((uint32_t)(data) << 0))
#define OSPI_NOR_PROTOCOL_INVALID (uint32_t)(0xFFFFFFFF)
 
#define OSPI_PROTO_1S_1S_1S (0x0001)
#define OSPI_PROTO_1S_1S_2S (0x0002)
#define OSPI_PROTO_1S_1S_4S (0x0003)
#define OSPI_PROTO_1S_1S_8S (0x0004)
#define OSPI_PROTO_1S_8S_8S (0x000A)
#define OSPI_PROTO_4S_4S_4S (0x0005)
#define OSPI_PROTO_4S_4D_4D (0x0006)
#define OSPI_PROTO_8S_8S_8S (0x0007)
#define OSPI_PROTO_8D_8D_8D (0x0008)
#define OSPI_PROTO_CUSTOM   (0x0009)
 
#define OSPI_NAND_PROTOCOL(cmd, addr, data, dtr) (uint32_t)(((uint32_t)(dtr) << 24) | \
                                                           ((uint32_t)(cmd) << 16) | \
                                                           ((uint32_t)(addr) << 8) | \
                                                           ((uint32_t)(data) << 0))
#define OSPI_NAND_PROTOCOL_INVALID (uint32_t)(0xFFFFFFFF)
 
#define OSPI_CS0  (0U)
#define OSPI_CS1  (1U)
#define OSPI_CS2  (2U)
#define OSPI_CS3  (3U)
 
#define OSPI_CHIP_SELECT(x)   ((~((1U) << (x))) & 0xFU)
 
#define OSPI_READ_MODE_DAC  (0U)
#define OSPI_READ_MODE_INDAC  (1U)
 
#define OSPI_RESETPIN_DQ3       (0U)
#define OSPI_RESETPIN_DEDICATED (1U)
 
#define CSL_OSPI_BAUD_RATE_DIVISOR(x)        (((x) - 2U) >> 1U)
#define MAX_BAUDRATE_DIVIDER                 (32U)
#define CSL_OSPI_BAUD_RATE_DIVISOR_DEFAULT   (CSL_OSPI_BAUD_RATE_DIVISOR(MAX_BAUDRATE_DIVIDER))
 
#define OSPI_DECODER_SELECT4  ((uint32_t) 0U)
#define OSPI_DECODER_SELECT16 ((uint32_t) 1U)
 
#define OSPI_STATE_RESET                     ((uint32_t) 0U)
 
#define OSPI_STATE_IDLE                      ((uint32_t) 1U)
 
#define OSPI_STATE_BUSY                      ((uint32_t) 2U)
 
#define OSPI_STATE_ERROR                     ((uint32_t) 3U)
 
#define OSPI_SYSTEM_SUCCESS     ((int32_t )0)
 
#define OSPI_SYSTEM_FAILURE     ((int32_t)-1)
 
#define OSPI_TIMEOUT            ((int32_t)-2)
 
#define OSPI_LLD_INVALID_PARAM  ((int32_t)-3)
 
#define OSPI_BUSY               ((int32_t)-4)
 
#define OSPI_INVALID_STATE      ((int32_t)-5)
 
#define OSPI_NO_WAIT        ((uint32_t)0)
 
#define OSPI_WAIT_FOREVER   ((uint32_t)-1)
 
#define OSPI_TRANS_IDLE     ((uint32_t)0)
 
#define OSPI_TRANS_READ     ((uint32_t)1)
 
#define OSPI_TRANS_WRITE     ((uint32_t)2)
 
#define OSPI_FLASH_CFG_PHY_MASTER_CONTROL_REG_PHY_MASTER_MODE           (0U)
#define OSPI_FLASH_CFG_PHY_MASTER_CONTROL_REG_PHY_BYPASS_MODE           (1U)
 
#define OSPI_PHY_DLL_FULL_CYCLE_LOCK                   ((uint16_t) 0U)
#define OSPI_PHY_DLL_HALF_CYCLE_LOCK                   ((uint16_t) 1U)
 
#define OSPI_FLASH_ATTACK_VECTOR_SIZE       (128U)
 
/* ========================================================================== */
/*                      Function pointers Declarations                        */
/* ========================================================================== */
 
typedef uint32_t (*OSPI_Clock_getTicks)(void);
 
typedef uint32_t (*OSPI_Clock_usecToTicks)(uint64_t usecs);
 
typedef void (*OSPI_Clock_usec)(uint32_t usecs);
 
/* Type definition for the callback function*/
typedef void (*OSPI_lld_InterruptCallback)(void* args);
 
typedef void (*OSPI_lld_dma_readCompleteCallback)(void* args);
 
/* ========================================================================== */
/*                         Structure Declarations                             */
/* ========================================================================== */
typedef struct
{
    uint32_t                count;
    void                   *buf;
    uint32_t                addrOffset;
    uint32_t                status;
    uint32_t                dataLen;
    uint32_t                transferOffset;
    uint32_t                transferTimeout;
    uint32_t                state;
} OSPI_Transaction;
 
typedef struct
{
    uint8_t cmd;
    uint32_t cmdAddr;
    uint8_t numAddrBytes;
    void *txDataBuf;
    uint32_t txDataLen;
    uint32_t writeTimeout;
} OSPI_WriteCmdParams;
 
typedef struct
{
    uint8_t cmd;
    uint32_t cmdAddr;
    uint8_t numAddrBytes;
    uint8_t dummyBits;
    void *rxDataBuf;
    uint16_t rxDataLen;
    uint32_t readTimeout;
} OSPI_ReadCmdParams;
 
typedef struct
{
    uint32_t regionStartAddr;
    uint32_t regionSize;
} OSPI_AddrRegion;
 
typedef struct
{
    int32_t ospiDmaChIndex;
    /* Index of Channel used by OSPI DMA Driver. This index will be set by SysCfg according to the DMA driver chosen.
     * The OSPI driver uses this index to do an \ref OSPI_dmaOpen inside the \ref OSPI_open if the DMA mode is enabled
     */
} OSPI_Params;
 
 
typedef struct
{
    int32_t txDllLowWindowStart;
    int32_t txDllLowWindowEnd;
    int32_t txDllHighWindowStart;
    int32_t txDllHighWindowEnd;
    int32_t rxLowSearchStart;
    int32_t rxLowSearchEnd;
    int32_t rxHighSearchStart;
    int32_t rxHighSearchEnd;
    int32_t txLowSearchStart;
    int32_t txLowSearchEnd;
    int32_t txHighSearchStart;
    int32_t txHighSearchEnd;
    int32_t txDLLSearchOffset;
    uint32_t rxTxDLLSearchStep;
    uint32_t rdDelayMin;
    uint32_t rdDelayMax;
} OSPI_PhyWindowParams;
 
typedef struct
{
    uint32_t phaseDelayElement;
    uint32_t phyControlMode;
    uint32_t dllLockMode;
    OSPI_PhyWindowParams tuningWindowParams;
} OSPI_PhyConfiguration;
 
typedef struct
{
    uint32_t                dataBaseAddr;
    uint32_t                inputClkFreq;
    /*
     * Driver configuration
     */
    uint32_t                intrNum;
    uint32_t                intrEnable;
    uint8_t                 intrPriority;
    uint32_t                dmaEnable;
    uint32_t                phyEnable;
    uint32_t                dacEnable;
    uint32_t                frmFmt;
    uint32_t                devDelays[4];
    uint32_t                chipSelect;
    uint32_t                decChipSelect;
    uint32_t                baudRateDiv;
    const OSPI_AddrRegion *dmaRestrictedRegions;
    OSPI_DmaHandle  ospiDmaHandle;
    OSPI_DmaChConfig ospiDmaChConfig;
    OSPI_PhyConfiguration  phyConfiguration;
} OSPILLD_InitObject, *OSPILLD_InitHandle;
 
typedef struct
{
    /*
     * SOC configuration
     */
    uint32_t                baseAddr;
    /*
     * User params
     */
    const OSPI_Params *openParams;
    uint32_t transferMode;
    uint32_t protocol;
    uint32_t rdDummyCycles;
    uint32_t cmdDummyCycles;
    uint32_t rdDataCapDelay;
    uint32_t phyRdDataCapDelay;
    uint32_t numAddrBytes;
    uint32_t cmdExtType;
    uint32_t                phyEnableSuccess;
    OSPI_Transaction *currTrans;
    OSPI_Transaction trans;
    OSPILLD_InitHandle hOspiInit;
    /*
     * State variables
     */
    uint32_t            state;
 
    void*               args;
    OSPI_Clock_getTicks Clock_getTicks;
    OSPI_Clock_usecToTicks Clock_usecToTicks;
    OSPI_Clock_usec Clock_usleep;
 
    OSPI_lld_InterruptCallback interruptCallback;
    /* Interrupt Callback to be registered by the application*/
    OSPI_lld_dma_readCompleteCallback readCompleteCallback;
    /* DMA Readcallback function*/
 
} OSPILLD_Object, *OSPILLD_Handle;
 
/* ========================================================================== */
/*                  Internal/Private Structure Declarations                   */
/* ========================================================================== */
 
/* ========================================================================== */
/*                       Function Declarations                                */
/* ========================================================================== */
 
int32_t OSPI_lld_init(OSPILLD_Handle hOspi);
 
int32_t OSPI_lld_initDma(OSPILLD_Handle hOspi);
 
int32_t OSPI_lld_deInit(OSPILLD_Handle hOspi);
 
int32_t OSPI_lld_deInitDma(OSPILLD_Handle hOspi);
 
int32_t OSPI_lld_readDirect(OSPILLD_Handle handle, OSPI_Transaction *trans);
 
int32_t OSPI_lld_readDirectDma(OSPILLD_Handle handle, OSPI_Transaction *trans);
 
int32_t OSPI_lld_readIndirect(OSPILLD_Handle handle, OSPI_Transaction *trans);
 
int32_t OSPI_lld_writeDirect(OSPILLD_Handle handle, OSPI_Transaction *trans);
 
int32_t OSPI_lld_writeIndirect(OSPILLD_Handle handle, OSPI_Transaction *trans);
int32_t OSPI_lld_readCmd(OSPILLD_Handle handle, OSPI_ReadCmdParams *rdParams);
 
int32_t OSPI_lld_writeCmd(OSPILLD_Handle handle, OSPI_WriteCmdParams *wrParams);
 
void OSPI_lld_isr(void* args);
 
void OSPI_lld_readCompleteCallback(void* args);
 
void OSPI_lld_Transaction_init(OSPI_Transaction *trans);
 
void OSPI_lld_readCmdParams_init(OSPI_ReadCmdParams *rdParams);
 
void OSPI_lld_writeCmdParams_init(OSPI_WriteCmdParams *wrParams);
 
uint32_t OSPI_lld_getInputClk(OSPILLD_Handle handle);
 
uint32_t OSPI_lld_isDacEnable(OSPILLD_Handle handle);
 
uint32_t OSPI_lld_isDmaEnable(OSPILLD_Handle handle);
 
uint32_t OSPI_lld_isIntrEnable(OSPILLD_Handle handle);
 
uint32_t OSPI_lld_isPhyEnable(OSPILLD_Handle handle);
 
int32_t OSPI_lld_enableDDR(OSPILLD_Handle handle);
 
int32_t OSPI_lld_enableSDR(OSPILLD_Handle handle);
 
int32_t OSPI_lld_enableDdrRdCmds(OSPILLD_Handle handle);
 
int32_t OSPI_lld_setRdDataCaptureDelay(OSPILLD_Handle handle, uint32_t rdDataCapDelay);
 
void OSPI_lld_setNumAddrBytes(OSPILLD_Handle handle, uint32_t numAddrBytes);
 
void OSPI_lld_setDeviceSize(OSPILLD_Handle handle, uint32_t pageSize, uint32_t blkSize);
 
void OSPI_lld_setCmdDummyCycles(OSPILLD_Handle handle, uint32_t cmdDummyCycles);
 
void OSPI_lld_setReadDummyCycles(OSPILLD_Handle handle, uint32_t dummyCycles);
 
void OSPI_lld_setWriteDummyCycles(OSPILLD_Handle handle, uint32_t dummyCycles);
 
void OSPI_lld_setPhyEnableSuccess(OSPILLD_Handle handle, uint32_t success);
 
void OSPI_lld_setModeBits(OSPILLD_Handle handle, uint32_t modeBits);
 
void OSPI_lld_enableModeBitsCmd(OSPILLD_Handle handle);
 
void OSPI_lld_enableModeBitsRead(OSPILLD_Handle handle);
 
uint32_t OSPI_lld_getPhyEnableSuccess(OSPILLD_Handle handle);
 
uint32_t OSPI_lld_getProtocol(OSPILLD_Handle handle);
 
void OSPI_lld_setProtocol(OSPILLD_Handle handle, uint32_t protocol);
 
void OSPI_lld_setDualOpCodeMode(OSPILLD_Handle handle);
 
void OSPI_lld_clearDualOpCodeMode(OSPILLD_Handle handle);
 
void OSPI_lld_setXferOpCodes(OSPILLD_Handle handle, uint8_t readCmd, uint8_t pageProgCmd);
 
void OSPI_lld_setCmdExtType(OSPILLD_Handle handle, uint32_t cmdExtType);
 
int32_t OSPI_lld_enableDacMode(OSPILLD_Handle handle);
 
int32_t OSPI_lld_disableDacMode(OSPILLD_Handle handle);
 
uint32_t OSPI_lld_getFlashDataBaseAddr(OSPILLD_Handle handle);
 
int32_t OSPI_lld_phyTuneDDR(OSPILLD_Handle handle, uint32_t flashOffset);
 
int32_t OSPI_lld_phyTuneSDR(OSPILLD_Handle handle, uint32_t flashOffset);
 
int32_t OSPI_lld_phyTuneGrapher(OSPILLD_Handle handle, uint32_t flashOffset, uint8_t arrays[4][128][128]);
 
void OSPI_lld_phyGetTuningData(uint32_t *tuningData, uint32_t *tuningDataSize);
 
int32_t OSPI_lld_phyReadAttackVector(OSPILLD_Handle handle, uint32_t offset);
 
int32_t OSPI_lld_enablePhy(OSPILLD_Handle handle);
 
int32_t OSPI_lld_disablePhy(OSPILLD_Handle handle);
 
int32_t OSPI_lld_enablePhyPipeline(OSPILLD_Handle handle);
 
int32_t OSPI_lld_disablePhyPipeline(OSPILLD_Handle handle);
 
int32_t OSPI_lld_norFlashInit1s1s1s(OSPILLD_Handle handle);
 
void OSPI_lld_norFlashSetCmds(uint8_t rdCmd, uint8_t wrCmd, uint8_t eraseCmd);
 
 
int32_t OSPI_lld_norFlashReadId(OSPILLD_Handle handle, uint32_t *manufacturerId, uint32_t *deviceId);
 
int32_t OSPI_lld_norFlashWrite(OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len);
 
int32_t OSPI_lld_norFlashRead(OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len);
 
int32_t OSPI_lld_norFlashReadIndirect(OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len);
 
int32_t OSPI_lld_norFlashReadSfdp(OSPILLD_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len);
 
int32_t OSPI_lld_norFlashErase(OSPILLD_Handle handle, uint32_t address);
 
int32_t OSPI_lld_configResetPin(OSPILLD_Handle handle, uint32_t config);
 
int32_t OSPI_lld_configBaudrate(OSPILLD_Handle handle, uint32_t baud);
 
int32_t OSPI_lld_readBaudRateDivFromReg(OSPILLD_Handle handle, uint32_t *baudDiv);
 
int32_t OSPI_lld_getBaudRateDivFromObj(OSPILLD_Handle handle, uint32_t *baudDiv);
 
int32_t OSPI_lld_setResetPinStatus(OSPILLD_Handle hOspi, uint32_t pinStatus);
 
#ifdef __cplusplus
}
#endif
 
#endif /* #ifndef OSPI_LLD_H_ */