QSPI-Interface

Quad-SPI controller with OBI bus attachment — developed for the hatch SoC (RISC-V) at Hochschule München, reusable as a standalone IP with two OBI subordinate ports. The controller maps external serial memories into the address space as execution and data memory (XIP) and additionally offers a register-driven indirect mode for arbitrary chip commands (init, status, JEDEC ID, …).

Supported/validated target devices:

Chip	Type	Access	Profile
Microchip 23LC1024	1 Mbit SRAM	read and write	SPI/SQI, 0/2 dummy clocks
Winbond W25Q128JV	128 Mbit NOR flash	read	0x03/0x0B/0x6B/0xEB, QE bit, 4–8 dummy clocks

Status: Beta

Fully simulation-verified (6 self-checking testbenches + SoC system simulation) and FPGA-validated on Arty A7-100T boards, both the open-source flow (two-board run inside the complete hatch SoC) and, since 2026-07-16, a Vivado flow with real bidirectional QSPI pins (FPGA Test Setups (Arty A7) setup 3) — same two-board result, fewer wires. Not yet silicon-proven. Details: Verification Plan and Changelog & Versioning.

Contents

• Getting Started
  • Prerequisites
  • Build and run all tests
  • A single testbench + waveform
  • Simulating inside the hatch SoC
  • On real hardware (Arty A7)
  • Building the docs locally
• Architecture Overview
  • Block diagram
  • Datapath
  • Clock and reset
  • Embedding in an SoC (hatch example)
• Interface Specification
  • Port list (qspi_top)
  • OBI protocol (subset used)
  • SPI timing (mode 0)
  • Configuration limits
• Register Map
  • CR — offset 0x00
  • DCR — offset 0x04
  • SR — offset 0x08
  • FCR — offset 0x0C
  • DLR — offset 0x10
  • CCR — offset 0x14
  • AR — offset 0x18
  • ABR — offset 0x1C
  • DR — offset 0x20
  • WCCR — offset 0x24
  • Command triggers (indirect mode)
  • Software contracts
• Programmer’s & Integrator’s Guide
  • Software view
  • SoC integration view
• Design Rationale & Microarchitecture
  • Why a register-driven controller with programmable frames?
  • The job as central abstraction
  • Phase FSM (qspi_cmd_seq)
  • Shift unit: registered I/O and the first-bit trap
  • One FIFO instead of four
  • mmap frontend: stream semantics
  • Deliberate feature-set boundaries
• FPGA Test Setups (Arty A7)
  • Files involved
  • Toolchain
  • Setup 1: single-board loopback
  • Setup 2: two boards (test master ↔ SRAM slave)
  • Setup 3: two boards, Vivado (real bidirectional pins)
  • Outlook: flash model on Board A
• Verification Plan
  • Strategy
  • Testbench inventory
  • Coverage goals
  • Hardware validation
  • Known limitations
• Known Issues & Bring-up Findings
  • Simulation / testbench
  • Synthesis / place & route (openXC7 flow)
  • Board / host
• Changelog & Versioning
  • Unreleased
  • 1.0.0-beta.3 — 2026-07-08
  • 1.0.0-beta.2 — 2026-07-07
  • 1.0.0-beta.1 — 2026-07-06
  • 0.2.0 — 2026-06-23
  • 0.1.0 — starting point

Quick links

• Build and simulate in 5 minutes → Getting Started

• Register map (generated from docs/regs.yaml) → Register Map

• Software recipes + SoC integration → Programmer’s & Integrator’s Guide

• Why things are the way they are → Design Rationale & Microarchitecture

• SoC-level integration, simulation and FPGA flow of the hatch chip → hatch repository, docs/ (published as GitLab Pages of the hatch project)