Register Map

Note

The tables on this page are generated at docs-build time from docs/regs.yaml (docs/gen_regmap.py) — the YAML file is the single source of truth. The same generator also produces the C header sw/include/qspi_regs.h (register offsets, bit fields, field encodings), which is checked into the repository so software can consume it without running the generator; CI fails if it is out of date. Register changes must be made in the YAML file (and in the RTL, src/qspi_pkg.sv), never in this page or the header.

Base address: 0x2000_0000 (hatch SoC, window UserQspiCfg)

Offset	Register	Reset	Description
0x00	CR	0x00000000	Control Register
0x04	DCR	0x00000010	Device Configuration Register
0x08	SR	0x00000000	Status Register (read-only)
0x0C	FCR	0x00000000	Flag Clear Register
0x10	DLR	0x00000000	Data Length Register
0x14	CCR	0x00000000	Communication Configuration Register (frame format + functional mode)
0x18	AR	0x00000000	Address Register
0x1C	ABR	0x00000000	Alternate Bytes Register
0x20	DR	—	Data Register (FIFO port)
0x24	WCCR	0x00000000	Write Communication Configuration Register (frame format for memory-mapped WRITES)

CR — offset 0x00

Control Register. Reset: 0x00000000

Bits	Field	Access	Description
0	EN	RW	Controller enable. 0 = all commands/mmap accesses rejected.
1	ABORT	RW	Abort the running transfer; flushes the FIFO. Self-clearing once the sequencer is idle. Mandatory flow for leaving memory-mapped mode.
15:8	PRESCALER	RW	SCK divider: SCK = clk / (2*(PRESCALER+1)).

DCR — offset 0x04

Device Configuration Register. Reset: 0x00000010

Bits	Field	Access	Description
4:0	FSIZE	RW	Device size = 2^(FSIZE+1) bytes. Reset 16 -> 128 KiB (23LC1024). W25Q128JV flash: 23 -> 16 MiB. Change only while SR.BUSY=0.
10:8	CSHT	RW	Minimum CS-high time between two commands, in SCK cycles. Change only while SR.BUSY=0.

SR — offset 0x08

Status Register (read-only). Reset: 0x00000000

Bits	Field	Access	Description
0	TEF	RO	Transfer Error Flag: indirect command with address+length beyond FSIZE (the command was not started). Clear via FCR.CTEF.
1	TCF	RO	Transfer Complete Flag: all DLR+1 data bytes transferred. Clear via FCR.CTCF; cleared automatically when the next command starts.
5	BUSY	RO	Sequencer active (incl. CS tail and CSHT). Permanently 1 in memory-mapped mode (the prefetch stream is running).
13:8	FLEVEL	RO	Data-FIFO fill level in bytes (0…32).

FCR — offset 0x0C

Flag Clear Register. Reset: 0x00000000

Bits	Field	Access	Description
0	CTEF	W1C	Writing 1 clears SR.TEF.
1	CTCF	W1C	Writing 1 clears SR.TCF.

DLR — offset 0x10

Data Length Register. Reset: 0x00000000

Bits	Field	Access	Description
31:0	DL	RWnb	Data length - 1 in bytes for indirect transfers (0 = 1 byte). Ignored in memory-mapped mode.

CCR — offset 0x14

Communication Configuration Register (frame format + functional mode). Reset: 0x00000000

Bits	Field	Access	Description
7:0	INSTRUCTION	RWnb	Opcode of the instruction phase.
9:8	IMODE	RWnb	Lanes of the instruction phase: 00 skip / 01 single / 10 dual / 11 quad.
11:10	ADMODE	RWnb	Lanes of the address phase (same encoding as IMODE).
13:12	ADSIZE	RWnb	Address bytes - 1 (2 = 24-bit address, both target chips).
15:14	ABMODE	RWnb	Lanes of the alternate-byte phase (e.g. the mode byte of 0xEB).
17:16	ABSIZE	RWnb	Alternate bytes - 1.
22:18	DCYC	RWnb	Dummy cycles in SCK clocks (0 = none). SRAM SQI read: 2 / flash 0x6B/0x0B: 8 / flash 0xEB: 4.
25:24	DMODE	RWnb	Lanes of the data phase (00 = no data phase).
27:26	FMODE	RWnb	Functional mode: 00 indirect write / 01 indirect read / 11 memory-mapped.

AR — offset 0x18

Address Register. Reset: 0x00000000

Bits	Field	Access	Description
31:0	ADDRESS	RWnb	Chip address for indirect commands. A write triggers the command if ADMODE!=00 and (FMODE=01 or DMODE=00).

ABR — offset 0x1C

Alternate Bytes Register. Reset: 0x00000000

Bits	Field	Access	Description
31:0	ALTERNATE	RWnb	Alternate bytes (MSByte sent first). Also used for the read frames in memory-mapped mode.

DR — offset 0x20

Data Register (FIFO port). Reset: —

Bits	Field	Access	Description
31:0	DATA	RW	Direct FIFO access. Transfer width = asserted byte enables (sb->1, sh->2, sw->4 bytes). A write pushes (and triggers the command when FMODE=00, DMODE!=00, BUSY=0); a read pops. Contract: push exactly DLR+1 bytes; check SR.FLEVEL before reading.

WCCR — offset 0x24

Write Communication Configuration Register (frame format for memory-mapped WRITES). Reset: 0x00000000

Identical field layout to CCR; FMODE is ignored. WCCR.DMODE=00 blocks mmap writes (bus error) – mandatory for read-only devices (flash).

Fields: see CCR.

Command triggers (indirect mode)

A command starts only with SR.BUSY = 0 and CR.EN = 1, triggered by the last required CSR write:

Write to	Condition	Typical case
CCR	ADMODE=00 ∧ (FMODE=01 ∨ DMODE=00)	instruction-only (EQIO, RSTIO, WREN) or read without address (JEDEC ID, status register)
AR	ADMODE≠00 ∧ (FMODE=01 ∨ DMODE=00)	read with address; write without data phase
DR	FMODE=00 ∧ DMODE≠00	write with data (the first DR write starts)

So the order is: configure DLR/CCR/AR first, the trigger write comes last.

Software contracts

• DR width = byte enables. sb pushes/pops 1 byte, sh 2, sw 4. Exactly DLR+1 bytes must be pushed — excess bytes stay in the FIFO and corrupt the next command (remedy: CR.ABORT flushes).

• No reconfiguration while BUSY. Writes to DLR/CCR/AR/ABR/WCCR are silently ignored while SR.BUSY=1. Poll SR.BUSY first or assert CR.ABORT.

• Leaving mmap only via ABORT. In memory-mapped mode the prefetch stream runs forever (BUSY stays 1); CR.ABORT ends it, flushes the FIFO, and only then does a CCR write (e.g. changing FMODE) take effect.

• Reads: check SR.FLEVEL before reading DR (enough bytes in the FIFO); SR.TCF signals the end of the whole transfer.

• Error picture: indirect out-of-range → SR.TEF (no start); mmap out-of-range / EN=0 / FMODE≠11 / write with WCCR.DMODE=00 → OBI err response.

• Endianness: the chip byte at address A sits on byte lane A mod 4 (little-endian, RISC-V-conformant); the first byte received is the LSB.