tranZPUter FusionX Guia del Desarrollador

Descripcion general

1. Modulos del kernel Linux (z80drv.ko, ttymzdrv.ko) — escritos en C, compilados contra el arbol del kernel Linux 4.9-rt de SigmaStar. z80drv ejecuta el bucle de despacho de emulacion Z80 en un nucleo de CPU aislado y se comunica con el CPLD a traves de SPI y GPIO. ttymzdrv proporciona una interfaz TTY al teclado y pantalla de caracteres del Sharp MZ.
2. Utilidades de espacio de usuario (z80ctrl, k64fcpu, sharpbiter) — escritas en C, compiladas cruzadas con arm-linux-gnueabihf-gcc.
3. RTL CPLD (VHDL) — compilado con Altera Quartus II 13.0.1 SP1 Web Edition. El CPLD se encuentra directamente en el bus Z80 de la maquina host y actua como interfaz de hardware entre las senales fisicas del bus Z80 y el SOM SigmaStar.

Arbol de fuentes

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
            ├── ttymz/
            │   └── 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

Configuracion del entorno de desarrollo

Configuracion y compilacion automatizadas (recomendado)

# Linux / macOS
chmod +x setup_FusionX.sh
./setup_FusionX.sh

# Windows 10/11 (nativo, sin WSL2)
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_FusionX_windows_native.ps1

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

# Descargar Linaro GCC 5.5-2017.10 para ARM hard-float
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
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
export PATH="/opt/arm-linux-gnueabihf/bin:$PATH"

Clonacion y compilacion

git clone https://git.eaw.app/eaw/tzpuFusionX.git
cd tzpuFusionX
git submodule update --init --recursive
./build.sh --all

Estructuras de datos clave

typedef struct {
    uint32_t  baseAddr;       // Inicio del espacio de direcciones Z80
    uint32_t  size;           // Tamano de la region en bytes
    uint8_t  *data;           // Puntero al buffer de memoria emulada
    uint8_t   type;           // MEM_ROM, MEM_RAM, MEM_VHARDWARE, MEM_PHYSICAL
    void     (*read_fn)(uint16_t addr, uint8_t *data);
    void     (*write_fn)(uint16_t addr, uint8_t data);
} t_memRegion;

Agregar una nueva maquina

1. Definir el mapa de memoria en z80driver.h
2. Crear el modulo de hardware virtual (z80vhw_*.c)
3. Crear el directorio de variante de compilacion
4. Crear la variante VHDL CPLD
5. Crear el script de inicio

Errores comunes

• Bloqueo en CPU0 en z80drv: cualquier llamada al sistema Linux desde codigo ejecutandose en el bucle de despacho z80drv en la CPU1 arriesga la preemption del planificador o un deadlock.
• Desajuste de variante del bitstream CPLD: compilar el CPLD con las asignaciones de pines del MZ-80A y programarlo en hardware conectado a un MZ-700 causa temporizacion del bus y decodificacion de direcciones incorrectas.
• Aislamiento de CPU no activo: si isolcpus=1 no esta presente en los argumentos de arranque del kernel, el planificador Linux interrumpira el hilo de despacho z80drv.
• Imagen ROM faltante: siempre verifique con dmesg | grep z80drv que el modulo del kernel reporte una carga de ROM exitosa antes de iniciar el Z80.

Sitios de referencia

Aviso regulatorio inalambrico