tranZPUter SW-700 — Guida per Sviluppatori

Guida per Sviluppatori del tranZPUter SW-700

Questa guida e una presentazione dettagliata del codice sorgente e dell'ambiente di sviluppo del tranZPUter SW-700. Introduce il VHDL per gli sviluppatori non familiari con il linguaggio, analizza ogni modulo sorgente principale, documenta i progetti CPLD e FPGA, spiega l'architettura di mappatura della memoria e commutazione CPU, e mostra come compilare il firmware, aggiungere supporto per nuove macchine Sharp MZ e risolvere problemi hardware.

Per l'architettura hardware, vedere la pagina tranZPUter SW-700. Per i comandi TZFS, vedere il Manuale Utente TZFS.

Introduzione al VHDL per Programmatori Non-HDL

Tutta la logica digitale del tranZPUter SW-700 e scritta in VHDL. A differenza del software, il VHDL descrive hardware che si esegue in parallelo — ogni blocco process funziona simultaneamente e continuamente.

ENTITY e ARCHITECTURE

Ogni modulo VHDL ha due parti:

ENTITY dichiara l'interfaccia del modulo — i suoi pin di ingresso e uscita.

ARCHITECTURE contiene l'implementazione — segnali interni, istanziazioni di componenti e processi.

entity coreMZ is
    port (
        CLOCK_50   : in  std_logic;
        VZ80_ADDR  : inout std_logic_vector(15 downto 0);
        VGA_R      : out std_logic_vector(3 downto 0)
    );
end entity;

SEGNALI

I segnali sono i fili interni di un modulo VHDL. I tipi piu comuni sono std_logic, std_logic_vector, unsigned e integer.

PROCESS

Un process e un blocco di istruzioni VHDL sequenziali che si riesegue ogni volta che un segnale nella sua lista di sensibilita cambia.

Albero dei Sorgenti

Tutto il codice sorgente e organizzato sotto il repository tranZPUter.

Setup automatizzato e build (raccomandato)

L'intero ambiente puo essere configurato automaticamente per voi. Lo script di setup incluso per la propria piattaforma installa gli strumenti di base, installa Java (JRE) per l'assemblatore GLASS Z80 e Docker, costruisce le tre immagini Docker Quartus, clona il repository --recurse-submodules (TZFS, zSoft/zOS, zpu) e propone di eseguire il primo build (./build.sh -t all). Quartus non viene installato sull'host — i build di CPLD e FPGA vengono eseguiti all'interno delle immagini Docker. Ogni script e autonomo.

Script	Platform	Notes
`setup_tranZPUter.sh`	Linux / macOS	Installs base tools + Java (JRE) + Docker, builds the three Quartus images, clones into `~/tranZPUter`, offers `./build.sh -t all`.
`setup_tranZPUter_windows.cmd`	Windows 10 / 11	Double-click launcher — runs the `.ps1` non-interactively and logs to `setup_tranZPUter_log.txt`.
`setup_tranZPUter_windows_native.ps1`	Windows 10 / 11	winget installs Git for Windows + Docker Desktop, builds the Quartus images, clones into `%HOME%\tranZPUter`, runs `./build.sh -t all` via Git Bash.

Linux / macOS:

chmod +x setup_tranZPUter.sh
./setup_tranZPUter.sh

Windows — doppio clic su setup_tranZPUter_windows.cmd, oppure da PowerShell:

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

Le tre immagini costruite sono tzpu-quartus:13.0.1 (CPLD MAX7000), tzpu-quartus:13.1 (Cyclone III, SW-700 v1.2) e tzpu-quartus:17.1 (Cyclone IV, SW-700 v1.3 / Fusion) — tutte gratuite Web/Lite Edition, senza licenza. Il build e guidato da build.sh, che esegue Quartus nativamente se viene trovata una versione corrispondente, altrimenti all'interno di queste immagini (Java/GLASS viene sempre eseguito nativamente). Gli output (.pof, .sof, boot flash .jic, immagini ROM/TZFS/CP/M) vengono raccolti sotto ./build/output/.

./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

Override utili dell’ambiente:

Variable (alias)	Purpose
`TZPU_REPO_URL` (`tranZPUter_REPO_URL`)	Repository URL to clone. Default `https://git.eaw.app/eaw/tranZPUter.git`.
`TZPU_DIR` (`tranZPUter_DIR`)	Build in an existing checkout instead of cloning.
`TZPU_ASSUME_YES` (`tranZPUter_ASSUME_YES`)`=1`	Non-interactive; accept all defaults.
`TZPU_QUARTUS_CPLD_IMAGE` (`tranZPUter_CPLD_IMAGE`)	Override the CPLD image (default `tzpu-quartus:13.0.1`).
`TZPU_QUARTUS_C3_IMAGE` (`tranZPUter_FPGA_IMAGE`)	Override the Cyclone III image (default `tzpu-quartus:13.1`).
`TZPU_QUARTUS_C4_IMAGE`	Override the Cyclone IV image (default `tzpu-quartus:17.1`).

I passi di build manuali per FPGA, CPLD e Docker rimangono pienamente supportati per gli utenti avanzati e le ricompilazioni parziali.

Siti di Riferimento

Resource	Link
tranZPUter SW-700 project page	/tranzputer-sw-700/
tranZPUter SW-700 User Manual	/tranzputer-sw-700-usermanual/
tranZPUter SW-700 Technical Guide	/tranzputer-sw-700-technicalguide/