tranZPUter SW-700 — Entwicklerhandbuch

Dieses Handbuch ist eine detaillierte Anleitung zum Quellcode und zur Entwicklungsumgebung des tranZPUter SW-700. Es fuehrt in VHDL fuer Entwickler ein, die mit der Sprache nicht vertraut sind, geht jedes wichtige Quellmodul durch, dokumentiert die CPLD- und FPGA-Designs, erklaert die Speicherabbildung und CPU-Umschaltungsarchitektur und zeigt, wie man die Firmware baut, Unterstuetzung fuer neue Sharp MZ-Maschinen hinzufuegt und Hardwareprobleme debuggt. Fuer die Hardware-Architektur und Schaltplaene siehe die tranZPUter SW-700 Seite. Fuer benutzerseitige Bedienung und TZFS-Befehle siehe das TZFS Benutzerhandbuch.

Die gesamte digitale Logik des tranZPUter SW-700 — die CPLD-Verbindungslogik und die FPGA-Video- und Soft-CPU-Kerne — ist in VHDL (VHSIC Hardware Description Language) geschrieben. Anders als Software beschreibt VHDL keine Abfolge von Schritten, die ein Prozessor nacheinander ausfuehrt. Es beschreibt Hardware: Sammlungen von Logikgattern, Flipflops und Zustandsmaschinen, die alle gleichzeitig arbeiten. Jeder process in einer VHDL-Datei laeuft parallel zu jedem anderen Prozess; Signale aendern ihren Wert alle gleichzeitig an jeder Taktflanke.

Jedes VHDL-Modul besteht aus zwei Teilen:

• ENTITY deklariert die Schnittstelle des Moduls — seine Ein- und Ausgangspins. Man kann es sich als Funktionssignatur in einer Softwaresprache vorstellen.
• ARCHITECTURE enthaelt die Implementierung — die internen Signale, Komponenteninstanziierungen und Prozesse, die beschreiben, wie Ausgaenge aus Eingaengen berechnet werden.

entity coreMZ is
    port (
        CLOCK_50   : in  std_logic;                      -- 50 MHz base clock
        VZ80_ADDR  : inout std_logic_vector(15 downto 0); -- Z80 address bus
        VGA_R      : out std_logic_vector(3 downto 0)    -- VGA red channel
        -- ... further ports ...
    );
end entity;

architecture rtl of coreMZ is
    signal PLL_LOCKED : std_logic := '0';  -- internal signal
begin
    -- concurrent statements and processes go here
end architecture;

Signale sind die internen Leitungen eines VHDL-Moduls — sie verbinden Prozesse miteinander und mit den Ports. Die gaengigsten Typen in diesem Design sind:

• std_logic — ein einzelnes Bit, das '0', '1', 'Z' (Hochohmig / Tristate) oder verschiedene andere Simulationswerte sein kann.
• std_logic_vector(N downto 0) — ein Bus aus N+1 Bits.
• unsigned / integer — numerische Typen fuer Zaehler und Arithmetik.

Ein process ist ein Block sequenzieller VHDL-Anweisungen, der bei jeder Aenderung eines Signals in seiner Empfindlichkeitsliste erneut ausgefuehrt wird. Prozesse sind der fundamentale Baustein synchroner Logik.

process(SYS_CLK, RESETn)
begin
    if RESETn = '0' then
        MY_REGISTER <= (others => '0');
    elsif rising_edge(SYS_CLK) then
        MY_REGISTER <= NEXT_VALUE;
    end if;
end process;

Der gesamte Quellcode ist unter dem tranZPUter-Repository organisiert. Die wichtigsten Pfade und Dateien sind in der folgenden Tabelle aufgefuehrt.

Bevor Sie die manuellen Quartus- und Docker-Schritte durcharbeiten, die folgen, beachten Sie, dass die gesamte Umgebung fuer Sie eingerichtet werden kann. Das mitgelieferte Setup-Skript fuer Ihre Plattform installiert die Basis-Werkzeuge, installiert Java (JRE) fuer den GLASS-Z80-Assembler und Docker, baut die drei Quartus-Docker-Images, die im Abschnitt Docker-Build-Umgebung beschrieben sind, klont das Repository mit --recurse-submodules (TZFS, zSoft/zOS, zpu) und bietet an, den ersten Build auszufuehren (./build.sh -t all). Quartus wird nicht auf dem Host installiert — die CPLD- und FPGA-Builds laufen innerhalb der Docker-Images. Jedes Skript ist eigenstaendig.

chmod +x setup_tranZPUter.sh
./setup_tranZPUter.sh

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

Die drei gebauten Images sind tzpu-quartus:13.0.1 (MAX7000-CPLDs), tzpu-quartus:13.1 (Cyclone III, SW-700 v1.2) und tzpu-quartus:17.1 (Cyclone IV, SW-700 v1.3 / Fusion) — alle kostenlose Web/Lite Edition, keine Lizenz. Der Build wird von build.sh gesteuert, das Quartus nativ ausfuehrt, wenn eine passende Version gefunden wird, andernfalls innerhalb dieser Images (Java/GLASS laeuft immer nativ). Die Ausgaben (.pof, .sof, .jic-Boot-Flash, ROM/TZFS/CP/M-Images) werden unter ./build/output/ gesammelt.

./build.sh -t all        # CPLD + FPGA + software (default: -V v1.3 -M all -D E115 -C emuMZ)
./build.sh -t fpga -V v1.2   # just the v1.2 (Cyclone III) FPGA bitstream
./build.sh -h            # list all targets and options

Die manuellen FPGA-, CPLD- und Docker-Build-Schritte unten werden fuer fortgeschrittene Benutzer und Teil-Rebuilds weiterhin vollstaendig unterstuetzt.