tranZPUter FusionX Entwicklerhandbuch

Uebersicht

1. Linux-Kernelmodule (z80drv.ko, ttymzdrv.ko) — in C geschrieben, gegen den SigmaStar Linux 4.9-rt Kernel-Baum gebaut. z80drv fuehrt die Z80-Emulations-Dispatch-Schleife auf einem isolierten CPU-Kern aus und kommuniziert mit dem CPLD ueber SPI und GPIO. ttymzdrv bietet eine TTY-Schnittstelle zur Sharp MZ Tastatur- und Zeichenanzeige-Hardware.
2. User-Space-Dienstprogramme (z80ctrl, k64fcpu, sharpbiter) — in C geschrieben, Cross-kompiliert mit arm-linux-gnueabihf-gcc. Diese Dienstprogramme starten, stoppen und konfigurieren das Kernelmodul zur Laufzeit; k64fcpu agiert als Daemon, der die K64F virtuelle CPU-Schnittstelle emuliert; sharpbiter vermittelt den Zugriff auf Tastatur und Display zwischen der Host-Maschinen-Software und der Linux-Konsole.
3. CPLD RTL (VHDL) — erstellt mit Altera Quartus II 13.0.1 SP1 Web Edition. Das CPLD sitzt direkt auf dem Z80-Bus der Host-Maschine und fungiert als Hardware-Schnittstelle zwischen den physischen Z80-Bussignalen und dem SigmaStar SOM (System-on-Module). Es erfasst jeden Buszyklus, signalisiert dem SOM und treibt den Z80-Datenbus im Auftrag des SOM fuer Lesezyklen.

Quellbaum

FusionX/
├── CPLD/
│   └── v1.0/
│       ├── MZ80A/build/          Quartus II project for Sharp MZ-80A
│       ├── MZ700/build/          Quartus II project for Sharp MZ-700
│       ├── MZ2000/build/         Quartus II project for Sharp MZ-2000
│       ├── PCW8256/build/        Quartus II project for Amstrad PCW-8256
│       ├── tzpuFusionX.vhd           Main RTL (FSMs, SPI, bus interface, video/audio)
│       ├── tzpuFusionX_Toplevel.vhd  Top-level entity and I/O pin assignments
│       └── tzpuFusionX_pkg.vhd       Shared package (types, constants, generics)
└── software/
    ├── linux/
    │   └── Build_FusionX.sh      Master build script (U-boot + kernel + rootfs + apps)
    └── FusionX/
        └── src/
            ├── z80drv/
            │   ├── src.mz80a/    Makefile and symlinks for MZ-80A build variant
            │   ├── src.mz700/    MZ-700 build variant
            │   ├── src.mz2000/   MZ-2000 build variant
            │   ├── src.pcw/      PCW-8256 build variant
            │   └── src/          Common source files:
            │       ├── z80driver.c      Main kernel module: dispatch loop, memory/IO routing
            │       ├── z80driver.h      Data structures, memory map constants per machine
            │       ├── z80io.c          HAL: SPI write path, GPIO read path, CPLD communication
            │       ├── emumz.c          Zeta Z80 instruction execution wrapper
            │       ├── z80vhw_mz80a.c   MZ-80A virtual hardware
            │       ├── z80vhw_mz700.c   MZ-700 virtual hardware
            │       ├── z80vhw_mz2000.c  MZ-2000 virtual hardware
            │       ├── z80vhw_pcw.c     PCW-8256 virtual hardware
            │       ├── z80vhw_rfs.c     ROM Filing System virtual device
            │       └── z80vhw_tzpu.c    tranZPUter SW virtual hardware (K64F stub)
            ├── ttymz/
            │   ├── Makefile
            │   └── ttymzdrv.c           MZ keyboard/display TTY driver
            └── utils/
                ├── z80ctrl.c            z80drv control utility
                ├── k64fcpu.c            K64F virtual CPU daemon
                └── sharpbiter.c         Keyboard/display arbiter daemon

Entwicklungsumgebung einrichten

Automatisierte Einrichtung und Build (empfohlen)

chmod +x setup_FusionX.sh
./setup_FusionX.sh

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

./build.sh                 # all components
./build.sh --cpld          # just the CPLD bit streams
./build.sh --help          # list all options

Voraussetzungen

sudo apt update
sudo apt install -y make bc libssl-dev git default-jre docker.io u-boot-tools

sudo usermod -aG docker $USER
# Abmelden und erneut anmelden, damit die Gruppenaenderung wirksam wird

ARM-Cross-Compiler (Linaro GCC 5.5)

# Linaro GCC 5.5-2017.10 fuer ARM Hard-Float herunterladen
wget https://releases.linaro.org/components/toolchain/binaries/5.5-2017.10/arm-linux-gnueabihf/gcc-linaro-5.5.0-2017.10-x86_64_arm-linux-gnueabihf.tar.xz

# Nach /opt extrahieren (erfordert Root-Rechte)
sudo mkdir -p /opt/arm-linux-gnueabihf
sudo tar xJf gcc-linaro-5.5.0-2017.10-x86_64_arm-linux-gnueabihf.tar.xz \
    -C /opt/arm-linux-gnueabihf --strip-components=1

# Zum PATH hinzufuegen (fuer Persistenz in ~/.bashrc hinzufuegen)
export PATH="/opt/arm-linux-gnueabihf/bin:$PATH"

# Ueberpruefen
arm-linux-gnueabihf-gcc --version
# Erwartete Ausgabe: arm-linux-gnueabihf-gcc (Linaro GCC 5.5-2017.10) 5.5.0

Quartus II Docker-Images (CPLD-Builds)

# Erstellen Sie ein Build-Verzeichnis mit dem Dockerfile und unterstuetzenden Dateien
mkdir -p quartus-docker/files
cd quartus-docker

# Erstellen Sie das Dockerfile (siehe unten) als Dockerfile.13.0.1
# Legen Sie die folgenden Dateien im files/-Unterverzeichnis ab:
#   license.dat              - Quartus license file (dummy for Web Edition)
#   quartus2.ini             - Quartus configuration
#   quartus2.qreg            - Quartus registry settings
#   quartus_web_rules_file.txt - Web edition rules
#   libjtag_hw_arrow.so      - Arrow USB Blaster library (optional, for programming)
#   70-usb.rules             - USB Blaster udev rules (optional)

# Image erstellen (laedt ~4GB an Quartus-Installationsdateien waehrend des Builds herunter)
docker build -f Dockerfile.13.0.1 \
    --build-arg user_uid=$(id -u) \
    --build-arg user_gid=$(id -g) \
    --build-arg user_name=$(whoami) \
    -t quartus-ii-13.0.1 .

Toolchain-Uebersicht

Klonen und Erstellen

# Repository klonen (enthaelt den vollstaendigen Kernel-Baum — etwa 1,5 GB)
git clone https://git.eaw.app/eaw/tzpuFusionX.git
cd tzpuFusionX

# Git-Submodule initialisieren (Z80- und 6502-CPU-Emulator-Bibliotheken)
git submodule update --init --recursive

# Alles erstellen (Z80-ROMs, TZFS, CP/M, Kernelmodule, SPI-Tools, CPLD-Bitstreams)
./build.sh --all

# Oder einzelne Komponenten erstellen:
./build.sh --asm           # Z80-Assembly-ROMs und MZF-Dateien
./build.sh --tzfs          # TZFS-ROMs fuer MZ-80A/700/2000
./build.sh --cpm           # CP/M 2.2 Binaerdateien
./build.sh --drivers       # Kernelmodule (z80drv, ttymzdrv) und User-Space-Anwendungen
./build.sh --spi           # SPI-Tools (mspi_main)
./build.sh --cpld          # CPLD-Bitstreams (erfordert Quartus Docker-Image)
./build.sh --image         # Linux SD-Karten-Image (erfordert vollstaendigen Kernel-Baum)
./build.sh --clean         # Alle Build-Artefakte entfernen

Fuer die vollstaendigen Details zu SDK-Setup, Kernelmodul-Build, Continuous Integration (Jenkins), Datenstrukturen, Dispatch-Schleife, Hinzufuegen neuer Maschinen, Hinzufuegen virtueller Hardware-Geraete, Aendern des CPLD, Cross-Kompilierung von Benutzerprogrammen, OTA-Firmware-Update und haeufigen Fallstricken — einschliesslich vollstaendiger Code-Beispiele, Jenkins-Pipeline-Skripte und Dockerfile-Inhalte — beziehen Sie sich bitte auf die englischsprachige Dokumentation, da der gesamte Code, die Befehle und die technische Konfiguration unveraendert bleiben.

Wichtige Datenstrukturen

Speicherabbildung

// z80driver.h — MZ-80A memory map example
#define MZ80A_MONITOR_ROM_ADDR    0x0000
#define MZ80A_MONITOR_ROM_SIZE    0x1000  // 4KB system monitor
#define MZ80A_VRAM_ADDR           0xD000  // Video RAM start
#define MZ80A_VRAM_SIZE           0x0800  // 2KB VRAM
#define MZ80A_IO_KEYBOARD         0xE000  // Keyboard I/O port

typedef struct {
    uint32_t  baseAddr;       // Z80 address space start
    uint32_t  size;           // Region size in bytes
    uint8_t  *data;           // Pointer to emulated memory buffer
    uint8_t   type;           // MEM_ROM, MEM_RAM, MEM_VHARDWARE, MEM_PHYSICAL
    void     (*read_fn)(uint16_t addr, uint8_t *data);   // Virtual hardware read handler
    void     (*write_fn)(uint16_t addr, uint8_t data);   // Virtual hardware write handler
} t_memRegion;

Buszyklus-Anforderung

// Bus cycle information captured from CPLD GPIO pins
typedef struct {
    uint16_t  address;        // Z80 address bus A0-A15
    uint8_t   data;           // Z80 data bus D0-D7
    uint8_t   busType;        // BUS_MREQ_RD, BUS_MREQ_WR, BUS_IORQ_RD, BUS_IORQ_WR, BUS_M1
    bool      isRead;         // true = read cycle, false = write cycle
} t_busCycle;

Virtual Hardware Module-Schnittstelle

// Each z80vhw_*.c implements these functions:

// Called once at module load — register memory/IO regions and handlers
int vhw_init(void);

// Memory read handler — called by dispatch loop for memory-mapped regions
uint8_t vhw_mem_read(uint16_t addr);

// Memory write handler
void vhw_mem_write(uint16_t addr, uint8_t data);

// I/O read handler (not used for 6502-based machines, always present for Z80)
uint8_t vhw_io_read(uint16_t port);

// I/O write handler
void vhw_io_write(uint16_t port, uint8_t data);

// Called on Z80 RESET — reinitialise hardware state
void vhw_reset(void);

// Called periodically from dispatch loop — for timers, sound emulation, etc.
void vhw_tick(uint64_t cycles);

z80driver.c — Dispatch-Schleife

// Simplified dispatch loop (z80driver.c)
static int z80_emulation_thread(void *data)
{
    while (!kthread_should_stop()) {
        // 1. Wait for CPLD to signal pending bus cycle (GPIO IRQ or poll)
        t_busCycle cycle = cpld_read_bus_cycle();    // reads GPIO pins

        // 2. Dispatch based on cycle type and address
        if (cycle.busType == BUS_M1) {
            // Opcode fetch — run one Z80 instruction via Zeta library
            zeta_run_one_instruction(&z80_state);

        } else if (cycle.busType == BUS_MREQ_RD) {
            // Memory read
            uint8_t data = dispatch_mem_read(cycle.address);
            cpld_write_data(data);                   // SPI write to CPLD

        } else if (cycle.busType == BUS_MREQ_WR) {
            // Memory write
            dispatch_mem_write(cycle.address, cycle.data);

        } else if (cycle.busType == BUS_IORQ_RD) {
            // I/O read
            uint8_t data = dispatch_io_read(cycle.address & 0xFF);
            cpld_write_data(data);

        } else if (cycle.busType == BUS_IORQ_WR) {
            // I/O write
            dispatch_io_write(cycle.address & 0xFF, cycle.data);
        }

        // 3. Periodic housekeeping
        if ((cycle_count++ & 0x7FF) == 0)
            vhw_tick(cycle_count);
    }
    return 0;
}

Eine neue Maschine hinzufuegen

Referenz-Websites

Hinweis zur Funkregulierung