# SPI W25QXX Example

## Overview

This sample demonstrates how to access SPI NOR Flash devices such as W25QXX on K230. It covers device identification, erase/write/read verification, boundary tests, and performance measurements.

## Functional Description

### Main Features

- Read JEDEC ID and match the device table
- Automatically handle 3-byte and 4-byte address modes
- Erase, write, read back, and compare
- Test boundary addresses
- Measure transfer and erase throughput
- Select controller, CS pin, baud rate, test type, address, and size from the command line

### Hardware Connection

The W25QXX device is connected to K230 through SPI:

| W25QXX Pin | K230 Side | Description |
| --- | --- | --- |
| `VCC` | `3.3V` | power |
| `GND` | `GND` | ground |
| `CLK` | SPI clock pin | SPI clock |
| `DO` | SPI MISO pin | data output |
| `DI` | SPI MOSI pin | data input |
| `CS` | SPI chip-select pin | chip select |
| `WP/HOLD` | `3.3V` | write-protect / hold disabled |

### Flash Notes

- standard SPI interface
- page size: `256 bytes`
- sample-compatible parts include W25Q16, W25Q32, W25Q64, and W25Q128

### Common Commands Covered

| Command | Description |
| --- | --- |
| `0x05` | read status register |
| `0x06` | write enable |
| `0x20` | 4 KB sector erase |
| `0x52` | 32 KB block erase |
| `0xD8` | 64 KB block erase |
| `0xC7` | chip erase |
| `0x02` | page program |
| `0x03` | read data |
| `0x9F` | read JEDEC ID |

### Main Functions in the Current Source

- `flash_create()`
- `flash_detect_device()`
- `flash_erase_sector()`
- `flash_write()`
- `flash_read_data()`
- `test_read_write_with_params()`
- `test_performance_with_params()`

## Hardware Notes

The flash is connected over standard SPI. The sample commonly uses QSPI1 as the default controller, and supports devices such as W25Q16, W25Q32, W25Q64, and W25Q128.

## Build and Run

Build the sample in its example directory, then run it on the board with the desired SPI parameters. Review the source defaults if your board uses different controller or pin assignments.

### Typical Test Scope

The sample is intended to validate:

- basic flash identification
- sector erase and page programming
- data readback at normal and boundary addresses
- throughput behavior for write and read paths

## Source Location

Demo source path: `src/rtsmart/examples/peripheral/spi_w25qxx`

Main source file: `test_spi_wq128.c`

## Usage

### Build

#### Firmware Build

Enable the SPI W25QXX example in `make menuconfig`, then rebuild the firmware.

#### Standalone Build

```shell
cd src/rtsmart/examples/peripheral/spi_w25qxx
make
```

### Hardware Preparation

1. prepare a W25QXX-series flash module
1. wire it according to the pin table above
1. verify power and SPI signal connections

### Run

```shell
cd /sdcard/app/examples/peripheral
./spi_w25qxx.elf
```

### Command-Line Arguments

| Argument | Short | Default | Description |
| --- | --- | --- | --- |
| `--help` | `-h` | - | show help |
| `--spi-id` | `-i` | `2` | SPI controller ID |
| `--cs-pin` | `-c` | `11` | CS GPIO pin |
| `--baudrate` | `-b` | `10` | SPI baudrate in MHz |
| `--test` | `-t` | `all` | `info/basic/rw/boundary/perf/all` |
| `--address` | `-a` | `auto` | start address in hex |
| `--size` | `-s` | `auto` | test size in KB |

#### `test` Argument Options

The `test` argument supports:

- `info`
- `basic`
- `rw`
- `boundary`
- `perf`
- `all`

#### SPI Controller ID Notes

Select the SPI controller ID that matches the actual flash connection on your board.

#### Address and Size Notes

Use `address` and `size` to select the start region and test length. Make sure the selected range is valid for the connected flash device.

### View Help

```shell
./spi_w25qxx.elf --help
```

### Example Commands

```shell
./spi_w25qxx.elf
./spi_w25qxx.elf -i 1 -c 14 -b 5
./spi_w25qxx.elf -t perf -a 0x100000 -s 64
./spi_w25qxx.elf -i 0 -t info
./spi_w25qxx.elf -i 1 -t basic -b 20
```

### Expected Result

The sample prints a summary of the selected tests, including device information, erase/write/read verification, boundary checks, and performance results. On success, it reports that all tests passed.

```{admonition} Tip
Before using SPI flash, make sure the FPIOA pinmux is configured correctly. The target region must normally be erased before writing, and larger-capacity parts may require 4-byte address-mode handling.
```