Sistema di archiviazione ROM (RFS) — Guida per sviluppatori

Guida per sviluppatori RFS

Introduzione all'assembly Z80 per programmatori non-assembly

Albero dei sorgenti

Configurazione: rfs_definitions.asm

HW_SPI_ENA    EQU 1    ; 1 = hardware SPI on RomDisk v2+ PCB
SW_SPI_ENA    EQU 0    ; 1 = software bit-bang SPI (RomDisk v1)
PP_SPI_ENA    EQU 0    ; 1 = SPI via parallel port (RomDisk v1 alternative)
FUSIONX_ENA   EQU 0    ; 1 = running on tranZPUter FusionX
KUMA80_ENA    EQU 0    ; 1 = Kuma 40/80 upgrade present
VIDEOMODULE_ENA EQU 0  ; 1 = 40/80 colour video module present
BUILD_ROMDISK EQU 0    ; 1 = build for RomDisk card
BUILD_SFD700  EQU 0    ; 1 = build for SFD-700 floppy interface
BUILD_PICOZ80 EQU 1    ; 1 = build for picoZ80 board
ENADEBUG      EQU 0    ; 1 = enable debug output during assembly

UROMADDR    EQU 0E800H   ; Base address of the User ROM window
UROMBSTBL   EQU UROMADDR + 020H   ; Bank-switch table entry point (fixed offset)
RFSJMPTABLE EQU UROMADDR + 0B0H   ; RFS jump table start
FDCROMADDR  EQU 0F000H   ; FDC ROM address (SFD-700 MROM location)

; SFD-700 specific bank defaults (only assembled when BUILD_SFD700 = 1):
BNKDEFMROM_MZ80A EQU 0   ; Default MROM bank for MZ-80A (AFI ROM)
BNKDEFMROM_MZ700 EQU 1   ; Default MROM bank for MZ-700 (AFI ROM)
BNKDEFUROM       EQU 2   ; Default UROM bank for RFS (starts at 8KB in Flash)

BELL    EQU 007H    ; Terminal bell
CR      EQU 00DH    ; Carriage return
LF      EQU 00AH    ; Line feed
CS      EQU 00CH    ; Clear screen
SPACE   EQU 020H    ; ASCII space
DELETE  EQU 07FH    ; Delete key

La commutazione banchi in dettaglio

; One command table entry:
;
;   DB  FLAGS          ; 1 byte: END|MATCH|BANK[5:3]|SIZE[2:0]
;   DB  "COMMAND"      ; SIZE bytes: the command string (no null terminator)
;   DW  HANDLER_ADDR   ; 2 bytes: address of the handler routine in the named bank
;
; Flags byte:
;   Bit 7 = 1: End of table marker (last entry).
;   Bit 6 = 1: Exact match required (command must be entire input, no trailing chars).
;   Bits 5:3   Bank number where HANDLER_ADDR lives (0-11 for RFS, 12-15 for CBIOS).
;   Bits 2:0   Length of the command string in bytes.
;
; Example - the ASM command (all builds, lives in bank 6, 3-char string):
CMDTABLE:
    DB  000H | 000H | 030H | 003H    ; FLAGS: not-end, not-exact, bank 6, length 3
    DB  "ASM"                         ; Command string
    DW  ASM_MAIN                      ; Handler address in bank 6

Analisi dei moduli

Aggiungere un nuovo comando del monitor

; FLAGS: not-end (bit7=0), not-exact (bit6=0), bank 3 (bits5:3 = 011 = 0x18), length 3 (bits2:0 = 011)
    DB  000H | 000H | 018H | 003H
    DB  "FOO"
    DW  FOO_CMD

Aggiungere una nuova piattaforma hardware

Suggerimenti per il debug

Ambiente di build

# Install Java runtime (required for the GLASS assembler)
sudo apt install -y default-jre git

# Clone the repository
git clone https://git.eaw.app/eaw/tzpuFusionX.git
cd tzpuFusionX

# Initialise git submodules
git submodule update --init --recursive

macOS / Linux / WSL — setup_RFS.sh

chmod +x setup_RFS.sh
./setup_RFS.sh

Windows 10 / 11 — setup_RFS_windows_native.ps1 (consigliato — nativo, senza WSL). Da un prompt PowerShell:

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

Windows 10 / 11 — setup_RFS_windows.ps1 (alternativa — compila all’interno di WSL2 / Ubuntu). Da una PowerShell come Amministratore:

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

# Build all Z80 assembly ROMs and MZF files (includes RFS)
./build.sh --asm

# Build output appears in software/roms/
ls software/roms/*.rom software/roms/*.mzf

1. Si invia il codice al ramo master del repository Gitea.
2. Gitea invia un webhook (una notifica HTTP) al server Jenkins.
3. Jenkins clona il repository in un workspace nuovo e pulito.
4. Jenkins esegue ./build.sh --asm che assembla tutte le ROM del monitor Z80 e i file MZF usando l'assemblatore GLASS.
5. Jenkins impacchetta i file ROM e MZF assemblati in un tarball versionato (FusionX-ROMs-v1.08.tar.gz).
6. Jenkins crea una Release Gitea con il tarball allegato come asset scaricabile.
7. Jenkins invia un'email che riporta successo o fallimento.

# Install Docker (Debian/Ubuntu)
sudo apt update && sudo apt install -y docker.io docker-compose
sudo systemctl enable docker && sudo systemctl start docker

# Create the Jenkins directory
sudo mkdir -p /srv/jenkins/data
cd /srv/jenkins

# /srv/jenkins/docker-compose.yml
version: '3.8'
services:
  jenkins:
    image: jenkins/jenkins:lts
    ports:
      - "8080:8080"
    volumes:
      - /srv/jenkins/data:/var/jenkins_home
    environment:
      - JAVA_OPTS=-Djenkins.install.runSetupWizard=false
    restart: unless-stopped

# Start Jenkins
docker-compose up -d

# Get the initial admin password (first run only)
docker-compose logs jenkins | grep "initial admin password" -A 2

# Open http://your-server:8080 in a browser

1. Fare clic su New Item nella dashboard di Jenkins.
2. Inserire un nome (es. RFS-Build), selezionare Pipeline, fare clic su OK.
3. Nella sezione Pipeline, impostare Definition su "Pipeline script" e incollare questo:

pipeline {
    agent any
    environment {
        GITEA_URL   = "https://git.eaw.app"
        REPO_URL    = "https://git.eaw.app/eaw/tzpuFusionX.git"
        GITEA_TOKEN = credentials('gitea-api-token')
        GITEA_OWNER = "eaw"
        GITEA_REPO  = "tzpuFusionX"
    }
    triggers {
        GenericTrigger(
            genericVariables: [[key: 'ref', value: '$.ref']],
            causeString: 'Triggered by Gitea push to $ref',
            token: 'rfs-build-trigger',
            regexpFilterText: '$ref',
            regexpFilterExpression: '^refs/heads/(main|master)$'
        )
    }
    stages {
        stage('Checkout') {
            steps {
                cleanWs()
                git url: "${REPO_URL}", branch: 'master'
                sh 'git submodule update --init --recursive'
            }
        }
        stage('Build Assembly ROMs') {
            steps {
                sh 'chmod +x build.sh && mkdir -p software/tmp software/roms'
                sh './build.sh --asm'
            }
        }
        stage('Package') {
            steps {
                script {
                    def ver = readFile('VERSION').trim()
                    sh "cd software/roms && tar czf ../../FusionX-ROMs-v${ver}.tar.gz *.rom *.mzf"
                    archiveArtifacts artifacts: "FusionX-ROMs-v${ver}.tar.gz"
                }
            }
        }
    }
    post {
        success { mail to: 'your-email@example.com', subject: "RFS Build - SUCCESS", body: "Build completed." }
        failure { mail to: 'your-email@example.com', subject: "RFS Build - FAILED", body: "Check console output." }
        always  { cleanWs() }
    }
}

• Target URL: http://your-server:8080/generic-webhook-trigger/invoke?token=rfs-build-trigger
• Content Type: application/json
• Trigger On: Push Events

Link di riferimento