ospi/v0/ospi.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2021 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>
 
#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_XFER_LINES_SINGLE  (0U)
#define OSPI_XFER_LINES_DUAL    (1U)
#define OSPI_XFER_LINES_QUAD    (2U)
#define OSPI_XFER_LINES_OCTAL   (3U)
 
#define OSPI_CMD_INVALID_OPCODE  (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_1_1_1     (0x00)
#define OSPI_NOR_PROTOCOL_1_1_2     (0x01)
#define OSPI_NOR_PROTOCOL_1_2_2     (0x02)
#define OSPI_NOR_PROTOCOL_1_1_4     (0x03)
#define OSPI_NOR_PROTOCOL_1_4_4     (0x04)
#define OSPI_NOR_PROTOCOL_1_1_8     (0x05)
#define OSPI_NOR_PROTOCOL_1_8_8     (0x06)
#define OSPI_NOR_PROTOCOL_2_2_2_S   (0x07)
#define OSPI_NOR_PROTOCOL_2_2_2_D   (0x08)
#define OSPI_NOR_PROTOCOL_4_4_4_S   (0x09)
#define OSPI_NOR_PROTOCOL_4_4_4_D   (0x0A)
#define OSPI_NOR_PROTOCOL_8_8_8_S   (0x0B)
#define OSPI_NOR_PROTOCOL_8_8_8_D   (0x0C)
 
#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)
 
/* ========================================================================== */
/*                         Structure Declarations                             */
/* ========================================================================== */
typedef struct
{
    uint32_t                count;
    void                   *buf;
    uint32_t                addrOffset;
    uint32_t                status;
    uint32_t                transferTimeout;
} 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;
    void *rxDataBuf;
    uint32_t rxDataLen;
} 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
{
    /*
     * SOC configuration
     */
    uint32_t                baseAddr;
    uint32_t                dataBaseAddr;
    uint32_t                inputClkFreq;
    /*
     * Driver configuration
     */
    uint32_t                intrNum;
    uint32_t                intrEnable;
    uint8_t                 intrPriority;
    uint32_t                dtrEnable;
    uint32_t                dmaEnable;
    uint32_t                phyEnable;
    uint32_t                dacEnable;
    uint32_t                xferLines;
    uint32_t                frmFmt;
    uint32_t                devDelays[4];
    uint32_t                chipSelect;
    uint32_t                decChipSelect;
    uint32_t                baudRateDiv;
    const OSPI_AddrRegion *dmaRestrictedRegions;
} OSPI_Attrs;
 
typedef struct
{
    /*
     * User params
     */
    OSPI_Handle handle;
    uint32_t transferMode;
    uint32_t xferLines;
    uint32_t rdDummyCycles;
    uint32_t cmdDummyCycles;
    uint32_t rdDataCapDelay;
    uint32_t phyRdDataCapDelay;
    uint32_t numAddrBytes;
    uint32_t cmdExtType;
    /*
     * State variables
     */
    uint32_t isOpen;
    SemaphoreP_Object       lockObj;
    SemaphoreP_Object       transferSemObj;
    HwiP_Object             hwiObj;
    uint32_t                phyEnableSuccess;
    OSPI_Transaction *currTrans;
    void* ospiDmaHandle;
} OSPI_Object;
 
typedef struct
{
    const OSPI_Attrs *attrs;
    OSPI_Object *object;
} OSPI_Config;
 
typedef struct {
 
    /* Data and CMDs */
 
    uint8_t  XSPI_NOR_CMD_RSTEN;
    uint8_t  XSPI_NOR_CMD_RSTMEM;
    uint8_t  XSPI_NOR_CMD_WREN;
    uint8_t  XSPI_NOR_CMD_WRREG;
    uint8_t  XSPI_NOR_CMD_BULK_ERASE;
    uint8_t  XSPI_NOR_CMD_SECTOR_ERASE_3B;
    uint8_t  XSPI_NOR_CMD_SECTOR_ERASE_4B;
    uint8_t  XSPI_NOR_CMD_BLOCK_ERASE_3B;
    uint8_t  XSPI_NOR_CMD_BLOCK_ERASE_4B;
    uint8_t  XSPI_NOR_CMD_PAGE_PROG_3B;
    uint8_t  XSPI_NOR_CMD_PAGE_PROG_4B;
    uint8_t  XSPI_NOR_CMD_RDSR;
    uint8_t  XSPI_NOR_CMD_RDREG;
    uint8_t  XSPI_NOR_CMD_RDID;
    uint8_t  XSPI_NOR_CMD_READ;
    uint8_t  XSPI_NOR_CMD_888_SDR_READ;
    uint8_t  XSPI_NOR_CMD_888_DDR_READ;
    uint8_t  XSPI_NOR_CMD_444_SDR_READ;
    uint8_t  XSPI_NOR_CMD_444_DDR_READ;
    uint8_t  XSPI_NOR_CMD_114_READ;
    uint32_t XSPI_NOR_SR_WIP;
    uint32_t XSPI_NOR_SR_WEL;
    uint8_t  XSPI_NOR_RDID_NUM_BYTES;
    uint8_t  XSPI_NOR_MANF_ID;
    uint16_t XSPI_NOR_DEVICE_ID;
    uint16_t XSPI_NOR_114_READ_MODE_CLKS;
    uint16_t XSPI_NOR_114_READ_DUMMY_CYCLES;
    uint16_t XSPI_NOR_114_READ_DUMMY_CYCLES_LC;
    uint16_t XSPI_NOR_444_READ_MODE_CLKS;
    uint16_t XSPI_NOR_444_READ_DUMMY_CYCLES;
    uint16_t XSPI_NOR_444_READ_DUMMY_CYCLES_LC;
    uint16_t XSPI_NOR_QUAD_CMD_READ_DUMMY_CYCLES;
    uint16_t XSPI_NOR_OCTAL_READ_DUMMY_CYCLE;
    uint16_t XSPI_NOR_OCTAL_READ_DUMMY_CYCLE_LC;
    uint16_t XSPI_NOR_OCTAL_DDR_RDSR_DUMMY_CYCLE;
    uint16_t XSPI_NOR_OCTAL_DDR_RDSR_ADDR_BYTES;
    uint16_t XSPI_NOR_OCTAL_DDR_RDREG_ADDR_BYTES;
    uint16_t XSPI_NOR_OCTAL_DDR_WRREG_ADDR_BYTES;
    uint16_t XSPI_NOR_OCTAL_DDR_RDVREG_DUMMY_CYCLE;
    uint16_t XSPI_NOR_OCTAL_DDR_RDNVREG_DUMMY_CYCLE;
    uint16_t XSPI_NOR_OCTAL_RDSFDP_DUMMY_CYCLE;
    uint8_t  XSPI_NOR_OCTAL_RDSFDP_ADDR_TYPE;
    uint32_t XSPI_NOR_WRR_WRITE_TIMEOUT;
    uint32_t XSPI_NOR_BULK_ERASE_TIMEOUT;
    uint32_t XSPI_NOR_PAGE_PROG_TIMEOUT;
    uint32_t XSPI_NOR_VREG_OFFSET;
    uint32_t XSPI_NOR_NVREG_OFFSET;
    uint32_t XSPI_NOR_QUAD_MODE_CFG_ADDR;
    uint32_t XSPI_NOR_QUAD_MODE_CFG_BIT_LOCATION;
    uint32_t XSPI_NOR_DDR_OCTAL_MODE_CFG_ADDR;
    uint32_t XSPI_NOR_DDR_OCTAL_MODE_CFG_BIT_LOCATION;
    uint32_t XSPI_NOR_DUMMY_CYCLE_CFG_ADDR;
    uint64_t XSPI_NOR_FLASH_SIZE;
    uint16_t XSPI_NOR_PAGE_SIZE;
    uint32_t XSPI_NOR_BLOCK_SIZE;
    uint32_t XSPI_NOR_SECTOR_SIZE;
 
    /* Settings and flags */
    uint8_t addrByteSupport;
    /* Number of address bytes supported. 3 or 4 or both */
 
    uint8_t dtrSupport;
    /* Supports DTR clocking or not */
 
    uint8_t qeType;
    /* Quad Enable Requirements Type */
 
    uint8_t seq444Enable[5];
    /* Sequence numbers to enable 4-4-4 mode */
 
    uint8_t seq444Disable[4];
    /* Sequence numbers to disable 4-4-4 mode */
 
    uint8_t oeType;
    /* Octal Enable Requirements Type */
 
    uint8_t cmdExtType;
    /* Command Extension supported by the flash in 8D mode */
 
    uint8_t byteOrder;
    /* Byte order of the flash data out in 8D mode */
 
    uint8_t supportedEraseTypes[2];
    /* Indexed array of 2 selected supported erase types. [0] will be sect, [1] will be block */
 
} OSPI_GenericXspiDevDefines;
 
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_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);
 
void OSPI_setNumAddrBytes(OSPI_Handle handle, uint32_t numAddrBytes);
 
void OSPI_setDeviceSize(OSPI_Handle handle, 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_setPhyEnableSuccess(OSPI_Handle handle, uint32_t success);
 
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);
 
void OSPI_setXferLines(OSPI_Handle handle, uint32_t xferLines);
 
uint32_t OSPI_getXferLines(OSPI_Handle handle);
 
void OSPI_setDualOpCodeMode(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_phyTuneGrapher(OSPI_Handle handle, uint32_t flashOffset, uint8_t arrays[4][128][128]);
 
void OSPI_phyGetTuningData(uint32_t *tuningData, uint32_t *tuningDataSize);
 
int32_t OSPI_phyReadAttackVector(OSPI_Handle handle, uint32_t offset);
 
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);
 
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);
#ifdef __cplusplus
}
#endif
 
#endif /* #ifndef OSPI_H_ */