W25QFlashQSPI.cpp

/*
 * W25QFlashQSPI.cpp
 *
 *  Created on: Sep 3, 2026
 *      Author: johng
 */
 
#include "W25QFlashQSPI.hpp"
 
extern QSPI_HandleTypeDef hqspi;
 
namespace {
 
QSPI_CommandTypeDef makeBaseCommand() {
    QSPI_CommandTypeDef cmd = {0};
    cmd.InstructionMode = QSPI_INSTRUCTION_1_LINE;
    cmd.AlternateByteMode = QSPI_ALTERNATE_BYTES_NONE;
    cmd.DummyCycles = 0;
    cmd.DdrMode = QSPI_DDR_MODE_DISABLE;
    cmd.DdrHoldHalfCycle = QSPI_DDR_HHC_ANALOG_DELAY;
    cmd.SIOOMode = QSPI_SIOO_INST_EVERY_CMD;
    return cmd;
}
 
} // namespace
 
W25QFlashQSPI::W25QFlashQSPI(uint32_t qspiTimeoutMs) : _hqspi(&hqspi), _qspiTimeoutMs(qspiTimeoutMs) {
}
 
HAL_StatusTypeDef W25QFlashQSPI::runCommand(uint8_t instruction) {
    QSPI_CommandTypeDef cmd = makeBaseCommand();
    cmd.Instruction = instruction;
    cmd.AddressMode = QSPI_ADDRESS_NONE;
    cmd.DataMode = QSPI_DATA_NONE;
 
    HAL_StatusTypeDef status = HAL_QSPI_Command(_hqspi, &cmd, _qspiTimeoutMs);
    return status;
}
 
HAL_StatusTypeDef W25QFlashQSPI::readCommand(uint8_t instruction, uint8_t *resp, uint32_t len) {
    QSPI_CommandTypeDef cmd = makeBaseCommand();
    cmd.Instruction = instruction;
    cmd.AddressMode = QSPI_ADDRESS_NONE;
    cmd.DataMode = (len > 0) ? QSPI_DATA_1_LINE : QSPI_DATA_NONE;
    cmd.NbData = len;
 
    HAL_StatusTypeDef status = HAL_QSPI_Command(_hqspi, &cmd, _qspiTimeoutMs);
    if (status == HAL_OK && len > 0) {
        status = HAL_QSPI_Receive(_hqspi, resp, _qspiTimeoutMs);
    }
    return status;
}
 
HAL_StatusTypeDef W25QFlashQSPI::writeCommand(uint8_t instruction, const uint8_t *data, uint32_t len) {
    QSPI_CommandTypeDef cmd = makeBaseCommand();
    cmd.Instruction = instruction;
    cmd.AddressMode = QSPI_ADDRESS_NONE;
    cmd.DataMode = (len > 0) ? QSPI_DATA_1_LINE : QSPI_DATA_NONE;
    cmd.NbData = len;
 
    HAL_StatusTypeDef status = HAL_QSPI_Command(_hqspi, &cmd, _qspiTimeoutMs);
    if (status == HAL_OK && len > 0) {
        status = HAL_QSPI_Transmit(_hqspi, const_cast<uint8_t *>(data), _qspiTimeoutMs);
    }
    return status;
}
 
HAL_StatusTypeDef W25QFlashQSPI::eraseCommand(uint8_t instruction, uint32_t addr) {
    HAL_StatusTypeDef status = writeEnable();
    if (status != HAL_OK) {
        return status;
    }
 
    QSPI_CommandTypeDef cmd = makeBaseCommand();
    cmd.Instruction = instruction;
    cmd.AddressMode = QSPI_ADDRESS_1_LINE;
    cmd.AddressSize = QSPI_ADDRESS_24_BITS;
    cmd.Address = addr;
    cmd.DataMode = QSPI_DATA_NONE;
 
    status = HAL_QSPI_Command(_hqspi, &cmd, _qspiTimeoutMs);
    return status;
}
 
HAL_StatusTypeDef W25QFlashQSPI::writeEnable() {
    HAL_StatusTypeDef status = runCommand(W25Q_CMD_WRITE_ENABLE);
    return status;
}
 
bool W25QFlashQSPI::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(); // QUADSPI 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 W25QFlashQSPI::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 "QUADSPI 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 W25QFlashQSPI::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 W25QFlashQSPI::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; // QUADSPI 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 W25QFlashQSPI::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 W25QFlashQSPI::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 W25QFlashQSPI::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 W25QFlashQSPI::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 W25QFlashQSPI::readBuffer(uint32_t addr, uint8_t *buf, uint32_t len) {
    QSPI_CommandTypeDef cmd = makeBaseCommand();
    cmd.Instruction = W25Q_CMD_READ;
    cmd.AddressMode = QSPI_ADDRESS_1_LINE;
    cmd.AddressSize = QSPI_ADDRESS_24_BITS;
    cmd.Address = addr;
    cmd.DataMode = QSPI_DATA_1_LINE;
    cmd.NbData = len;
 
    HAL_StatusTypeDef status = HAL_QSPI_Command(_hqspi, &cmd, _qspiTimeoutMs);
    if (status == HAL_OK) {
        status = HAL_QSPI_Receive(_hqspi, buf, _qspiTimeoutMs);
    }
 
    return status == HAL_OK;
}
 
bool W25QFlashQSPI::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;
        }
 
        QSPI_CommandTypeDef cmd = makeBaseCommand();
        cmd.Instruction = W25Q_CMD_PAGE_PROGRAM;
        cmd.AddressMode = QSPI_ADDRESS_1_LINE;
        cmd.AddressSize = QSPI_ADDRESS_24_BITS;
        cmd.Address = addr + written;
        cmd.DataMode = QSPI_DATA_1_LINE;
        cmd.NbData = chunk;
 
        status = HAL_QSPI_Command(_hqspi, &cmd, _qspiTimeoutMs);
        if (status == HAL_OK) {
            status = HAL_QSPI_Transmit(_hqspi, const_cast<uint8_t *>(data + written), _qspiTimeoutMs);
        }
 
        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;
}