tranZPUter FusionX Guide du Developpeur

Presentation

1. Modules noyau Linux (z80drv.ko, ttymzdrv.ko) — ecrits en C, construits contre l'arbre noyau Linux 4.9-rt SigmaStar. z80drv execute la boucle de distribution de l'emulation Z80 sur un coeur CPU isole et communique avec le CPLD via SPI et GPIO. ttymzdrv fournit une interface TTY pour le clavier et l'ecran de caracteres du Sharp MZ.
2. Utilitaires espace utilisateur (z80ctrl, k64fcpu, sharpbiter) — ecrits en C, compiles de maniere croisee avec arm-linux-gnueabihf-gcc. Ces utilitaires demarrent, arretent et configurent le module noyau a l'execution ; k64fcpu agit comme un daemon emulant l'interface du processeur virtuel K64F ; sharpbiter arbitre l'acces au clavier et a l'ecran entre le logiciel de la machine hote et la console Linux.
3. RTL CPLD (VHDL) — construit avec Altera Quartus II 13.0.1 SP1 Web Edition. Le CPLD est directement sur le bus Z80 de la machine hote et agit comme interface materielle entre les signaux physiques du bus Z80 et le SOM SigmaStar (System-on-Module). Il capture chaque cycle de bus, signale le SOM et pilote le bus de donnees Z80 pour le compte du SOM lors des cycles de lecture.

Arbre source

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

Configuration de l'environnement de developpement

Configuration et construction automatisees (recommande)

chmod +x setup_FusionX.sh
./setup_FusionX.sh

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

./build.sh                 # tous les composants
./build.sh --cpld          # uniquement les bit streams du CPLD
./build.sh --help          # lister toutes les options

Prerequis

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

sudo usermod -aG docker $USER
# Deconnectez-vous et reconnectez-vous pour que le changement de groupe prenne effet

Compilateur croise ARM (Linaro GCC 5.5)

# Telecharger Linaro GCC 5.5-2017.10 pour 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

# Extraire vers /opt (necessite root)
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

# Ajouter au PATH (ajoutez ceci a ~/.bashrc pour la persistance)
export PATH="/opt/arm-linux-gnueabihf/bin:$PATH"

# Verifier
arm-linux-gnueabihf-gcc --version
# Sortie attendue : arm-linux-gnueabihf-gcc (Linaro GCC 5.5-2017.10) 5.5.0

Images Docker Quartus II (constructions CPLD)

# Creer un repertoire de construction avec le Dockerfile et les fichiers de support
mkdir -p quartus-docker/files
cd quartus-docker

# Creer le Dockerfile (voir ci-dessous) comme Dockerfile.13.0.1
# Placer les fichiers suivants dans le sous-repertoire files/ :
#   license.dat              - Fichier de licence Quartus (factice pour Web Edition)
#   quartus2.ini             - Configuration Quartus
#   quartus2.qreg            - Parametres de registre Quartus
#   quartus_web_rules_file.txt - Regles Web edition
#   libjtag_hw_arrow.so      - Bibliotheque Arrow USB Blaster (optionnel, pour la programmation)
#   70-usb.rules             - Regles udev USB Blaster (optionnel)

# Construire l'image (telecharge ~4 Go d'installateurs Quartus pendant la construction)
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 .

FROM ubuntu:xenial
ENV DEBIAN_FRONTEND=noninteractive

ARG TARGET_DOWNLOAD_DIR=/tmp/
ARG INSTALLATION_DIR=/opt/altera
ARG ALTERA_DOWNLOAD_SITE=http://download.altera.com/akdlm/software/acdsinst
ARG QUARTUS_VERSION_INSTALLER=/13.0sp1/232/ib_installers/
ARG QUARTUS=QuartusSetupWeb-13.0.1.232.run
ARG QUARTUS_PROGRAMMER=QuartusProgrammerSetup-13.0.1.232.run
ARG QUARTUS_HELP=QuartusHelpSetup-13.0.1.232.run
ARG QUARTUS_DEVICE_FILES="cyclone_web-13.0.1.232.qdz max-13.0.1.232.qdz"

# Installer les bibliotheques 32 bits requises par Quartus II
RUN dpkg --add-architecture i386 && apt-get update && \
    apt-get install --no-install-recommends -y \
        ca-certificates wget make locales \
        libstdc++6:i386 libc6:i386 libx11-dev:i386 libxext-dev:i386 \
        libxau-dev:i386 libxdmcp-dev:i386 libfreetype6:i386 \
        libxtst6:i386 libxi6:i386 fontconfig:i386 expat:i386 \
        lib32ncurses5-dev libfontconfig1 libglib2.0-0 \
        libncurses5:i386 libsm6 libsm6:i386 libssl-dev \
        libxext6:i386 libxft2:i386 libxrender1 libzmq3-dev \
        libxrender-dev:i386 openjdk-8-jdk pkg-config && \
    rm -rf /var/lib/apt/lists/*

RUN echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen && locale-gen

# Telecharger et installer Quartus II
RUN wget -q --directory-prefix=${TARGET_DOWNLOAD_DIR} \
        ${ALTERA_DOWNLOAD_SITE}/${QUARTUS_VERSION_INSTALLER}/${QUARTUS} \
        ${ALTERA_DOWNLOAD_SITE}/${QUARTUS_VERSION_INSTALLER}/${QUARTUS_PROGRAMMER} \
        ${ALTERA_DOWNLOAD_SITE}/${QUARTUS_VERSION_INSTALLER}/${QUARTUS_HELP} && \
    for f in ${QUARTUS_DEVICE_FILES}; do \
        wget -q --directory-prefix=${TARGET_DOWNLOAD_DIR} \
            ${ALTERA_DOWNLOAD_SITE}/${QUARTUS_VERSION_INSTALLER}/${f}; \
    done

RUN chmod +x ${TARGET_DOWNLOAD_DIR}${QUARTUS} \
             ${TARGET_DOWNLOAD_DIR}${QUARTUS_PROGRAMMER} \
             ${TARGET_DOWNLOAD_DIR}${QUARTUS_HELP} && \
    ${TARGET_DOWNLOAD_DIR}${QUARTUS}            --mode unattended --installdir ${INSTALLATION_DIR}/ && \
    ${TARGET_DOWNLOAD_DIR}${QUARTUS_PROGRAMMER} --mode unattended --installdir ${INSTALLATION_DIR}/ && \
    ${TARGET_DOWNLOAD_DIR}${QUARTUS_HELP}       --mode unattended --installdir ${INSTALLATION_DIR}/ && \
    rm -rf ${TARGET_DOWNLOAD_DIR}/* ${INSTALLATION_DIR}/uninstall ${INSTALLATION_DIR}/logs/*

COPY ./files/license.dat ${INSTALLATION_DIR}/
RUN echo "export PATH=\$PATH:${INSTALLATION_DIR}/quartus/bin" >> /root/.bashrc

CMD ${INSTALLATION_DIR}/quartus/bin/quartus --64bit

# Compiler le bitstream CPLD MZ-80A (depuis la racine du depot FusionX)
docker run --rm --net=host \
    -v "$(pwd):$(pwd)" \
    -w "$(pwd)/CPLD/v1.0/MZ80A/build" \
    quartus-ii-13.0.1 \
    /opt/altera/quartus/bin/quartus_sh --flow compile tzpuFusionX_MZ80A

# Le fichier .pof de sortie sera dans CPLD/v1.0/MZ80A/build/output_files/
ls CPLD/v1.0/MZ80A/build/output_files/tzpuFusionX_MZ80A.pof

# Compiler les quatre cibles CPLD
for target in MZ80A MZ700 MZ2000 PCW8256; do
    echo "==> Compilation CPLD : ${target}"
    docker run --rm --net=host \
        -v "$(pwd):$(pwd)" \
        -w "$(pwd)/CPLD/v1.0/${target}/build" \
        quartus-ii-13.0.1 \
        /opt/altera/quartus/bin/quartus_sh --flow compile "tzpuFusionX_${target}"
done

# Activer le transfert X11 pour le conteneur Docker
xhost +local:docker

docker run --rm --net=host \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v "$(pwd):$(pwd)" \
    -w "$(pwd)/CPLD/v1.0/MZ80A/build" \
    quartus-ii-13.0.1 \
    /opt/altera/quartus/bin/quartus --64bit

Resume de la chaine d'outils

Clonage et construction

# Cloner le depot (inclut l'arbre noyau complet — environ 1,5 Go)
git clone https://git.eaw.app/eaw/tzpuFusionX.git
cd tzpuFusionX

# Initialiser les sous-modules git (bibliotheques d'emulation CPU Z80 et 6502)
git submodule update --init --recursive

# Tout construire (ROMs Z80, TZFS, CP/M, modules noyau, outils SPI, bitstreams CPLD)
./build.sh --all

# Ou construire des composants individuels :
./build.sh --asm           # ROMs assembleur Z80 et fichiers MZF
./build.sh --tzfs          # ROMs TZFS pour MZ-80A/700/2000
./build.sh --cpm           # Binaires CP/M 2.2
./build.sh --drivers       # Modules noyau (z80drv, ttymzdrv) et applications espace utilisateur
./build.sh --spi           # Outils SPI (mspi_main)
./build.sh --cpld          # Bitstreams CPLD (necessite image Docker Quartus)
./build.sh --image         # Image carte SD Linux (necessite arbre noyau complet)
./build.sh --clean         # Supprimer tous les artefacts de construction

Configuration du SDK

# S'assurer que le compilateur croise ARM est dans le PATH
export PATH="/opt/arm-linux-gnueabihf/bin:$PATH"

# Construire une image flash NAND complete pour le SOM SSD202
cd software/linux/
./Build_FusionX.sh -f nand -p ssd202 -o 2D06

Construction du module noyau

# Construire z80drv pour la cible MZ-80A
cd software/FusionX/src/z80drv
make MZ80A

# Copier le module construit vers une carte FusionX en fonctionnement via SSH
scp modules/z80drv.ko root@192.168.1.100:/apps/FusionX/modules/

# Sur la carte FusionX : decharger l'ancien module et charger le nouveau
rmmod z80drv
insmod /apps/FusionX/modules/z80drv.ko

Integration continue (Jenkins)

• Au moins 2 Go de RAM (4 Go recommandes — la compilation Quartus est gourmande en memoire)
• 20 Go d'espace disque libre (donnees Jenkins, images Docker, artefacts de construction)
• Docker et Docker Compose installes
• Acces reseau a votre depot Gitea (ou GitHub)
• Un nom de domaine ou une adresse IP statique (pour les callbacks de webhook)

# Installer Docker sur Debian/Ubuntu
sudo apt update && sudo apt install -y docker.io docker-compose
sudo systemctl enable docker
sudo systemctl start docker

# Permettre a votre utilisateur d'executer les commandes Docker sans sudo
sudo usermod -aG docker $USER
# Deconnectez-vous et reconnectez-vous pour que le changement de groupe prenne effet

Structures de donnees cles

Carte memoire

// z80driver.h — exemple de carte memoire MZ-80A
#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;       // Debut de l'espace d'adressage Z80
    uint32_t  size;           // Taille de la region en octets
    uint8_t  *data;           // Pointeur vers le tampon memoire emule
    uint8_t   type;           // MEM_ROM, MEM_RAM, MEM_VHARDWARE, MEM_PHYSICAL
    void     (*read_fn)(uint16_t addr, uint8_t *data);   // Gestionnaire de lecture materiel virtuel
    void     (*write_fn)(uint16_t addr, uint8_t data);   // Gestionnaire d'ecriture materiel virtuel
} t_memRegion;

Requete de cycle de bus

// Informations de cycle de bus capturees depuis les broches GPIO du CPLD
typedef struct {
    uint16_t  address;        // Bus d'adresses Z80 A0-A15
    uint8_t   data;           // Bus de donnees Z80 D0-D7
    uint8_t   busType;        // BUS_MREQ_RD, BUS_MREQ_WR, BUS_IORQ_RD, BUS_IORQ_WR, BUS_M1
    bool      isRead;         // true = cycle de lecture, false = cycle d'ecriture
} t_busCycle;

Interface de module materiel virtuel

// Chaque z80vhw_*.c implemente ces fonctions :

// Appele une fois au chargement du module — enregistrer les regions memoire/E/S et les gestionnaires
int vhw_init(void);

// Gestionnaire de lecture memoire — appele par la boucle de distribution pour les regions mappees en memoire
uint8_t vhw_mem_read(uint16_t addr);

// Gestionnaire d'ecriture memoire
void vhw_mem_write(uint16_t addr, uint8_t data);

// Gestionnaire de lecture E/S (non utilise pour les machines basees sur 6502, toujours present pour Z80)
uint8_t vhw_io_read(uint16_t port);

// Gestionnaire d'ecriture E/S
void vhw_io_write(uint16_t port, uint8_t data);

// Appele lors du RESET Z80 — reinitialiser l'etat materiel
void vhw_reset(void);

// Appele periodiquement depuis la boucle de distribution — pour les timers, l'emulation sonore, etc.
void vhw_tick(uint64_t cycles);

z80driver.c — Boucle de distribution

// Boucle de distribution simplifiee (z80driver.c)
static int z80_emulation_thread(void *data)
{
    while (!kthread_should_stop()) {
        // 1. Attendre que le CPLD signale un cycle de bus en attente (IRQ GPIO ou interrogation)
        t_busCycle cycle = cpld_read_bus_cycle();    // lit les broches GPIO

        // 2. Distribuer en fonction du type de cycle et de l'adresse
        if (cycle.busType == BUS_M1) {
            // Fetch d'opcode — executer une instruction Z80 via la bibliotheque Zeta
            zeta_run_one_instruction(&z80_state);

        } else if (cycle.busType == BUS_MREQ_RD) {
            // Lecture memoire
            uint8_t data = dispatch_mem_read(cycle.address);
            cpld_write_data(data);                   // ecriture SPI vers CPLD

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

        } else if (cycle.busType == BUS_IORQ_RD) {
            // Lecture E/S
            uint8_t data = dispatch_io_read(cycle.address & 0xFF);
            cpld_write_data(data);

        } else if (cycle.busType == BUS_IORQ_WR) {
            // Ecriture E/S
            dispatch_io_write(cycle.address & 0xFF, cycle.data);
        }

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

Ajouter une nouvelle machine

Etape 1 — Definir la carte memoire dans z80driver.h

#ifdef TARGET_SPECTRUM48K
  #define TARGET_NAME           "Spectrum48K"
  #define SPECTRUM_ROM_ADDR     0x0000
  #define SPECTRUM_ROM_SIZE     0x4000   // 16KB Spectrum ROM
  #define SPECTRUM_RAM_ADDR     0x4000
  #define SPECTRUM_RAM_SIZE     0xC000   // 48KB RAM
  #define SPECTRUM_ULA_PORT     0xFE    // ULA I/O port (keyboard, border, speaker, tape)
#endif

Etape 2 — Creer le module materiel virtuel

Ajouter un peripherique materiel virtuel

// Dans z80vhw_mz80a.c — ajouter une RTC virtuelle au port E/S 0xB0-0xB7

typedef struct {
    uint8_t seconds, minutes, hours, day, month, year;
} t_virtualRTC;

static t_virtualRTC rtc = {0};

static uint8_t rtc_read(uint16_t port) {
    switch (port & 0x07) {
        case 0: return rtc.seconds;
        case 1: return rtc.minutes;
        case 2: return rtc.hours;
        case 3: return rtc.day;
        case 4: return rtc.month;
        case 5: return rtc.year;
        default: return 0xFF;
    }
}

static void rtc_write(uint16_t port, uint8_t data) {
    switch (port & 0x07) {
        case 0: rtc.seconds = data; break;
        case 1: rtc.minutes = data; break;
        case 2: rtc.hours   = data; break;
        case 3: rtc.day     = data; break;
        case 4: rtc.month   = data; break;
        case 5: rtc.year    = data; break;
        default: break;
    }
}

// Dans vhw_init() :
register_io_handler(0xB0, 0x08, rtc_read, rtc_write);

Modifier le CPLD

Ajouter une nouvelle commande SPI

-- Dans tzpuFusionX_pkg.vhd — ajouter une nouvelle constante de commande
constant CMD_SET_BORDER : std_logic_vector(7 downto 0) := x"42";

-- Dans le processus decodeur SPI de tzpuFusionX.vhd
when CMD_SET_BORDER =>
    border_colour <= spi_data_in(2 downto 0);

Compilation croisee des utilitaires utilisateur

# Compiler z80ctrl de maniere croisee pour un test rapide
arm-linux-gnueabihf-gcc -o z80ctrl z80ctrl.c -lpthread

# Copier vers une carte FusionX en fonctionnement via SSH
scp z80ctrl root@192.168.1.100:/apps/FusionX/bin/

Mise a jour firmware OTA

Construction de l'image de mise a jour

cd software/linux/
./Build_FusionX.sh -f nand -p ssd202 -o 2D06 -m 256

Preparation de la carte SD

# Preparer la carte SD (en supposant que la carte SD est montee sur /media/sdcard)
mkdir -p /media/sdcard/FusionX/upgrade/
cp project/image/output/images/uboot.img       /media/sdcard/FusionX/upgrade/
cp project/image/output/images/kernel.img      /media/sdcard/FusionX/upgrade/
cp project/image/output/images/rootfs.ubifs    /media/sdcard/FusionX/upgrade/
cp project/image/output/images/FusionX_apps.tar /media/sdcard/FusionX/upgrade/
touch /media/sdcard/FusionX/upgrade/DO_UPGRADE
sync
umount /media/sdcard

Pieges courants

• Blocage sur CPU0 dans z80drv : tout appel systeme Linux (E/S fichier, allocation memoire via kmalloc avec GFP_KERNEL, mise en veille) depuis du code s'executant dans la boucle de distribution z80drv sur le CPU1 risque la preemption du planificateur ou le blocage. Utilisez uniquement des API noyau securisees et non bloquantes dans le chemin critique.
• Non-correspondance de variante du bitstream CPLD : compiler le CPLD avec les affectations de broches MZ-80A et le programmer dans du materiel connecte a un MZ-700 cause une synchronisation de bus et un decodage d'adresses incorrects. Verifiez toujours les parametres du projet Quartus II avant la programmation.
• Isolation CPU non active : si isolcpus=1 n'est pas present dans les arguments de demarrage du noyau, le planificateur Linux preemptera le thread de distribution z80drv pendant les cycles de bus Z80, causant le blocage ou le plantage de la machine hote.
• Decalage d'horloge SPI : le bus SPI du SOM fonctionne a 50 MHz, ce qui necessite une disposition PCB soignee avec des longueurs de piste appariees et un plan de masse adequat sous les lignes SPI.
• Image ROM manquante : z80ctrl --loadrom peut signaler le succes meme si le fichier ROM n'est pas trouve sur la carte SD. Verifiez toujours avec dmesg | grep z80drv que le module noyau signale un chargement ROM reussi avant de demarrer le Z80.
• Frequence de vhw_tick : vhw_tick() est appele environ toutes les 2048 cycles Z80, pas toutes les 2048 microsecondes. A 4 MHz, cela correspond a environ 0,5 ms par tick.
• Latence de lecture GPIO : le chemin de lecture GPIO utilise pour capturer le bus d'adresses Z80 et le type de cycle a un overhead d'environ 200 ns par lecture sur le SOM SigmaStar. C'est suffisamment rapide pour le fonctionnement Z80 a 4 MHz mais peut etre marginal pour les machines fonctionnant a des vitesses d'horloge superieures.

Sites de reference

Avis reglementaire sans fil