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                                          
/* -----------------------------------------------------------------------------*/
 
void spiFlash_init_controller(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;
    if (!IS_VALID_CPHA(spi->cpha)) spi->cpha = DATA_SAMPLED_RISE_EDGE;
    if (!IS_VALID_MODE(spi->mode)) spi->mode = FULL_DUPLEX_SINGLE_LINE;
 
    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->ssDisable == 0)  spi->ssDisable  = 7;
 
    // Apply Config and wait to be completed.
    spi_applyConfig(spi);
    spi_waitUntilIdle(spi);
}
 
 
spiFlash_status_t spiFlash_probe(spiFlash_instance_t * flash, const spiFlash_info_t *user_flash)
{
    // Initialize SPI driver with User Config, fallback with default config if incorrect input.
    spiFlash_init_controller(flash);
 
    // Release flash from deep power down.
    spiFlash_wake(flash);
 
    // Identify Flash (Type,Brand,JEDEC_ID, etc ....)
    if (spiFlash_verify(flash, user_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_wake(spiFlash_instance_t *flash){
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    spiFlash_wake_(flash);
    spi_diselect(inst,flash->cs);
    spi_waitUntilIdle(inst);
    bsp_uDelay(100); // make sure the Flash fully awake
}
 
 
/* -----------------------------------------------------------------------------*/
/*  Internal API: Initialization                                            
/* -----------------------------------------------------------------------------*/
 
static 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_writeEnable(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_SR2_BIT1) { //Windbond ONLY
        flash->mask_qe = QE_BIT1; 
        flash->cmd_rd_status = CMD_READ_STATUS_REG_2; 
        flash->cmd_wr_status = CMD_WRITE_STATUS_REG_2; 
    } 
    else if (flags & FLAG_QE_SR1_BIT6) { //Macronix & ISSI
        flash->mask_qe = QE_BIT6; 
        flash->cmd_wr_status = CMD_WRITE_STATUS_REG_1;
    }
 
}
 
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                                               
/* -----------------------------------------------------------------------------*/
 
spiFlash_status_t spiFlash_verify(spiFlash_instance_t *flash, const spiFlash_info_t *user_flash)
{
    // Check JEDEC ID and store it in detected_id variable.
    flash->detected_id = spiFlash_jedec_id(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;
    }
 
    // Initialize to safe state
    flash->info = NULL; 
    const spiFlash_info_t* tables[] = { user_flash, known_flash };
    // Identify Flash
    for (int i = 0; i < 2; i++) {
        if (tables[i] != NULL) {
            flash->info = identifyFlash(flash->detected_id, tables[i]);
            if (flash->info == NULL && i ==0) LOG_WARN(DBG_MOD_SPI_FLASH,
            "User flash is not found/match, checking with known flash."); // userflash not exist.
            if (flash->info != NULL) break; // Found a match!
        }
    }
 
    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;
}
 
 
u8 spiFlash_read_id(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    u8 data = spiFlash_read_id_(flash);
    spi_diselect(inst,flash->cs);
    return data;
}
 
u32 spiFlash_jedec_id(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spi_select(inst,flash->cs);
    flash->detected_id = spiFlash_jedec_id_(flash);
    spi_select(inst,flash->cs);
    return flash->detected_id;
}
 
 
/* -----------------------------------------------------------------------------*/
/* Internal API: Identify Operation                                             
/* -----------------------------------------------------------------------------*/
 
static const spiFlash_info_t * identifyFlash(u32 detected_id, const spiFlash_info_t *table)
{
    if (table == NULL) return NULL; // If NULL, expect to use generic flash. (UserFlash not exist)
 
    for (int i = 0; table[i].part_no != NULL; i++) {
        if (table[i].jedec_id == detected_id) {
            return &table[i];
        }
    }
    return NULL; //Return user table (UserFlash not match)
}
 
 
static u8 spiFlash_read_id_(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_jedec_id_(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                                            
/* -----------------------------------------------------------------------------*/
 
// Use to write 256 byte only!
u8 spiFlash_write(spiFlash_instance_t *flash, u32 flashAddress, u8 *src, u32 len)
{
    spi_instance_t *inst = flash-> inst;
    spiFlash_globalUnlock(flash);
    spiFlash_sectorErase(flash,flashAddress);
    spiFlash_writeEnable(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_diselect(inst,flash->cs);
    if (spiFlash_waitBusy(flash) == 1) return SPI_FLASH_ERR;
    spiFlash_globalLock(flash);
    return SPI_FLASH_OK;
}
 
 
u8 spiFlash_write_quad(spiFlash_instance_t *flash, u32 flashAddress, u8 *src, u32 len)
{
    spi_instance_t *inst = flash-> inst;
    spiFlash_globalUnlock(flash);
    spiFlash_sectorErase(flash,flashAddress);
    spiFlash_writeEnable(flash);
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_QUAD_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_diselect(inst,flash->cs);
    if (spiFlash_waitBusy(flash) == 1) return SPI_FLASH_ERR;
    spiFlash_globalLock(flash);
    return SPI_FLASH_OK;
}
 
void spiFlash_read(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_diselect(inst,flash->cs);
}
 
void spiFlash_read_quad(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_QUAD_OUTPUT_READ); 
    spi_write(inst, (flashAddress >> 16) & 0xFF);
    spi_write(inst, (flashAddress >> 8)  & 0xFF);
    spi_write(inst, (flashAddress >> 0)  & 0xFF);
    spi_write(inst, 0x00); 
    spi_write(inst, 0);
    spi_write(inst, 0);
    for (u32 i = 0; i < len; i++)
    {
        buffer[i] = spi_read(inst);
    }
    spi_diselect(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_diselect(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_diselect(inst,flash->cs);
}
 
 
void spiFlash_f2m(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size)
{
    spi_select(flash->inst,flash->cs);
    spiFlash_f2m_(flash, flashAddress, memoryAddress, size);
    spi_diselect(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_dual_f2m_(flash, flashAddress, memoryAddress, size);
    spi_diselect(flash->inst,flash->cs);
}
 
void spiFlash_f2m_quad(spiFlash_instance_t *flash, u32 flashAddress, uintptr_t memoryAddress, u32 size)
{
    spi_select(flash->inst,flash->cs);
    spiFlash_quad_f2m_(flash, flashAddress, memoryAddress, size);
    spi_diselect(flash->inst,flash->cs);
}
 
 
/* -----------------------------------------------------------------------------*/
/* Public API: Enablement Operation                                                 
/* -----------------------------------------------------------------------------*/
 
void spiFlash_enable_quad_access(spiFlash_instance_t *flash)
{
    u8 status = 0;
    spi_instance_t *inst = flash->inst;
 
    // Set Write Enable Latch (WEL) by sending CMD-0x06
    do {
        spiFlash_writeEnable(flash); 
        status = spiFlash_readStatusReg(flash);
        bsp_uDelay(1);
    } while ((status & WEL_BIT) != WEL_BIT); // 0x02 is standard WEL bit
    
    // 1. Mask the existing Status Register Bit-Flip (Winbond/Macronix)
    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);
    } 
    
    // 2. Direct write to register (GigaDevice)
    else if (flash->info->flags & FLAG_QE_CMD_38) {
        spi_select(inst,flash->cs);
        spi_write(inst, CMD_ENABLE_QUAD_GD);
        spi_diselect(inst,flash->cs);
    }
}
 
 
void spiFlash_writeEnable(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_diselect(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_diselect(inst,flash->cs);
        spi_waitUntilIdle(inst);
        
        return SPI_FLASH_OK;
    }
    else return SPI_FLASH_SKIP;
 
}
 
void spiFlash_globalLock(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spiFlash_writeEnable(flash);
    spi_select(inst,flash->cs);
    spi_write(inst, CMD_GLOBAL_LOCK);
    spi_diselect(inst,flash->cs);
}
 
void spiFlash_globalUnlock(spiFlash_instance_t *flash)
{
    spi_instance_t *inst = flash->inst;
    spiFlash_writeEnable(flash);
    spi_select(inst,flash->cs);
    spi_write(flash->inst, CMD_GLOBAL_UNLOCK);
    spi_diselect(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_sectorErase(spiFlash_instance_t *flash, u32 flashAddress)
{
    spi_instance_t *inst = flash->inst;
    spiFlash_writeEnable(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_diselect(inst,flash->cs);
    spiFlash_waitBusy(flash);
}
 
/* -----------------------------------------------------------------------------*/
/* Internal: Read/Write Operation                                           
/* -----------------------------------------------------------------------------*/
 
static void spiFlash_f2m_(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_dual_f2m_(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
}
 
//TODO: Need to test for gigabit device!! 
static void spiFlash_quad_f2m_(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
}