DadDrivers::cW25Q128

Namespace: DadDrivers::cW25Q128
Files: W25Q128.h / W25Q128.cpp
Directory: DAD_FORGE/Drivers
Description: Complete implementation of the Winbond W25Q128JV (16MB) QSPI flash controller with Quad I/O and memory mapping support

📋 Class Description

The cW25Q128 class implements the iQSPI_FlashMemory interface for the Winbond W25Q128JV-IQ/JQ QSPI flash chip (16 MB, 16777216 bytes). It supports Quad I/O mode operations (4 input/output lines), direct memory mapping for fast CPU access, and all standard Winbond datasheet commands. Initialization includes software reset, status register configuration (block protection, driver strength, quad enable), and automatic Quad I/O mode activation. The class automatically handles transitions between memory-mapped and indirect modes based on required operations.

🎯 Enumerations and Associated Structures

W25Q128_Commands

Element / Variable	Type / Value (if applicable)	Description
`CMD_WRITE_ENABLE`	0x06	Write Enable (WREN) - enables writes
`CMD_WRITE_DISABLE`	0x04	Write Disable (WRDI) - disables writes
`CMD_READ_STATUS_REG1`	0x05	Read Status Register-1 (RDSR1)
`CMD_READ_STATUS_REG2`	0x35	Read Status Register-2 (RDSR2)
`CMD_READ_STATUS_REG3`	0x15	Read Status Register-3 (RDSR3)
`CMD_WRITE_STATUS_REG1`	0x01	Write Status Register-1 (WRSR1)
`CMD_WRITE_STATUS_REG2`	0x31	Write Status Register-2 (WRSR2)
`CMD_WRITE_STATUS_REG3`	0x11	Write Status Register-3 (WRSR3)
`CMD_READ_ID`	0xAB	Read ID / Release Power Down (RDID/RDPD)
`CMD_READ_JEDEC_ID`	0x9F	Read JEDEC ID (RDJDID)
`CMD_READ_NORMAL`	0x03	Normal Read (READ) - 1-1-1 mode
`CMD_READ_FAST`	0x0B	Fast Read (FAST_READ) - 1-2-1 mode
`CMD_READ_FAST_QUAD_IO`	0x6B	Fast Read Quad I/O (QREAD) - 4-4-4 mode
`CMD_PAGE_PROGRAM`	0x02	Page Program (PP) - page write
`CMD_QUAD_PAGE_PROGRAM`	0x32	Quad Input Page Program (QPP)
`CMD_SECTOR_ERASE`	0x20	Sector Erase 4KB (SE)
`CMD_BLOCK_ERASE_32K`	0x52	Block Erase 32KB (BE32)
`CMD_BLOCK_ERASE_64K`	0xD8	Block Erase 64KB (BE64)
`CMD_CHIP_ERASE`	0xC7	Chip Erase (CE) - full erase
`CMD_POWER_DOWN`	0xB9	Deep Power Down (DP)
`CMD_RELEASE_POWER_DOWN`	0xAB	Release Power Down (RPD)
`CMD_NOP`	0x00	No Operation (NOP)

W25Q128_StatusReg1

Bit union for Status Register 1:

Bit	Name	Description
0	BUSY	Busy flag (1=busy, 0=ready)
1	WEL	Write Enable Latch (1=writes enabled)
2	BP0	Block Protection Bit 0
3	BP1	Block Protection Bit 1
4	BP2	Block Protection Bit 2
5	TB	Top/Bottom Block Protect
6	SEC	Sector/Block Protect
7	SRP0	Status Register Protect 0

W25Q128_StatusReg2

Bit union for Status Register 2:

Bit	Name	Description
0	SRP1	Status Register Protect 1
1	QE	Quad Enable (1=Quad mode enabled)
2	Reserved	Reserved for future use
3	LB1	Security Register Lock Bit 1
4	LB2	Security Register Lock Bit 2
5	LB3	Security Register Lock Bit 3
6	CMP	Complement Protect
7	SUS	Suspend Status

W25Q128_StatusReg3

Bit union for Status Register 3:

Bit	Name	Description
0-1	RFU1/RFU2	Reserved for future use
2	WPS	Write Protect Selection
3-4	RFU3/RFU4	Reserved for future use
5	DRV0	Output Drive Strength 0
6	DRV1	Output Drive Strength 1
7	HOLD_RST	/HOLD or /RESET Function

📚 Public Methods

Init

Element	Details
Method	`HAL_StatusTypeDef Init(QSPI_HandleTypeDef* phqspi, bool DualMode = false, uint32_t MemoryMappedBaseAddress = 0x90000000)`
Description	Initializes the QSPI controller and W25Q128JV flash memory. Performs a complete software reset (Enable Reset + Reset Device), configures status registers 1, 2, and 3 (disables block protection, enables Quad mode, configures driver strength), waits for all operations to complete (WaitWhileBusy), then activates memory-mapped mode. In DualMode, prepares configuration for two flash chips in parallel.
Parameter(s)
`phqspi`	Pointer to the configured HAL QSPI handle
`DualMode`	Flag enabling dual flash mode (two W25Q128 chips in parallel), default false
`MemoryMappedBaseAddress`	Base address for memory mapping in CPU address space, default 0x90000000
Return	HAL status code: `HAL_OK` success, `HAL_ERROR` initialization failure

ModeMemoryMap

Element	Details
Method	`HAL_StatusTypeDef ModeMemoryMap()`
Description	Configures the flash memory in mapped mode for direct CPU access. Flushes CPU caches (ICache and DCache) on the mapped region. The CPU can then read the entire flash capacity as if it were RAM.
Parameter(s)	None
Return	HAL status code: `HAL_OK` success, `HAL_ERROR` configuration failure

ModeIndirect

Element	Details
Method	`HAL_StatusTypeDef ModeIndirect()`
Description	Restores indirect access mode after using memory mapping. Aborts the memory-mapped session, returns to standard command mode where each operation (READ, WRITE, ERASE) requires an explicit QSPI instruction. Required before any write or erase operation.
Parameter(s)	None
Return	HAL status code: `HAL_OK` success, `HAL_ERROR` configuration failure

Read

Element	Details
Method	`HAL_StatusTypeDef Read(uint8_t* pData, uint32_t Address, uint32_t NbData)`
Description	Reads data from the W25Q128 flash memory in Quad I/O mode. The output buffer must be allocated by the caller. If in mapped mode, switches to indirect mode then returns to mapped mode after reading.
Parameter(s)
`pData`	Pointer to the read buffer where data will be stored
`Address`	Starting read address in the flash memory (Memory-mapped address)
`NbData`	Number of bytes to read
Return	HAL status code: `HAL_OK` success, `HAL_TIMEOUT` read timeout, `HAL_ERROR` error

Write

Element	Details
Method	`HAL_StatusTypeDef Write(uint8_t* pData, uint32_t Address, uint32_t NbData)`
Description	Writes data to the W25Q128 flash memory in Quad I/O mode. Uses the Quad Input Page Program command (0x32). If in mapped mode, switches to indirect mode then returns to mapped mode after writing.
Parameter(s)
`pData`	Pointer to the write buffer containing data to be programmed
`Address`	Starting write address in the flash memory (Memory-mapped address)
`NbData`	Number of bytes to write
Return	HAL status code: `HAL_OK` success, `HAL_TIMEOUT` programming timeout, `HAL_ERROR` error

EraseBlock4K

Element	Details
Method	`HAL_StatusTypeDef EraseBlock4K(uint32_t Address)`
Description	Erases a 4 KB sector (or 8 KB in DualMode) of the W25Q128 flash memory. After erasure, all bits in the sector are set to 1.
Parameter(s)
`Address`	Starting address of the sector to erase (Memory-mapped address)
Return	HAL status code: `HAL_OK` success, `HAL_TIMEOUT` erase timeout, `HAL_ERROR` error

EraseBlock32K

Element	Details
Method	`HAL_StatusTypeDef EraseBlock32K(uint32_t Address)`
Description	Erases a 32 KB block (or 64 KB in DualMode) of the W25Q128 flash memory. After erasure, all bits in the block are set to 1.
Parameter(s)
`Address`	Starting address of the block to erase (Memory-mapped address)
Return	HAL status code: `HAL_OK` success, `HAL_TIMEOUT` erase timeout, `HAL_ERROR` error

EraseBlock64K

Element	Details
Method	`HAL_StatusTypeDef EraseBlock64K(uint32_t Address)`
Description	Erases a 64 KB block (or 128 KB in DualMode) of the W25Q128 flash memory. After erasure, all bits in the block are set to 1.
Parameter(s)
`Address`	Starting address of the block to erase (Memory-mapped address)
Return	HAL status code: `HAL_OK` success, `HAL_TIMEOUT` erase timeout, `HAL_ERROR` error

EraseChip

Element	Details
Method	`HAL_StatusTypeDef EraseChip()`
Description	Erases the entire W25Q128JV flash chip (16 MB). After erasure, all bits in the flash memory are set to 1.
Parameter(s)	None
Return	HAL status code: `HAL_OK` success, `HAL_TIMEOUT` chip erase timeout, `HAL_ERROR` error

getSize

Element	Details
Method	`uint32_t getSize() const`
Description	Returns the total size of the W25Q128 flash memory: 16777216 bytes (16 MB). Constant value based on the W25Q128JV model. Useful for address validation and operation boundaries.
Parameter(s)	None
Return	`uint32_t` value: 16777216 (16 MB in bytes)

getFlashID

Element	Details
Method	`HAL_StatusTypeDef getFlashID(FlashID* pID)`
Description	Reads the W25Q128 device identification. Sends the Read ID command (0xAB) and reads the three identification bytes: Manufacturer ID (0xEF for Winbond), Device Type (0x40 or 0x70 depending on JV-IM/JV-IQ variant), Capacity (0x18 = 16 MB).
Parameter(s)
`pID`	Pointer to the FlashID structure to be filled with identification
Return	HAL status code: `HAL_OK` success, `HAL_ERROR` read failed

🔒 Protected/Private Methods

No protected or private methods.

📦 Data Members (Variables)

Public Variables

No public variables.

Protected/Private Variables

Member	Type	Description
`m_pQSPI`	`QSPI_HandleTypeDef*`	Pointer to the HAL QSPI handle configured for the W25Q128 chip
`m_MemoryMappedBaseAddress`	`uint32_t`	Base address for memory mapping (0x90000000 by default)
`m_MappedMode`	`bool`	Flag indicating whether memory is in direct mapped mode (true) or indirect command mode (false)
`m_DualMode`	`bool`	Flag enabling dual flash mode (two W25Q128 chips in parallel)

💡 Usage Example

#include "W25Q128.h"

using namespace DadDrivers;

int main()
{
    QSPI_HandleTypeDef hqspi;  // Configured by HAL_QSPI_Init
    
    // W25Q128JV flash initialization
    cW25Q128 flash;
    
    if (flash.Init(&hqspi, false, 0x90000000) != HAL_OK) {
        Error_Handler();
    }
    
    // Identification verification
    FlashID id;
    if (flash.getFlashID(&id) == HAL_OK) {
        printf("Manufacturer: 0x%02X\n", id.ManufactuerID);  // 0xEF = Winbond
        printf("Device ID: 0x%02X %02X\n", 
               id.MemoryType, id.Capacity);  // 0x4018 or 0x7018
    }
    
    // Data write (page size = 256 bytes)
    uint8_t data[256] = {0xAA, 0x55, 0x88, 0x00};  // Test pattern
    if (flash.Write(data, 0x90000000, 256) == HAL_OK) {
        printf("Write completed\n");
    }

    // Data read from flash
    uint8_t buffer[256];
    if (flash.Read(buffer, 0x90000000, 256) == HAL_OK) {
        printf("Read: %02X %02X %02X %02X\n", 
               buffer[0], buffer[1], buffer[2], buffer[3]);
    }
    
    // 32K block erase
    if (flash.EraseBlock32K(0x90000000) == HAL_OK) {
        printf("32K block erased\n");
    }
    
    // Memory mapping for fast CPU access
    if (flash.ModeMemoryMap() == HAL_OK) {
        // Direct read from mapped address (as if it were RAM)
        uint8_t* mappedAddr = (uint8_t*)0x90000000;
        *mappedAddr = 0xDEADBEEF;  // Direct write
        
        printf("Read value: %02X\n", *mappedAddr);
        
        // Return to indirect mode before erase/programming
        flash.ModeIndirect();
    }

    return 0;
}