tranZPUter SW-700 — Guia del Desarrollador

English

Guia del Desarrollador del tranZPUter SW-700

Esta guia es un recorrido detallado por el codigo fuente y el entorno de desarrollo del tranZPUter SW-700. Introduce VHDL para desarrolladores no familiarizados con el lenguaje, recorre cada modulo fuente principal, documenta los disenos CPLD y FPGA, explica la arquitectura de mapeo de memoria y conmutacion de CPU, y muestra como compilar el firmware, agregar soporte para nuevas maquinas Sharp MZ y depurar problemas de hardware.
Para la arquitectura de hardware, ver la pagina del tranZPUter SW-700. Para los comandos TZFS, ver el Manual de Usuario TZFS.

Introduccion a VHDL para Programadores No-HDL

Toda la logica digital del tranZPUter SW-700 esta escrita en VHDL. A diferencia del software, VHDL describe hardware que se ejecuta en paralelo — cada bloque process se ejecuta simultanea y continuamente.

ENTITY y ARCHITECTURE
Cada modulo VHDL tiene dos partes:
  • ENTITY declara la interfaz del modulo — sus pines de entrada y salida.
  • ARCHITECTURE contiene la implementacion — senales internas, instanciaciones de componentes y procesos.
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;

SENALES
Las senales son los cables internos de un modulo VHDL. Los tipos mas comunes son std_logic, std_logic_vector, unsigned e integer.

PROCESS
Un process es un bloque de instrucciones VHDL secuenciales que se reejecuta cada vez que una senal en su lista de sensibilidad cambia.

Arbol de Fuentes

Todo el codigo fuente esta organizado bajo el repositorio tranZPUter.

Configuracion y compilacion automatizada (recomendado)

Antes de seguir los pasos manuales de Quartus y Docker que aparecen a continuacion, tenga en cuenta que todo el entorno puede configurarse por usted. El script de configuracion incluido para su plataforma instala las herramientas base, instala Java (JRE) para el ensamblador GLASS de Z80 y Docker, construye las tres imagenes Docker de Quartus descritas en la seccion Entorno de Compilacion Docker, clona el repositorio --recurse-submodules (TZFS, zSoft/zOS, zpu), y ofrece ejecutar la primera compilacion (./build.sh -t all). Quartus no se instala en el host — las compilaciones de CPLD y FPGA se ejecutan dentro de las imagenes Docker. Cada script es 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 — haga doble clic en setup_tranZPUter_windows.cmd, o desde PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_tranZPUter_windows_native.ps1
Las tres imagenes construidas son tzpu-quartus:13.0.1 (CPLDs MAX7000), tzpu-quartus:13.1 (Cyclone III, SW-700 v1.2) y tzpu-quartus:17.1 (Cyclone IV, SW-700 v1.3 / Fusion) — todas Web/Lite Edition gratuitas, sin licencia. La compilacion se controla mediante build.sh, que ejecuta Quartus de forma nativa si encuentra una version compatible, de lo contrario dentro de estas imagenes (Java/GLASS siempre se ejecuta de forma nativa). Las salidas (.pof, .sof, flash de arranque .jic, imagenes ROM/TZFS/CP/M) se recopilan en ./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

Sobreescrituras utiles de variables de entorno:

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).
Los pasos manuales de compilacion de FPGA, CPLD y Docker que aparecen debajo siguen siendo totalmente compatibles para usuarios avanzados y recompilaciones parciales.

Sitios de Referencia

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/