ROM-Dateisystem (RFS) — Entwicklerhandbuch

RFS-Entwicklerhandbuch

Einfuehrung in Z80-Assembler fuer Nicht-Assembler-Programmierer

Quellbaum

Konfiguration: 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

Bank-Switching im Detail

; 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

Modul-Walkthroughs

Einen neuen Monitorbefehl hinzufuegen

; 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

Eine neue Hardware-Plattform hinzufuegen

Debugging-Tipps

Build-Umgebung

# 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 (empfohlen — nativ, kein WSL). An einer PowerShell-Eingabeaufforderung:

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

Windows 10 / 11 — setup_RFS_windows.ps1 (Alternative — baut innerhalb von WSL2 / Ubuntu). Aus einer PowerShell mit Administratorrechten:

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. Sie pushen Code zum master-Branch des Gitea-Repositorys.
2. Gitea sendet einen Webhook (eine HTTP-Benachrichtigung) an den Jenkins-Server.
3. Jenkins klont das Repository in einen frischen, sauberen Arbeitsbereich.
4. Jenkins fuehrt ./build.sh --asm aus, was alle Z80-Monitor-ROMs und MZF-Dateien mit dem GLASS-Assembler assembliert.
5. Jenkins paketiert die assemblierten ROM- und MZF-Dateien in einen versionierten Tarball (FusionX-ROMs-v1.08.tar.gz).
6. Jenkins erstellt einen Gitea-Release mit dem angehaengten Tarball als herunterladbares Asset.
7. Jenkins sendet eine E-Mail, die Erfolg oder Fehlschlag meldet.

# 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. Klicken Sie auf New Item auf dem Jenkins-Dashboard.
2. Geben Sie einen Namen ein (z.B. RFS-Build), waehlen Sie Pipeline, klicken Sie auf OK.
3. Setzen Sie im Abschnitt Pipeline die Definition auf "Pipeline script" und fuegen Sie dies ein:

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

Referenz-Links