ZPU Evo Entwicklerhandbuch

Einfuehrung

Willkommen beim ZPU Evolution Entwicklerhandbuch. Dieses Handbuch richtet sich an Studenten, Hobbyisten und Ingenieure, die den ZPU Evolution Prozessor verstehen, bauen, modifizieren und erweitern moechten. Ob Sie einen Mikroprozessorkurs belegen, FPGA-Entwicklung lernen oder Soft-Core-CPU-Design erkunden – dieses Handbuch fuehrt Sie durch alles, von grundlegenden Konzepten bis hin zu fortgeschrittener Anpassung.

Die ZPU ist ein 32-Bit-Stack-basierter Mikroprozessor, der urspruenglich von Øyvind Harboe von Zylin AS entworfen wurde. Die ZPU Evolution (Evo) ist eine erweiterte Version, die von Philip Smart erstellt wurde und erhebliche Leistungsverbesserungen, Caching, erweiterte Befehle und ein umfangreiches System-on-Chip (SoC) Framework hinzufuegt. Das gesamte Design ist Open Source und in VHDL fuer die Synthese auf Intel/Altera FPGAs implementiert.

Was Sie lernen werden

Durch die Arbeit mit diesem Handbuch werden Sie:

Die Stack-basierte CPU-Architektur verstehen und wie sie sich von registerbasierten Designs unterscheidet
Lernen, wie der ZPU-Befehlssatz auf Hardware-Ebene funktioniert
In der Lage sein, FPGA-Bitstreams fuer mehrere Entwicklungsboards zu konfigurieren, zu erstellen und zu programmieren
Wissen, wie man dem CPU neue Hardware-Befehle hinzufuegt
Die SoC-Architektur verstehen, einschliesslich Speichercontroller, UARTs, Timer und Interrupt-Behandlung
In der Lage sein, C-Programme zu schreiben, zu kompilieren und auf der ZPU auszufuehren
Automatisierte CI/CD-Builds mit Jenkins und Docker einrichten

Voraussetzungen

Um das Beste aus diesem Handbuch herauszuholen, sollten Sie Folgendes mitbringen:

Grundlegende Digitallogik-Kenntnisse - Verstaendnis von Flip-Flops, Multiplexern, Zustandsmaschinen und Busstrukturen
Etwas VHDL-Erfahrung - Faehigkeit, VHDL-Entity-Deklarationen, Signalzuweisungen und Prozessbloecke zu lesen
C-Programmierung - Vertrautheit mit C-Syntax, Pointern und Kompilierung
Ein FPGA-Entwicklungsboard - Eines der unterstuetzten Boards (DE10 Nano, E115, CYC1000, QMV oder DE0 Nano)
Intel Quartus Prime - Version 17.1.1 Standard Edition (oder die containerisierte Docker-Version)

Teil 1: Die ZPU-Architektur verstehen

Stack-basierte vs. registerbasierte Prozessoren

Die meisten Prozessoren, denen Sie begegnen (ARM, x86, RISC-V), sind registerbasiert: Sie haben einen festen Satz benannter Register (R0-R15, EAX usw.) und Befehle geben an, mit welchen Registern operiert werden soll. Zum Beispiel bedeutet ADD R0, R1, R2 “addiere R1 und R2, speichere in R0”.

Die ZPU ist ein Stack-basierter Prozessor. Anstelle benannter Register verwendet sie einen Last-In-First-Out (LIFO) Stack. Operationen arbeiten implizit mit den obersten Elementen des Stacks:

Stack vor ADD:          Stack nach ADD:
  ┌─────┐                ┌─────┐
  │  3  │ ← TOS          │  7  │ ← TOS (3+4)
  ├─────┤                ├─────┤
  │  4  │ ← NOS          │ ... │
  ├─────┤                └─────┘
  │ ... │
  └─────┘

TOS = Top of Stack, NOS = Next on Stack.

Warum eine Stack-Architektur?

Minimale Befehlskodierung - Keine Registerfelder erforderlich. ADD ist nur ein Byte (Opcode 00000101), waehrend ein registerbasiertes ADD Quell- und Zielregisterfelder benoetigt (2-4 Bytes).
Sehr kleiner FPGA-Footprint - Der Decoder ist trivial und benoetigt minimale Logikelemente.
Einfaches Compiler-Ziel - Ausdrucksauswertung laesst sich natuerlich auf Stack-Operationen abbilden (Umgekehrte Polnische Notation).
Kompromiss - Stack-Maschinen sind typischerweise langsamer pro Operation als Registermaschinen wegen der zusaetzlichen Stack-Manipulation, aber das Caching-System der ZPU Evo mildert dies erheblich.

Das ZPU-Speichermodell

Die ZPU hat einen flachen, byteadressierbaren, 32-Bit-Speicherraum. Alle Speicher- und IO-Geraete teilen sich diesen Raum:

Address Space (24-bit example, configurable):
┌──────────────────────────────────────────────┐
│ 0x000000 - 0x01FFFF : Boot BRAM (128KB)      │  ← Program + Stack
│                        Reset vector at 0x0000 │
│                        Emulation vectors      │
│                        0x0000-0x0400          │
├──────────────────────────────────────────────┤
│ 0x020000 - 0x03FFFF : Application RAM (opt)   │  ← Secondary BRAM
├──────────────────────────────────────────────┤
│ 0x040000 - 0xFEFFFF : SDRAM (optional)        │  ← External memory
├──────────────────────────────────────────────┤
│ 0xFF0000 - 0xFFFFFF : Memory-Mapped I/O       │  ← Peripherals
├──────────────────────────────────────────────┤
│ 0x1000000 - 0x1FFFFFF: Wishbone bus (optional) │  ← Extended region
└──────────────────────────────────────────────┘

Wichtige Punkte:

Der Stack befindet sich am oberen Ende des BRAM und waechst nach unten
Das Programm beginnt an Adresse 0x0000 (konfigurierbar)
Adressen 0x0000-0x0400 sind fuer Emulationsvektoren reserviert (spaeter erklaert)
IO-Geraete sind am oberen Ende des Adressraums Memory-Mapped
Der Wishbone-Bus verdoppelt, wenn aktiviert, den Adressraum

Die fuenf CPU-Modelle

Das ZPU Evolution SoC unterstuetzt fuenf austauschbare CPU-Modelle, die zur Build-Zeit auswaehlbar sind. Nur eines kann aktiv sein:

Model	Logic Elements	Performance	Wishbone	Best For
Small	~400 LEs	Baseline	No	Minimum footprint applications
Medium	~600 LEs	~1.5x Small	No	Better performance, still small
Flex	~800 LEs	~1.8x Small	No	Good balance of size and speed
Evo	~2500 LEs	~3x Small	Yes	Maximum performance, full features
Evo Minimal	~1200 LEs	~2x Small	Yes	Evo with reduced instruction set

Das Evo-Modell fuegt hinzu:

L1-Befehls-Cache (registerbasiert, konfigurierbar 8-256 Eintraege)
L2-Befehls-Cache (BRAM-basiert, konfigurierbar 256-4096 Bytes)
Memory Transaction Processor (Warteschlange fuer Speicheroperationen)
Dualer Speicherbus (Systembus + optionaler Wishbone-Bus)
Optionaler Befehlsbus (separater BRAM-Port fuer Befehlsabruf)
Hardware Byte/Word Write (Vermeidung von Read-Modify-Write-Zyklen)
Unterstuetzung erweiterter Befehle (Mehrbyte-Befehle)

Befehlskodierung

ZPU-Befehle sind 8 Bit breit. Die Kodierung ist bemerkenswert einfach:

Bit 7 = 1: IM instruction (7-bit immediate value in bits 6:0)
Bit 7 = 0:
  Bits 6:5 = 00: Core instructions (opcode in bits 4:0)
  Bits 6:5 = 01: STORESP (store to stack offset in bits 4:0)
  Bits 6:5 = 10: EMULATE (emulation vector index in bits 4:0)
  Bits 6:5 = 11: LOADSP (load from stack offset in bits 4:0)

Laden einer 32-Bit-Konstante: Da jeder IM-Befehl nur 7 Bits tragen kann, erfordert das Laden eines vollstaendigen 32-Bit-Werts bis zu 5 aufeinanderfolgende IM-Befehle. Der L1-Cache in der Evo ermoeglicht es, bis zu 5 IM-Befehle in einem einzigen Zyklus auszufuehren, was das Laden von Konstanten sehr effizient macht.

Emulationsvektoren

Ein Schluesselfeature der ZPU ist die Befehlsemulation. Als EMULATE markierte Befehle (Opcode-Bits 6:5 = 10) verzweigen zu einem Vektor im Bereich 0x0000-0x0400. Jeder Vektor ist 32 Bytes gross:

Vector address = instruction[4:0] * 32

Wenn ein Hardware-Befehl nicht implementiert ist (in der Konfiguration deaktiviert), loest er den EMULATE-Pfad aus, in dem Software-Mikrocode die Operation implementiert. Dadurch kann die CPU dieselbe Software unabhaengig davon ausfuehren, welche Befehle in Hardware vorliegen – nur mit unterschiedlichen Geschwindigkeiten.

Dies ist es, was die ZPU einzigartig flexibel macht: Sie koennen FPGA-Ressourcen gegen Leistung tauschen, indem Sie selektiv Hardware-Befehle aktivieren/deaktivieren.

Teil 2: Projektstruktur

Verzeichnislayout

ZPU/
├── cpu/                          # CPU core implementations
│   ├── zpu_core_evo.vhd          # ZPU Evolution CPU (3688 lines)
│   ├── zpu_core_small.vhd        # ZPU Small CPU
│   ├── zpu_core_medium.vhd       # ZPU Medium CPU
│   ├── zpu_core_flex.vhd         # ZPU Flex CPU
│   ├── zpu_pkg.vhd               # CPU package (opcodes, config)
│   └── zpu_uart_debug.vhd        # Debug serialiser
│
├── devices/                      # Peripheral IP cores
│   ├── sysbus/                   # System bus peripherals
│   └── WishBone/                 # Wishbone bus peripherals
│
├── build/                        # FPGA board build files
│   ├── Makefile                  # Build targets for all boards/CPUs
│   └── *_zpu.qpf/qsf            # Board-specific Quartus projects
│
├── zpu_soc.vhd                   # SoC top level (2346 lines)
├── zpu_soc_pkg.vhd               # SoC configuration package
├── zpu_soc_pkg.tmpl.vhd          # Template for build system
└── README.md                     # Project documentation

Wichtige Quelldateien erklaert

zpu_pkg.vhd - Das CPU-Level-Konfigurationspaket. Enthaelt Opcode-Definitionen, Adressbusbreiten-Konfiguration, Komponentendeklarationen fuer die CPU-Kerne, Debug-Konfiguration und Befehlsbus-Aktivierungsflags.

zpu_soc_pkg.vhd - Die SoC-Level-Konfiguration. Enthaelt CPU-Modellauswahl, Board-Taktfrequenzen, Speichergeometrie, Peripherie-Aktivierungs/Deaktivierungsflags, Cache-Groessenparameter und Memory-Map-Konstanten.

zpu_soc.vhd - Das Haupt-SoC-Modul. Hier kommt alles zusammen: Instanziierung des ausgewaehlten CPU-Kerns, Verbindung von BRAM, SDRAM, UART, Timern, SD-Karte usw.

cpu/zpu_core_evo.vhd - Die Evo-CPU-Implementierung (3688 Zeilen). Enthaelt Befehlsdecoder und Ausfuehrungszustandsmaschine, L1-Cache, L2-Cache, Memory Transaction Processor und Stack-Verwaltung.

Teil 3: SoC konfigurieren

Die vollstaendigen Konfigurationsdetails – CPU-Modellauswahl, Speicherkonfiguration, Peripherie-Aktivierung und Evo-Cache-Tuning – sind identisch mit der englischen Version und werden dort ausfuehrlich erklaert.

Teil 4: FPGA-Bitstreams erstellen

Wenn Sie schnell einen funktionierenden Bitstream wollen, verwenden Sie das automatisierte Setup-Skript fuer Ihre Plattform (siehe Automatisiertes Setup und Build direkt unten). Es installiert die gesamte Toolchain (Intel Quartus Prime Lite 17.1 und, wo erforderlich, Docker), klont das Repository, laesst Sie Board und CPU waehlen und baut bis zur Fertigstellung. Die nachfolgenden Makefile-, Direkt-Quartus- und Docker-Workflows sind fuer alle, die die Tools von Hand steuern wollen.

Automatisiertes Setup und Build (empfohlen)

Die mitgelieferten Setup-Skripte installieren alles Noetige (Intel Quartus Prime Lite 17.1 und, wo erforderlich, Docker), klonen das Repository, lassen Sie Zielboard und CPU-Variante waehlen und bauen den FPGA-Bitstream bis zur Fertigstellung. Jedes Skript ist eigenstaendig — kopieren Sie nur die einzelne Datei fuer Ihre Plattform und fuehren Sie sie aus. Getestet unter Windows (nativ), macOS (Intel, via Docker) und Linux.

Script	Platform	Notes
`setup_ZPU_windows.cmd`	Windows 10 / 11	Empfohlen unter Windows — Doppelklick-Starter; haelt das Fenster offen und protokolliert nach `setup_ZPU_log.txt`. Native Installation, kein WSL.
`setup_ZPU_windows_native.ps1`	Windows 10 / 11	Das zugrunde liegende PowerShell-Skript (installiert Git for Windows + Quartus 17.1 via winget / Intel-Installer).
`setup_ZPU.sh`	Linux / macOS	Natives Quartus unter Linux; ein Headless-Quartus-Docker-Image unter macOS (nur Intel-Macs).
`build_zpu.sh`	all	Portabler Build-Wrapper. Jederzeit zum Neubauen ausfuehrbar: `./build_zpu.sh [BOARD] [CPU]`.

Windows — setup_ZPU_windows.cmd doppelklicken, oder aus PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_ZPU_windows_native.ps1

macOS / Linux:

chmod +x setup_ZPU.sh
./setup_ZPU.sh

Jedes Skript fragt nach Board und CPU-Variante (Standard QMV / EVO) sowie, sofern nicht aus einem Checkout gestartet, nach dem Klonziel. Nach Abschluss erhalten Sie build/<BOARD>_<CPU>.sof (den FPGA-Bitstream) und ein komprimiertes build/<BOARD>_<CPU>.rbf. Boards: QMV (Standard), DE10_nano, DE0_nano, E115, CYC1000; CPUs: EVO (Standard), EVO_MINIMAL, FLEX, MEDIUM, SMALL.

Zum spaeteren Neubauen ohne erneutes Setup (unter Windows Git Bash zuerst export PATH="/c/altera/17.1/quartus/bin64":$PATH):

./build_zpu.sh E115 EVO           # board + CPU
./build_zpu.sh --list             # list all boards / CPUs
ZPU_RTL_METHOD=docker ./build_zpu.sh QMV EVO   # force the headless Docker image

Nuetzliche Umgebungsvariablen: ZPU_REPO_URL (zu klonendes Repository; Standard https://git.eaw.app/eaw/zpu.git), ZPU_BOARD / ZPU_CPU (ueberspringen die Abfragen), ZPU_RTL_METHOD=native|docker, ZPU_DIR (Build in einem bestehenden Checkout) und ZPU_QUARTUS_BIN (Verweis auf ein vorhandenes Quartus bin/bin64).

Verwendung des Makefiles

Der einfachste Weg zum Build ist das Makefile im build/-Verzeichnis:

cd ZPU/build
make DE10_nano_EVO        # DE10-Nano mit Evo CPU
make E115_SMALL           # E115 mit Small CPU
make CYC1000_MEDIUM       # CYC1000 mit Medium CPU

Was waehrend eines Builds passiert:

Das Makefile kopiert zpu_soc_pkg.tmpl.vhd und setzt per sed das gewaehlte CPU-Modell auf 1
Die generierte zpu_soc_pkg.vhd ersetzt die bestehende
Quartus fuehrt die Synthese durch – konvertiert VHDL in eine Netzliste
Quartus fuehrt den Fitter (Place & Route) aus – bildet auf tatsaechliche FPGA-Ressourcen ab
Quartus fuehrt den Assembler aus – generiert die .sof-Programmierdatei
quartus_cpf konvertiert die .sof in .rbf (Raw Binary Format)

Teil 5-6: Befehlssatz und Hinzufuegen neuer Befehle

Die vollstaendigen Befehlssatztabellen (Kern-Befehle, emulierbare Befehle, erweiterte Befehle) und die schrittweise Anleitung zum Hinzufuegen neuer Hardware-Befehle finden Sie in der englischen Version.

Teil 7: Das Software-Oekosystem -- IOCP, zOS und Anwendungen

Ueberblick ueber die Software-Schichten

Der Standard-Software-Stack auf einem ZPU-Evolution-System ist:

┌───────────────────────────────────────────────────┐
│              Anwendungen                           │
│  (ed, kilo, tbasic, mbasic, Benchmarks,           │
│   eigene Programme -- von SD-Karte geladen)        │
├───────────────────────────────────────────────────┤
│         zOS -- Betriebssystem                      │
│  (Shell, Dateisystem, 80+ Befehle, App-Laden,      │
│   Speicherverwaltung, Interrupt-Behandlung)         │
├───────────────────────────────────────────────────┤
│         IOCP -- Bootloader                         │
│  (Hardware-Init, SD-Karten-Boot, serieller Upload,  │
│   Speichermonitor -- eingebettet in BRAM)           │
├───────────────────────────────────────────────────┤
│         ZPU Hardware (FPGA)                        │
│  (CPU, BRAM, SDRAM, UART, SD, Timer, Interrupts)   │
└───────────────────────────────────────────────────┘

Die Boot-Sequenz ist: FPGA wird eingeschaltet -> IOCP laeuft aus BRAM -> IOCP laedt zOS von SD-Karte -> zOS praesentiert eine Shell -> Benutzer fuehrt Anwendungen aus.

IOCP -- Der Bootloader

IOCP (I/O Control Program) ist der erste Code, der ausgefuehrt wird, wenn die ZPU eingeschaltet wird. Er ist direkt im Block-RAM des FPGAs waehrend der Synthese eingebettet, sodass er immer verfuegbar ist – keine SD-Karte oder externer Speicher wird fuer seine Ausfuehrung benoetigt.

IOCP-Funktionsstufen reichen von Full (~40 KB mit allen Befehlen) bis Tiny (~3-5 KB, nur Bootstrap). Details zu den seriellen Upload-Protokollen, Befehlen und dem Speicherlayout finden Sie in der englischen Version.

zOS -- Das Betriebssystem

zOS (ZPU Operating System) ist das Standardbetriebssystem fuer die ZPU Evolution. Es bietet eine Kommandozeilen-Shell, volle Dateisystem-Unterstuetzung, Speicherverwaltung und die Moeglichkeit, Anwendungen von der SD-Karte zu laden und auszufuehren – vergleichbar damit, wie CP/M oder fruehes DOS eine Kommandozeilenumgebung zum Ausfuehren von Programmen bereitstellten.

zOS-Shell-Funktionen umfassen: 80+ Befehle, Readline-artige Zeilenbearbeitung mit History, AUTOEXEC.BAT-Unterstuetzung und ein Hilfesystem.

Anwendungen

Mitgelieferte Anwendungen: ed (VT100-Texteditor), kilo (erweiterter VT100-Editor), tbasic (Tiny BASIC Interpreter), mbasic (Mini BASIC v1.0), dhry (Dhrystone v2.1 Benchmark), coremark (CoreMark v1.0 Benchmark).

Software erstellen

Alle ZPU-Software (IOCP, zOS und Anwendungen) wird aus dem zOS-Repository mit einem einheitlichen build.sh-Skript erstellt. Die vollstaendigen Build-Parameter und Beispielbefehle finden Sie in der englischen Version.

Teil 8-13: Fortgeschrittene Themen

Die vollstaendigen Abschnitte zu Custom Software, SoC-Architektur, Board-spezifischer Einrichtung, CI/CD, Debugging und weiterfuehrenden Ressourcen finden Sie in der englischen Version dieses Dokuments.

Uebungen fuer Studenten

Grundlegend: Erstellen Sie die ZPU Small fuer Ihr Board. Verbinden Sie ein Terminal bei 115200 Baud und interagieren Sie mit IOCP.
Mittel: Aendern Sie zpu_soc_pkg.vhd, um die BRAM-Groesse zu aendern. Beobachten Sie die Auswirkung auf den verfuegbaren Stack-Speicher.
Mittel: Aktivieren Sie den PS2-Controller und schliessen Sie eine Tastatur an. Schreiben Sie ein C-Programm, das Tastendruecke zurueckgibt.
Fortgeschritten: Fuegen Sie einen Hardware-SWAP-Befehl hinzu (wie in Teil 6 beschrieben). Ueberpruefen Sie ihn mit Inline-Assembly.
Fortgeschritten: Portieren Sie das Design auf ein neues, derzeit nicht unterstuetztes FPGA-Board.
Experte: Implementieren Sie einen neuen erweiterten Befehl unter Verwendung des EXTEND-Mechanismus.