spiFlash.c

Go to the documentation of this file.

// Copyright (C) 2013-2026 Efinix Inc. All rights reserved.
// Full license header bsp/efinix/EfxSapphireSocRV64/include/LICENSE.MD
 

#include <stdio.h>
#include "bsp.h"
#include "spiFlash/spiFlash.h"
 
/* -----------------------------------------------------------------------------*/
/*  Public API: Initialization                                          
/* -----------------------------------------------------------------------------*/
 
static const spiFlash_info_t *user_flash_table = NULL;
static size_t                 user_flash_count  = 0;
 
void spiFlash_registerFlash(const spiFlash_info_t *table, size_t count)
{
    user_flash_table = table;
    user_flash_count = count;
}
 
void spiFlash_initController(spiFlash_instance_t *flash) {
    spi_instance_t *spi = flash->inst;
 
    // Hardware Sanity Check from user config
    if (!IS_VALID_CPOL(spi->cpol)) {
            spi->cpol = LOW;
            LOG_WARN(DBG_MOD_SPI_FLASH,"SPI CPOL is not valid, applying default config.");
    }
    if (!IS_VALID_CPHA(spi->cpha)) {
        spi->cpha = DATA_SAMPLED_RISE_EDGE;
        LOG_WARN(DBG_MOD_SPI_FLASH,"SPI CPHA is not valid, applying default config.");
    }
    if (!IS_VALID_MODE(spi->mode)) {
        spi->mode = FULL_DUPLEX_SINGLE_LINE;
        LOG_WARN(DBG_MOD_SPI_FLASH,"SPI MODE is not valid, applying default config.");
    }
 
    if (spi->clkDivider == 0) spi->clkDivider = 2;
    if (spi->ssSetup == 0)    spi->ssSetup    = 5;
    if (spi->ssHold == 0)     spi->ssHold     = 2;
    if (spi->ssDisable == 0)  spi->ssDisable  = 7;
    if (spi->clkDivider == 0 || spi->ssSetup == 0 || spi->ssHold == 0 || spi->ssDisable == 0) {
        LOG_WARN(DBG_MOD_SPI_FLASH,"SPI timing parameters are not valid, applying default config.");
    }
    // Apply Config and wait to be completed.
    spiFlash_applyConfig(flash);
}
 
 
spiFlash_status_t spiFlash_probe(spiFlash_instance_t * flash)
{
    // Initialize SPI driver with User Config, fallback with default config if incorrect input.
    spiFlash_initController(flash);
 
    // Release flash from deep power down.
    spiFlash_wake(flash);
 
    // Identify Flash (Type,Brand,JEDEC_ID, etc ....)
    if (spiFlash_verify(flash) != 0)
        return SPI_FLASH_ERR;
 
    // --- Load Default CMD---
    flash-> mask_qe         = 0x0;
    flash-> cmd_exit_4byte  = CMD_EXIT_4B;
    flash-> cmd_rd_status   = CMD_READ_STATUS_REG_1;
    flash-> cmd_wr_status   = CMD_WRITE_STATUS_REG_1;
 
    // --- Checking quirk for special handling---
    spiFlash_applyQuirks(flash);
 
    // --- Return to 3-Byte Addressing Mode--- 
    spiFlash_exit4ByteAddr(flash);
 
    // If the user provided a custom setup function in the table, run it now.
    if (flash->info->post_init_hook != NULL) {
        flash->info->post_init_hook(flash);
    }
 
    return SPI_FLASH_OK;
}
 
void spiFlash_applyConfig(spiFlash_instance_t *flash){
    spi_instance_t *spi = flash->inst;
    spi_applyConfig(spi);
    spi_waitUntilIdle(spi);
}
 
void spiFlash_wake(spiFlash_instance_t *flash){
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    spiFlash_wake_(flash);
    spi_deselect(inst,flash->cs);
    spi_waitUntilIdle(inst);
    bsp_uDelay(100); // make sure the Flash fully awake
}
 
/* -----------------------------------------------------------------------------*/
/*  Internal API: Initialization                                            
/* -----------------------------------------------------------------------------*/
 
static void spiFlash_wake_(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spi_write(inst, CMD_RELEASE_DEEP_POWER_DOWN);        
}
 
 
 
/* -----------------------------------------------------------------------------*/
/*  SPI FLASH Identify Operation - Public API                                               
/* -----------------------------------------------------------------------------*/
 
u8 spiFlash_readId(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    u8 data = spiFlash_readId_(flash);
    spi_deselect(inst,flash->cs);
    return data;
}
 
u32 spiFlash_readJedecId(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    flash->detected_id = spiFlash_readJedecId_(flash);
    spi_deselect(inst,flash->cs);
    return flash->detected_id;
}
 
const spiFlash_info_t * spiFlash_lookup(u32 detected_id)
{
    // User table first — allows override of built-in entries
    if (user_flash_table != NULL) {
        for (size_t i = 0; i < user_flash_count; i++) {
            if (user_flash_table[i].jedec_id == detected_id)
                return &user_flash_table[i];  // found → stop immediately
        }
        LOG_WARN(DBG_MOD_SPI_FLASH,"User flash is not found/match, checking with known flash.");
    }
 
    // Fallback to built-in
    for (size_t i = 0; known_flash[i].part_no != NULL; i++) {
        if (known_flash[i].jedec_id == detected_id)
            LOG_INFO(DBG_MOD_SPI_FLASH,"Flash is detected from known table.");
            return &known_flash[i];
    }
 
    return NULL;
}
 
spiFlash_status_t spiFlash_verify(spiFlash_instance_t *flash)
{
    // Check JEDEC ID and store it in detected_id variable.
    flash->detected_id = spiFlash_readJedecId(flash);
 
    // Hardware Sanity Check
    if (flash->detected_id == 0x000000 || flash->detected_id == 0xFFFFFF) {
        LOG_ERR(DBG_MOD_SPI_FLASH,"SPI Bus Failure! ID: 0x%06X", flash->detected_id);
        return SPI_FLASH_ERR;
    }
 
    // Identify Flash with user table first, then fallback to built-in table.
    flash->info = spiFlash_lookup(flash->detected_id);
    if (flash->info == NULL) {
        LOG_ERR(DBG_MOD_SPI_FLASH, "Unknown Flash (ID: 0x%06X). Please register ID.", flash->detected_id);
        return SPI_FLASH_ERR;
    }
 
    LOG_INFO(DBG_MOD_SPI_FLASH, "%s Flash is found!",flash->info->part_no);
    LOG_INFO(DBG_MOD_SPI_FLASH, "Detected JEDEC_ID: 0x%X.",flash->detected_id);
 
    return SPI_FLASH_OK;
}
 
 
void spiFlash_applyQuirks(spiFlash_instance_t *flash)
{
    u32 flags = flash->info->flags;
 
    // --- Quirk: Write Protection ---
    if (flags & FLAG_UNLOCK_ON_PROBE) {
        u8 status = spiFlash_readStatusReg(flash);
        if (status & 0xBC) { // Check if any protection bits (BP0-3, SRWD) are actually set
            spiFlash_enableWrite(flash);
            spiFlash_writeStatusReg(flash, status & 0x43); 
            LOG_INFO(DBG_MOD_RTC,"OK: Protection bits cleared.");
        }
    }
 
    // --- Quirk: 4-Byte Exit Command ---
    if (flags & FLAG_4BYTE_EXIT_ISSI) {
        flash->cmd_exit_4byte = CMD_EXIT_4B_ISSI; // ISSI ONLY
    } else {
        flash->cmd_exit_4byte = CMD_EXIT_4B; // Default
    }
 
    // --- Quirk: Quad Enable Configuration ---
    if (flags & FLAG_QE_SR1_BIT6) { //Macronix & ISSI
        flash->mask_qe = QE_BIT6;
        flash->cmd_wr_status = CMD_WRITE_STATUS_REG_1;
    }
 
}
 
/* -----------------------------------------------------------------------------*/
/* Internal API: Identify Operation                                             
/* -----------------------------------------------------------------------------*/
 
static u8 spiFlash_readId_(spiFlash_instance_t *flash){
    spi_instance_t *inst = flash->inst;
    spi_write(inst,CMD_READ_DEVICE_ID);
    spi_write(inst, 0x00); // Dummy Data
    spi_write(inst, 0x00); // Dummy Data
    spi_write(inst, 0x00); // Dummy Data
    return spi_read(inst);
}
 
static u32 spiFlash_readJedecId_(spiFlash_instance_t *flash) {
    spi_instance_t *inst = flash->inst;
    u32 id = 0;
    spi_write(inst, CMD_READ_JEDEC_ID);
    // Ensure the command is sent before reading
    spi_waitUntilIdle(inst);
    // Read 3 bytes and pack them into a 24-bit integer
    id |= (u32)spi_read(inst) << 24; // Manufacturer ID
    id |= (u32)spi_read(inst) << 16;  // Memory Type
    id |= (u32)spi_read(inst) << 8;  // Capacity Code
    return id;
}
 
 
/* -----------------------------------------------------------------------------*/
/*  Public API: Read/Write Operation                                            
/* -----------------------------------------------------------------------------*/
 
u8 spiFlash_write_single(spiFlash_instance_t *flash, u32 flashAddress, u8 *src, u32 len)
{
    spi_instance_t *inst = flash-> inst;
    spiFlash_unlockGlobal(flash);
    spiFlash_eraseSector(flash,flashAddress);
    spiFlash_enableWrite(flash);
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_PAGE_PROGRAM);
    spi_write(inst, (flashAddress>>16) & 0xFF);
    spi_write(inst, (flashAddress>>8) & 0xFF);
    spi_write(inst, (flashAddress>>0) & 0xFF);
    for(int i=0; i<len; i++)
    {
        spi_write(inst, src[i] );
    }
    spi_deselect(inst,flash->cs);
    if (spiFlash_waitBusy(flash) == 1) return SPI_FLASH_ERR;
    spiFlash_lockGlobal(flash);
    return SPI_FLASH_OK;
}
 
void spiFlash_read_single(spiFlash_instance_t *flash, u32 flashAddress, u8 *buffer, u32 len)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_READ_DATA);
    spi_write(inst, (flashAddress>>16) & 0xFF);
    spi_write(inst, (flashAddress>>8) & 0xFF);
    spi_write(inst, (flashAddress>>0) & 0xFF);
    for (u32 i = 0; i < len; i++)
    {
        buffer[i] = spi_read(inst);
    }
    spi_deselect(inst,flash->cs);
}
 
 
/*******************************************************************************
*
* @brief This function read Status Register.
*
* @param reg SPI base address
* @param cs 32-bit bitwise chip select setting
*
******************************************************************************/
u8 spiFlash_readStatusReg(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    spi_write(inst, flash->cmd_rd_status); //Read Status Register
    u8 value = spi_read(inst);
    spi_deselect(inst,flash->cs);
    return value;
}
 
/*******************************************************************************
*
* @brief This function write Status Register.
*
* @param reg SPI base address
* @param cs 32-bit bitwise chip select setting
* @param data 8-bit data
*
******************************************************************************/
void spiFlash_writeStatusReg(spiFlash_instance_t *flash,u8 data)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    spi_write(inst, flash->cmd_wr_status); //Write Status Register
    spi_write(inst, data); //Write Status Register
    spi_deselect(inst,flash->cs);
}
 
void spiFlash_f2m_single(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size)
{
    spi_select(flash->inst,flash->cs);
    spiFlash_f2m_single_(flash, flashAddress, memoryAddress, size);
    spi_deselect(flash->inst,flash->cs);
}
 
void spiFlash_f2m_dual(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size)
{
    spi_select(flash->inst,flash->cs);
    spiFlash_f2m_dual_(flash, flashAddress, memoryAddress, size);
    spi_deselect(flash->inst,flash->cs);
}
 
void spiFlash_f2m_quad(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size)
{
    spiFlash_enableQuadMode(flash);
    spi_select(flash->inst,flash->cs);
    spiFlash_f2m_quad_(flash, flashAddress, memoryAddress, size);
    spi_deselect(flash->inst,flash->cs);
}
 
 
/* -----------------------------------------------------------------------------*/
/* Public API: Enablement Operation                                                 
/* -----------------------------------------------------------------------------*/
 
void spiFlash_enableQuadMode(spiFlash_instance_t *flash)
{
    u8 status = 0;
    spi_instance_t *inst = flash->inst;
 
    // Set Write Enable Latch (WEL) by sending CMD-0x06
    do {
        spiFlash_enableWrite(flash); 
        status = spiFlash_readStatusReg(flash);
        bsp_uDelay(1);
    } while ((status & WEL_BIT) != WEL_BIT); // 0x02 is standard WEL bit
    
    // Mask the existing Status Register Bit-Flip (Winbond/Macronix/ISIS)
    if (flash->info->flags & FLAG_QE_ENABLE_VIA_SR) {
        spiFlash_writeStatusReg(flash, status | flash->mask_qe);
        do {
            status = spiFlash_readStatusReg(flash);
            bsp_uDelay(1);
        } while ((status & flash->mask_qe) != flash->mask_qe);
    } 
    
 
}
 
void spiFlash_enableQPI(spiFlash_instance_t *flash)
{
    u8 status = 0;
    spi_instance_t *inst = flash->inst;
 
    // Set Write Enable Latch (WEL) by sending CMD-0x06
    do {
        spiFlash_enableWrite(flash); 
        status = spiFlash_readStatusReg(flash);
        bsp_uDelay(1);
    } while ((status & WEL_BIT) != WEL_BIT); // 0x02 is standard WEL bit
 
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_ENABLE_QPI);
    spi_deselect(inst,flash->cs);
    
}
 
 
void spiFlash_enableWrite(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_WRITE_ENABLE); // Write Enable Sequence
    spi_deselect(inst,flash->cs);
}
 
u8 spiFlash_exit4ByteAddr(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    
    if (flash->info->flags & FLAG_4BYTE_SUPPORT)
    {
        spi_waitUntilIdle(inst);
        spi_select(inst,flash->cs);
        spi_write(inst,flash->cmd_exit_4byte);
        spi_deselect(inst,flash->cs);
        spi_waitUntilIdle(inst);
        
        return SPI_FLASH_OK;
    }
    else return SPI_FLASH_SKIP;
 
}
 
void spiFlash_lockGlobal(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spiFlash_enableWrite(flash);
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_GLOBAL_LOCK);
    spi_deselect(inst,flash->cs);
}
 
void spiFlash_unlockGlobal(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spiFlash_enableWrite(flash);
    spi_select(inst,flash->cs);
    spi_write(flash->inst, CMD_GLOBAL_UNLOCK);
    spi_deselect(inst,flash->cs);
}
 
spiFlash_status_t spiFlash_waitBusy(spiFlash_instance_t *flash)
{
    u8 out;
    u16 timeout=0;
    while(1)
    {
        bsp_uDelay(1*1000);
        out = spiFlash_readStatusReg(flash);
        if((out & 0x01) ==0x00)
            return SPI_FLASH_OK;
        timeout++;
        //sector erase max=400ms
        if(timeout >=400)
        {
            return SPI_FLASH_ERR; //Time out
        }
    }
}
 
void spiFlash_eraseSector(spiFlash_instance_t *flash, u32 flashAddress)
{
    spi_instance_t *inst = flash->inst;
    spiFlash_enableWrite(flash);
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_SECTOR_ERASE);
    spi_write(inst, (flashAddress>>16)&0xFF);
    spi_write(inst, (flashAddress>>8)&0xFF);
    spi_write(inst, (flashAddress>>0)&0xFF);
    spi_deselect(inst,flash->cs);
    spiFlash_waitBusy(flash);
}
 
/* -----------------------------------------------------------------------------*/
/* Internal: Read/Write Operation                                           
/* -----------------------------------------------------------------------------*/
 
static void spiFlash_f2m_single_(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size){
    spi_instance_t *inst = flash->inst;
    spi_write(inst, CMD_FAST_READ);
    spi_write(inst, flashAddress >> 16);
    spi_write(inst, flashAddress >>  8);
    spi_write(inst, flashAddress >>  0);
    spi_write(inst, 0);
    u8 *ram = (u8 *) memoryAddress;
    for(u32 idx = 0;idx < size;idx++){
        *ram++ = spi_read(inst);
    }
 
}
 
static void spiFlash_f2m_dual_(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size){
    spi_instance_t *inst = flash->inst;
    spi_write(inst, CMD_DUAL_OUTPUT_READ);
    spi_write(inst, flashAddress >> 16);
    spi_write(inst, flashAddress >>  8);
    spi_write(inst, flashAddress >>  0);
    spi_write(inst, 0);
    spi_waitUntilIdle(inst); 
    spi_setDataMode(inst,HALF_DUPLEX_DUAL_LINE);
    u8 *ram = (u8 *) memoryAddress;
    for(u32 idx = 0;idx < size;idx++){
        *ram++ = spi_read(inst);
    }
    spi_setDataMode(inst,FULL_DUPLEX_SINGLE_LINE);// change mode back to single data mode
}
 
static void spiFlash_f2m_quad_(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size){
    spi_instance_t *inst = flash->inst;
    spi_write(inst, CMD_QUAD_OUTPUT_READ);
    spi_write(inst, flashAddress >> 16);
    spi_write(inst, flashAddress >>  8);
    spi_write(inst, flashAddress >>  0);
    spi_write(inst, 0);
    spi_waitUntilIdle(inst); 
    spi_setDataMode(inst, HALF_DUPLEX_QUAD_LINE); // change mode to quad data mode
    uint8_t *ram = (uint8_t *) memoryAddress;
    for(u32 idx = 0;idx < size;idx++){
        *ram++ = spi_read(inst);
    }
    spi_setDataMode(inst, FULL_DUPLEX_SINGLE_LINE); // change mode back to single data mode
}