w25q_validation.hpp

/*
 * w25q_validation.hpp
 *
 * Destructive validation test suite for the W25QFlashQSPI driver, adapted
 * from the SRAM validation suite in F439_CPP_AS6C4008_FMC_DaughterBoard_01
 * (sram_validation.c/.h -- same architecture: test-ID/phase/status enums,
 * one persistent report struct, self-contained per-test functions, a
 * RunAll() orchestrator).
 *
 * Differences from the SRAM version, and why:
 *  - No address-alias test. That test exists to catch mis-wired/stuck
 *    parallel address lines on the FMC bus. QSPI's address phase rides on
 *    the same 1-4 data/address lines as everything else, with no separate
 *    external address bus to mis-wire; a wiring mistake here shows up as total communication
 *    failure or a wrong JEDEC ID, both already caught by Init().
 *  - Every pattern write is preceded by an erase. NOR flash can only clear
 *    bits (1->0) via Page Program; setting a bit back to 1 requires an
 *    erase first. The SRAM version can freely write any value at any time,
 *    so it never needed this.
 *  - No whole-device full-sweep/full-range test. SRAM has unlimited write
 *    endurance; NOR flash sectors have a finite erase/program cycle count
 *    (commonly ~100,000 cycles), so treating a 16MB chip as disposable on
 *    every test run is a real cost, not just a time cost. Tests are scoped
 *    to a single sector instead.
 *  - Added an erased-state test (verify every byte reads 0xFF after erase)
 *    and a page-boundary test (write spans two pages, exercising
 *    writeBuffer()'s internal per-page splitting) -- both flash-specific
 *    concerns with no SRAM equivalent.
 *
 * This suite overwrites the first sector (W25Q_SECTOR_SIZE bytes) starting
 * at W25Q_VALIDATION_BASE_ADDR. Run it only when destroying that sector's
 * contents is acceptable -- see W25Q_VALIDATION_TEST_ENABLE in main.c, which
 * keeps this suite from running as part of the normal demo path.
 *
 *  Created on: Aug 30, 2026
 *      Author: johng
 */
 
#ifndef W25Q_W25Q_VALIDATION_HPP_
#define W25Q_W25Q_VALIDATION_HPP_
 
#include "main.h"
#include "W25QFlashQSPI.hpp"
 
#define W25Q_VALIDATION_BASE_ADDR          ((uint32_t)0x000000u)
 
#define W25Q_VALIDATION_SMALL_RANGE_SIZE   ((uint32_t)256u)
 
#define W25Q_VALIDATION_PATTERN_TEST_SIZE  ((uint32_t)256u)
 
#define W25Q_VALIDATION_BOUNDARY_TEST_SIZE ((uint32_t)512u)
 
typedef enum {
    W25Q_VALIDATION_TEST_NONE = 0,
    W25Q_VALIDATION_TEST_ERASED_STATE,
    W25Q_VALIDATION_TEST_SMALL_RANGE,
    W25Q_VALIDATION_TEST_PATTERN,
    W25Q_VALIDATION_TEST_PAGE_BOUNDARY
} w25qValidationTestId_t;
 
typedef enum {
    W25Q_VALIDATION_PHASE_IDLE = 0,
    W25Q_VALIDATION_PHASE_ERASE,
    W25Q_VALIDATION_PHASE_FILL,
    W25Q_VALIDATION_PHASE_VERIFY
} w25qValidationPhase_t;
 
typedef enum {
    W25Q_VALIDATION_STATUS_PASS = 0,
    W25Q_VALIDATION_STATUS_FAIL
} w25qValidationStatus_t;
 
typedef struct {
    w25qValidationStatus_t status;      
    w25qValidationTestId_t failedTest;  
    w25qValidationPhase_t failedPhase;  
    uint32_t failedOffset;              
    uint8_t expectedValue;              
    uint8_t actualValue;                
    uint32_t testsRun;                  
} w25qValidationReport_t;
 
class W25QValidation {
public:
    explicit W25QValidation(W25QFlashQSPI &flash);
 
    const w25qValidationReport_t *RunAll();
 
    const w25qValidationReport_t *GetReport() const;
 
private:
    W25QFlashQSPI &_flash;
    w25qValidationReport_t _report;
 
    void resetReport();
    void recordFailure(w25qValidationTestId_t testId, w25qValidationPhase_t phase,
            uint32_t offset, uint8_t expectedValue, uint8_t actualValue);
    void printFailure() const;
    static const char *getTestName(w25qValidationTestId_t testId);
    static const char *getPhaseName(w25qValidationPhase_t phase);
 
    bool runErasedStateTest();
 
    bool runSmallRangeTest();
 
    bool runPatternTest();
 
    bool runPageBoundaryTest();
};
 
#endif /* W25Q_W25Q_VALIDATION_HPP_ */