ospi/v0/ospi.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2021-2025 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_H_
#define OSPI_H_
 
/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
 
#include <stdint.h>
#include <kernel/dpl/SystemP.h>
#include <kernel/dpl/HwiP.h>
#include <kernel/dpl/SemaphoreP.h>
#include <drivers/hw_include/csl_types.h>
#include <drivers/hw_include/cslr_ospi.h>
#include "ospi_tuning/ospi_tuning_algo/algo_v1/ospi_phy_tuning.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
typedef void *OSPI_Handle;
 
#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_FLASH_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_FLASH_PROTOCOL_INVALID (uint32_t)(0xFFFFFFFF)
 
#define OSPI_READ_MODE_DAC    (0U)
#define OSPI_READ_MODE_INDAC  (1U)
 
#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_DECODER_SELECT4  ((uint32_t) 0U)
#define OSPI_DECODER_SELECT16 ((uint32_t) 1U)
 
#define OSPI_NOR_DMA_COPY_LOWER_LIMIT     (1024U)
#define OSPI_NAND_DMA_COPY_LOWER_LIMIT     (256U)
 
#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)
 
/* ========================================================================== */
/*                         Structure Declarations                             */
/* ========================================================================== */
typedef struct
{
    uint32_t                count;
    void                   *buf;
    uint32_t                addrOffset;
    uint32_t                status;
    uint32_t                transferTimeout;
    uint32_t                dmaCopyLowerLimit;
} OSPI_Transaction;
 
typedef struct
{
    uint8_t cmd;
    uint32_t cmdAddr;
    uint8_t numAddrBytes;
    void *txDataBuf;
    uint32_t txDataLen;
} OSPI_WriteCmdParams;
 
typedef struct
{
    uint8_t cmd;
    uint32_t cmdAddr;
    uint8_t numAddrBytes;
    uint8_t dummyBits;
    void *rxDataBuf;
    uint16_t rxDataLen;
} OSPI_ReadCmdParams;
 
typedef struct
{
    uint32_t regionStartAddr;
    uint32_t regionSize;
} OSPI_AddrRegion;
 
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_PhyTuneWindowParams;
 
typedef struct
{
    uint32_t phyControlMode;
    uint32_t dllLockMode;
    OSPI_PhyTuneWindowParams tuningWindowParams;
    OSPI_phyParams phyParams;
} OSPI_PhyConfiguration;
 
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
{
    /*
     * SOC configuration
     */
    uint32_t                baseAddr;
    uint32_t                dataBaseAddr;
    uint32_t                moduleId;
    uint32_t                clkId;
    uint32_t                inputClkFreq;
    /*
     * Driver configuration
     */
    uint32_t                intrNum;
    uint32_t                intrEnable;
    uint8_t                 intrPriority;
    uint32_t                dmaEnable;
    uint32_t                phyEnable;
    uint32_t                phySkipTuning;
    uint32_t                dacEnable;
    uint32_t                frmFmt;
    uint32_t                devDelays[4];
    uint32_t                chipSelect;
    uint32_t                decChipSelect;
    uint32_t                readMode;
    uint32_t                baudRateDiv;
    uint32_t                phaseDelayElement;
    uint8_t                 validateOtp;
    const OSPI_AddrRegion *dmaRestrictedRegions;
    OSPI_PhyConfiguration  phyConfiguration;
} OSPI_Attrs;
 
typedef struct
{
    /*
     * User params
     */
    OSPI_Handle handle;
    uint32_t transferMode;
    uint32_t protocol;
    uint32_t rdDummyCycles;
    uint32_t cmdDummyCycles;
    uint32_t rdDataCapDelay;
    uint32_t phyRdDataCapDelay;
    uint32_t phyCfgVal;
    uint32_t phyDummyCycles;
    uint32_t numAddrBytes;
    uint32_t cmdExtType;
    /*
     * State variables
     */
    uint32_t isOpen;
    SemaphoreP_Object       lockObj;
    SemaphoreP_Object       transferSemObj;
    HwiP_Object             hwiObj;
    uint32_t                phyEnableSuccess;
    uint32_t                rdDummyValPhyMode;
    OSPI_Transaction *currTrans;
    void* ospiDmaHandle;
    uint32_t deviceSize;
} OSPI_Object;
 
typedef struct
{
    const OSPI_Attrs *attrs;
    OSPI_Object *object;
} OSPI_Config;
 
extern OSPI_Config gOspiConfig[];
extern uint32_t    gOspiConfigNum;
 
/* ========================================================================== */
/*                  Internal/Private Structure Declarations                   */
/* ========================================================================== */
 
/* ========================================================================== */
/*                       Function Declarations                                */
/* ========================================================================== */
 
void OSPI_init(void);
 
void OSPI_deinit(void);
 
 
void OSPI_Params_init( OSPI_Params *ospiParams);
 
OSPI_Handle OSPI_open(uint32_t index, const OSPI_Params *openParams);
 
void OSPI_close(OSPI_Handle handle);
 
OSPI_Handle OSPI_getHandle(uint32_t index);
 
int32_t OSPI_readDirect(OSPI_Handle handle, OSPI_Transaction *trans);
 
int32_t OSPI_readIndirect(OSPI_Handle handle, OSPI_Transaction *trans);
 
int32_t OSPI_writeDirect(OSPI_Handle handle, OSPI_Transaction *trans);
 
int32_t OSPI_writeIndirect(OSPI_Handle handle, OSPI_Transaction *trans);
int32_t OSPI_readCmd(OSPI_Handle handle, OSPI_ReadCmdParams *rdParams);
 
int32_t OSPI_writeCmd(OSPI_Handle handle, OSPI_WriteCmdParams *wrParams);
 
void OSPI_Transaction_init(OSPI_Transaction *trans);
 
void OSPI_ReadCmdParams_init(OSPI_ReadCmdParams *rdParams);
 
void OSPI_WriteCmdParams_init(OSPI_WriteCmdParams *wrParams);
 
uint32_t OSPI_getInputClk(OSPI_Handle handle);
 
uint32_t OSPI_isDacEnable(OSPI_Handle handle);
 
uint32_t OSPI_isDmaEnable(OSPI_Handle handle);
 
uint32_t OSPI_isIntrEnable(OSPI_Handle handle);
 
uint32_t OSPI_isPhyEnable(OSPI_Handle handle);
 
uint32_t OSPI_isDtrEnable(OSPI_Handle handle);
 
int32_t OSPI_enableDDR(OSPI_Handle handle);
 
int32_t OSPI_enableSDR(OSPI_Handle handle);
 
int32_t OSPI_enableDdrRdCmds(OSPI_Handle handle);
 
int32_t OSPI_setRdDataCaptureDelay(OSPI_Handle handle, uint32_t rdDataCapDelay, uint32_t updatePhyRdDelay);
 
void OSPI_setNumAddrBytes(OSPI_Handle handle, uint32_t numAddrBytes);
 
void OSPI_setDeviceSize(OSPI_Handle handle, uint32_t deviceSize, uint32_t pageSize, uint32_t blkSize);
 
void OSPI_setCmdDummyCycles(OSPI_Handle handle, uint32_t cmdDummyCycles);
 
void OSPI_setReadDummyCycles(OSPI_Handle handle, uint32_t dummyCycles);
 
void OSPI_setRdDummyValPhyMode(OSPI_Handle handle, uint32_t rdDummyValPhyMode);
 
void OSPI_setPhyEnableSuccess(OSPI_Handle handle, uint32_t success);
 
void OSPI_setModeBits(OSPI_Handle handle, uint32_t modeBits);
 
void OSPI_enableModeBitsCmd(OSPI_Handle handle);
 
void OSPI_enableModeBitsRead(OSPI_Handle handle);
 
uint32_t OSPI_getPhyEnableSuccess(OSPI_Handle handle);
 
void OSPI_cmdModeBitSet(OSPI_Handle handle, uint32_t enable);
 
void OSPI_rdModeBitSet(OSPI_Handle handle, uint32_t enable);
 
uint32_t OSPI_getProtocol(OSPI_Handle handle);
 
void OSPI_setProtocol(OSPI_Handle handle, uint32_t protocol);
 
void OSPI_setDualOpCodeMode(OSPI_Handle handle);
 
void OSPI_clearDualOpCodeMode(OSPI_Handle handle);
 
void OSPI_setXferOpCodes(OSPI_Handle handle, uint8_t readCmd, uint8_t pageProgCmd);
 
void OSPI_setCmdExtType(OSPI_Handle handle, uint32_t cmdExtType);
 
int32_t OSPI_enableDacMode(OSPI_Handle handle);
 
int32_t OSPI_disableDacMode(OSPI_Handle handle);
 
uint32_t OSPI_getFlashDataBaseAddr(OSPI_Handle handle);
 
int32_t OSPI_phyTuneDDR(OSPI_Handle handle, uint32_t flashOffset);
 
int32_t OSPI_phyTuneSDR(OSPI_Handle handle, uint32_t flashOffset);
 
int32_t OSPI_phyTuneGrapher(OSPI_Handle handle, uint32_t flashOffset, uint8_t arrays[5][128][128]);
 
void OSPI_phyGetTuningData(uint32_t *tuningData, uint32_t *tuningDataSize);
 
int32_t OSPI_phyReadAttackVector(OSPI_Handle handle, uint32_t offset);
 
void OSPI_phyReadTunedVal(OSPI_Handle handle);
 
void OSPI_phyWriteTunedVal(OSPI_Handle handle);
 
void OSPI_phyResyncDLL(OSPI_Handle handle);
 
int32_t OSPI_enablePhy(OSPI_Handle handle);
 
int32_t OSPI_disablePhy(OSPI_Handle handle);
 
int32_t OSPI_enablePhyPipeline(OSPI_Handle handle);
 
int32_t OSPI_disablePhyPipeline(OSPI_Handle handle);
 
 
int32_t OSPI_norFlashInit1s1s1s(OSPI_Handle handle);
 
void OSPI_norFlashSetCmds(uint8_t rdCmd, uint8_t wrCmd, uint8_t eraseCmd);
 
int32_t OSPI_norFlashReadId(OSPI_Handle handle, uint32_t *manufacturerId, uint32_t *deviceId);
 
int32_t OSPI_norFlashWrite(OSPI_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len);
 
int32_t OSPI_norFlashRead(OSPI_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len);
 
int32_t OSPI_norFlashReadSfdp(OSPI_Handle handle, uint32_t offset, uint8_t *buf, uint32_t len);
 
int32_t OSPI_norFlashErase(OSPI_Handle handle, uint32_t address);
int32_t OSPI_skipTuning(OSPI_Handle handle);
 
uint32_t OSPI_isOtpValidateEnable(OSPI_Handle handle);
 
int32_t OSPI_phyValidateTuningPoint(OSPI_Handle handle, uint32_t flashOffset);
 
int32_t OSPI_setFrequency(OSPI_Handle handle, uint64_t inputClkFreq);
 
void OSPI_setDelays(OSPI_Handle handle, uint32_t inputClkFreq);
 
void OSPI_setBaudRateDiv(OSPI_Handle handle, uint32_t baudRateDiv);
 
int32_t OSPI_disableDdrRdCmds(OSPI_Handle handle);
 
void OSPI_set1sProtocol(OSPI_Handle handle);
 
#ifdef __cplusplus
}
#endif
 
#endif /* #ifndef OSPI_H_ */