Sistema de archivos ROM (RFS) — Guia del desarrollador

Guia del desarrollador RFS

Introduccion al ensamblador Z80 para programadores no familiarizados con el ensamblador

Arbol de fuentes

Configuracion: 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 conmutacion de bancos en detalle

; 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

Recorridos por los modulos

Agregar un nuevo 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

Agregar una nueva plataforma de hardware

Consejos de depuracion

Entorno de compilacion

# 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 (recomendado — nativo, sin WSL). Desde un simbolo del sistema de PowerShell:

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

Windows 10 / 11 — setup_RFS_windows.ps1 (alternativa — compila dentro de WSL2 / Ubuntu). Desde una PowerShell de Administrador:

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. Envias codigo a la rama master del repositorio de Gitea.
2. Gitea envia un webhook (una notificacion HTTP) al servidor Jenkins.
3. Jenkins clona el repositorio en un espacio de trabajo nuevo y limpio.
4. Jenkins ejecuta ./build.sh --asm que ensambla todos los ROMs del monitor Z80 y los archivos MZF usando el ensamblador GLASS.
5. Jenkins empaqueta los archivos ROM y MZF ensamblados en un tarball versionado (FusionX-ROMs-v1.08.tar.gz).
6. Jenkins crea una Release de Gitea con el tarball adjunto como un recurso descargable.
7. Jenkins envia un correo electronico informando del exito o el fallo.

# 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. Hacer clic en New Item en el panel de Jenkins.
2. Introducir un nombre (p. ej. RFS-Build), seleccionar Pipeline, hacer clic en OK.
3. En la seccion Pipeline, establecer Definition en "Pipeline script" y pegar esto:

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

Enlaces de referencia