W25QFlashSPI.cpp

/*
 * W25QFlashSPI.cpp
 *
 *  Created on: Aug 30, 2026
 *      Author: johng
 */
 
#include "W25QFlashSPI.hpp"
 
extern SPI_HandleTypeDef hspi1;
 
W25QFlashSPI::W25QFlashSPI(uint32_t spiTimeoutMs) : _hspi(&hspi1), _spiTimeoutMs(spiTimeoutMs) {
}
 
void W25QFlashSPI::csEnable() {
    HAL_GPIO_WritePin(WQ25_CS_GPIO_Port, WQ25_CS_Pin, GPIO_PIN_RESET);
}
 
void W25QFlashSPI::csDisable() {
    HAL_GPIO_WritePin(WQ25_CS_GPIO_Port, WQ25_CS_Pin, GPIO_PIN_SET);
}
 
void W25QFlashSPI::fillAddress(uint8_t *buf, uint32_t addr) {
    buf[0] = (uint8_t)(addr >> 16);
    buf[1] = (uint8_t)(addr >> 8);
    buf[2] = (uint8_t)(addr);
}
 
HAL_StatusTypeDef W25QFlashSPI::runCommand(uint8_t cmd) {
    csEnable();
    HAL_StatusTypeDef status = HAL_SPI_Transmit(_hspi, &cmd, 1, _spiTimeoutMs);
    csDisable();
    return status;
}
 
HAL_StatusTypeDef W25QFlashSPI::readCommand(uint8_t cmd, uint8_t *resp, uint32_t len) {
    csEnable();
    HAL_StatusTypeDef status = HAL_SPI_Transmit(_hspi, &cmd, 1, _spiTimeoutMs);
    if (status == HAL_OK && len > 0) {
        status = HAL_SPI_Receive(_hspi, resp, len, _spiTimeoutMs);
    }
    csDisable();
    return status;
}
 
HAL_StatusTypeDef W25QFlashSPI::writeCommand(uint8_t cmd, const uint8_t *data, uint32_t len) {
    csEnable();
    HAL_StatusTypeDef status = HAL_SPI_Transmit(_hspi, &cmd, 1, _spiTimeoutMs);
    if (status == HAL_OK && len > 0) {
        status = HAL_SPI_Transmit(_hspi, const_cast<uint8_t *>(data), len, _spiTimeoutMs);
    }
    csDisable();
    return status;
}
 
HAL_StatusTypeDef W25QFlashSPI::eraseCommand(uint8_t cmd, uint32_t addr) {
    HAL_StatusTypeDef status = writeEnable();
    if (status != HAL_OK) {
        return status;
    }
 
    uint8_t header[4];
    header[0] = cmd;
    fillAddress(&header[1], addr);
 
    csEnable();
    status = HAL_SPI_Transmit(_hspi, header, sizeof(header), _spiTimeoutMs);
    csDisable();
    return status;
}
 
HAL_StatusTypeDef W25QFlashSPI::writeEnable() {
    HAL_StatusTypeDef status = runCommand(W25Q_CMD_WRITE_ENABLE);
    return status;
}
 
bool W25QFlashSPI::Init() {
    // Fail-hard: see the class-level Doxygen note on Init() for why a HAL
    // failure here calls Error_Handler() while every other method below
    // propagates instead.
    HAL_StatusTypeDef status = runCommand(W25Q_CMD_ENABLE_RESET);
    if (status != HAL_OK) {
        Error_Handler();
    }
 
    status = runCommand(W25Q_CMD_RESET);
    if (status != HAL_OK) {
        Error_Handler();
    }
 
    HAL_Delay(1); // tRST: chip reset recovery time
 
    uint32_t id = 0;
    if (!readJEDECID(id)) {
        Error_Handler(); // SPI transfer itself failed -- distinct from a merely wrong id below
    }
 
    bool detected = ((id >> 16) & 0xFF) == W25Q_JEDEC_MANUFACTURER_ID;
    return detected; // a *wrong* ID is a legitimate non-fatal outcome, not a HAL fault
}
 
bool W25QFlashSPI::readJEDECID(uint32_t &id) {
    // Not escalated to Error_Handler() here -- this is a caller-facing
    // method, not Init() itself (which calls this and escalates on our
    // behalf). The bool return lets the caller tell "SPI transfer failed"
    // apart from "transfer succeeded, id just isn't a valid W25Q ID".
    uint8_t resp[3] = { 0, 0, 0 };
    HAL_StatusTypeDef status = readCommand(W25Q_CMD_READ_JEDEC_ID, resp, sizeof(resp));
    if (status != HAL_OK) {
        return false;
    }
 
    id = ((uint32_t)resp[0] << 16) | ((uint32_t)resp[1] << 8) | resp[2];
    return true;
}
 
bool W25QFlashSPI::readStatus(uint8_t &status1, uint8_t &status2) {
    HAL_StatusTypeDef status = readCommand(W25Q_CMD_READ_STATUS1, &status1, 1);
    if (status != HAL_OK) {
        return false;
    }
 
    status = readCommand(W25Q_CMD_READ_STATUS2, &status2, 1);
    if (status != HAL_OK) {
        return false;
    }
 
    return true;
}
 
bool W25QFlashSPI::waitUntilReady(uint32_t timeout_ms) {
    uint32_t start = HAL_GetTick();
    uint8_t chipStatus = 0;
 
    do {
        HAL_StatusTypeDef status = readCommand(W25Q_CMD_READ_STATUS1, &chipStatus, 1);
        if (status != HAL_OK) {
            return false; // SPI transfer failure -- propagate, don't escalate (see Init())
        }
 
        if ((chipStatus & 0x01) == 0) { // BUSY bit clear
            return true;
        }
    } while ((HAL_GetTick() - start) < timeout_ms);
 
    return false; // BUSY-bit timeout -- an expected outcome on a long erase,
                  // not a HAL communication failure either way.
}
 
bool W25QFlashSPI::eraseSector(uint32_t addr) {
    HAL_StatusTypeDef status = eraseCommand(W25Q_CMD_ERASE_SECTOR, addr);
    if (status != HAL_OK) {
        return false;
    }
 
    bool ready = waitUntilReady(500); // datasheet typical/max sector erase time varies by capacity
    return ready;
}
 
bool W25QFlashSPI::eraseRange(uint32_t addr, uint32_t len) {
    if (len == 0) {
        return true;
    }
 
    uint32_t firstSector = addr / W25Q_SECTOR_SIZE;
    uint32_t lastSector = (addr + len - 1) / W25Q_SECTOR_SIZE;
 
    for (uint32_t sector = firstSector; sector <= lastSector; sector++) {
        if (!eraseSector(sector * W25Q_SECTOR_SIZE)) {
            return false;
        }
    }
 
    return true;
}
 
bool W25QFlashSPI::eraseBlock(uint32_t addr) {
    HAL_StatusTypeDef status = eraseCommand(W25Q_CMD_ERASE_BLOCK, addr);
    if (status != HAL_OK) {
        return false;
    }
 
    bool ready = waitUntilReady(3000); // datasheet typical/max block erase time varies by capacity
    return ready;
}
 
bool W25QFlashSPI::eraseChip() {
    HAL_StatusTypeDef status = writeEnable();
    if (status != HAL_OK) {
        return false;
    }
 
    status = runCommand(W25Q_CMD_ERASE_CHIP);
    if (status != HAL_OK) {
        return false;
    }
 
    // Chip erase time scales heavily with capacity (16/64/128 Mbit) -- verify
    // this timeout against the specific chip's datasheet before relying on it.
    bool ready = waitUntilReady(100000);
    return ready;
}
 
bool W25QFlashSPI::readBuffer(uint32_t addr, uint8_t *buf, uint32_t len) {
    uint8_t header[4];
    header[0] = W25Q_CMD_READ;
    fillAddress(&header[1], addr);
 
    csEnable();
    HAL_StatusTypeDef status = HAL_SPI_Transmit(_hspi, header, sizeof(header), _spiTimeoutMs);
    if (status == HAL_OK) {
        status = HAL_SPI_Receive(_hspi, buf, len, _spiTimeoutMs);
    }
    csDisable();
 
    return status == HAL_OK;
}
 
bool W25QFlashSPI::writeBuffer(uint32_t addr, const uint8_t *data, uint32_t len) {
    uint32_t written = 0;
 
    while (written < len) {
        uint32_t pageOffset = (addr + written) % W25Q_PAGE_SIZE;
        uint32_t chunk = W25Q_PAGE_SIZE - pageOffset;
        if (chunk > (len - written)) {
            chunk = len - written;
        }
 
        HAL_StatusTypeDef status = writeEnable();
        if (status != HAL_OK) {
            return false;
        }
 
        uint8_t header[4];
        header[0] = W25Q_CMD_PAGE_PROGRAM;
        fillAddress(&header[1], addr + written);
 
        csEnable();
        status = HAL_SPI_Transmit(_hspi, header, sizeof(header), _spiTimeoutMs);
        if (status == HAL_OK) {
            status = HAL_SPI_Transmit(_hspi, const_cast<uint8_t *>(data + written), chunk, _spiTimeoutMs);
        }
        csDisable();
 
        if (status != HAL_OK) {
            return false;
        }
        if (!waitUntilReady(50)) { // page program typical max is a few ms; generous margin
            return false;
        }
 
        written += chunk;
    }
 
    return true;
}