Sistema di archiviazione tranZPUter (TZFS) -- Guida per sviluppatori

Guida per sviluppatori TZFS

Questa guida e una presentazione dettagliata del codice sorgente e dell'ambiente di sviluppo del TZFS (tranZPUter Filing System). Spiega i concetti dell'assembly Z80, esamina ogni modulo sorgente, documenta l'architettura di commutazione banchi TZMM e mostra come aggiungere nuovi comandi, modificare moduli esistenti e portare TZFS su nuove piattaforme hardware.

Per l'architettura hardware consultare la Guida tecnica. Per l'uso quotidiano consultare il Manuale utente.

Introduzione all'assembly Z80

Registro	Dimensione	Ruolo
A	8 bit	Accumulatore – registro principale per operazioni aritmetiche, logiche e I/O.
B, C	8 bit	Uso generale. BC forma una coppia a 16 bit.
H, L	8 bit	Uso generale. HL e il puntatore di memoria principale a 16 bit.
IX, IY	16 bit	Registri indice – per indirizzamento base+spostamento.
SP	16 bit	Stack Pointer.
PC	16 bit	Program Counter.

Albero dei sorgenti

Percorso	Contenuto
`asm/tzfs.asm`	Bank 0: punto d’ingresso, dispatcher comandi, tabelle di salto
`asm/tzfs_bank2.asm`	Bank 1: messaggi, aiuto, routine di stampa, conversione Sharp/ASCII
`asm/tzfs_bank3.asm`	Bank 2: utilita di memoria, I/O, compensazione nastro, comandi CPU/emulazione
`asm/tzfs_bank4.asm`	Bank 3: assemblatore e disassemblatore Z80 completi (occupa 52 KB)
`asm/include/tzfs_definitions.asm`	Costanti di configurazione e definizioni porte I/O

Commutazione banchi in dettaglio

Modo TZMM	Valore	0xE800-0xEFFF	0xF000-0xFFFF	Usato da
TZMM_TZFS	0x22	Nucleo TZFS (bank 0)	Nucleo TZFS (bank 0)	Operazione normale
TZMM_TZFS2	0x23	Nucleo TZFS (bank 0)	tzfs_bank2 (bank 1)	Aiuto, messaggi
TZMM_TZFS3	0x24	Nucleo TZFS (bank 0)	tzfs_bank3 (bank 2)	Utilita di memoria
TZMM_TZFS4	0x25	–	tzfs_bank4 (bank 3)	Assemblatore/disassemblatore

Esame dei moduli

tzfs.asm -- Dispatcher comandi (Bank 0)

Punto d'ingresso per tutte le funzionalita TZFS. Contiene tabella di salto esterna, stub inter-banco, tabella comandi e loop del dispatcher.

tzfs_bank2.asm -- Messaggi e aiuto (Bank 1)

Output testuale: conversione set di caratteri, stampa formattata, visualizzazione nomi file e schermata di aiuto.

tzfs_bank3.asm -- Utilita (Bank 2)

Editing memoria, dump esadecimale, copia blocchi, riempimento, accesso porte I/O, compensazione nastro, controllo emulazione e commutazione CPU.

tzfs_bank4.asm -- Assemblatore / Disassemblatore (Bank 3)

Assemblatore e disassemblatore Z80 interattivi completi che utilizzano 52 KB.

Aggiungere un nuovo comando monitor

Scrivere il gestore nel file di banco appropriato.

Aggiungere uno stub ?-prefissato in tzfs.asm.

Aggiungere una voce a CMDTABLE in tzfs.asm.

Aggiungere il testo di aiuto a HELPSCR in tzfs_bank2.asm.

Eseguire ./build.sh.

Suggerimenti per il debug

Attivare output di debug: ENADEBUG EQU 1 in tzfs_definitions.asm.

Sondare porte I/O con RIO/WIO. Ispezionare il blocco variabili TZFS: D EC80. Ispezionare il blocco servizio K64F: D ED80.

Ambiente di build

La build di TZFS usa l'assemblatore GLASS Z80 (incluso nel repository) e lo script di build globale FusionX. Per compilare i componenti in assembly Z80 servono solo un runtime Java e git. Il modo consigliato per compilare e lo script di setup automatizzato per la propria piattaforma (vedere Setup e build automatizzati di seguito); i passaggi manuali e FusionX che seguono sono per utenti avanzati e ricostruzioni parziali.

Setup e build automatizzati (consigliato)

Il modo consigliato per compilare TZFS e lo script di setup autonomo per la propria piattaforma. Installa i prerequisiti (Java per l'assemblatore GLASS Z80, piu git/perl/coreutils; su Windows, Git Bash + Java), clona il repository, scarica il bundle dei contenuti e puo compilare le immagini ROM — il tutto in modo interattivo, con valori predefiniti ragionevoli che potete accettare premendo Invio. Copiate il singolo file relativo alla vostra piattaforma ed eseguitelo.

macOS / Linux / WSL — setup_TZFS.sh

chmod +x setup_TZFS.sh
./setup_TZFS.sh

Lo script installa Java (che esegue l'assemblatore GLASS, tools/glass-0.5.1.jar), una toolchain C + make (per compilare il submodule cpmtools), perl e git; su macOS installa anche GNU coreutils e bash 4, aggiungendoli al PATH tramite un tzfs_env.sh generato. Se assente, scarica il bundle dei contenuti TZFS_Files.zip (~110 MB di contenuti MZF/DSK/CPM/CAS/BAS/BASIC).

Windows 10 / 11 — setup_TZFS_windows.ps1 (Git Bash nativo, senza WSL). Da PowerShell:

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

Lo script Windows usa winget per installare Git for Windows (che fornisce bash, coreutils, perl e curl) e la Temurin 17 JRE (Java), clona il repository, scarica il bundle dei contenuti ed esegue ./build.sh tramite Git Bash. Un tools\cpmcp.exe precompilato e incluso, quindi non serve un compilatore C su Windows.

Domande poste dal setup, e cosa fare. Ogni richiesta ha un valore predefinito sicuro tra parentesi — la lettera maiuscola e il valore predefinito, quindi premendo Invio lo si accetta.

macOS / Linux / WSL (setup_TZFS.sh):

Richiesta	Predefinito	Cosa fare
`Install now? [Y/n]` (pacchetti mancanti)	Si	Invio — installa i prerequisiti mancanti; potrebbe richiedere la password `sudo`.
`Repo URL [https://git.eaw.app/eaw/TZFS.git]`	repo pubblico	Invio per il repo pubblico, oppure incollare un URL diverso (privato).
`Install directory [~/TZFS]`	`~/TZFS`	Invio per `~/TZFS`, oppure digitare un percorso.
`Download and install them now? [Y/n]` (bundle dei contenuti)	Si	Invio per scaricare i contenuti MZF/DSK/CPM/CAS/BAS/BASIC necessari per una build completa.
`Run the build now (./build.sh …)? [Y/n]`	Si	Invio per compilare subito (verifica l’ambiente).

Windows (setup_TZFS_windows.ps1):

Richiesta	Predefinito	Cosa fare
`Repo URL [https://git.eaw.app/eaw/TZFS.git]`	repo pubblico	Invio per il repo pubblico, oppure incollare un URL diverso.
`TZFS checkout directory [%USERPROFILE%\TZFS]`	`%USERPROFILE%\TZFS`	Invio per il valore predefinito, oppure digitare un percorso.
`Download and install them … now? [Y/n]` (bundle dei contenuti)	Si	Invio per scaricare il bundle dei contenuti.
`Build the TZFS firmware now (runs ./build.sh via Git Bash)? [Y/n]`	Si	Invio per compilare subito tramite Git Bash.

Impostare la variabile d'ambiente TZFS_REPO_URL per sovrascrivere l'URL del repository predefinito senza modificare lo script.

Output e ricompilazione. Le immagini ROM vengono scritte in roms/ — ad esempio tzfs.rom, le varianti FusionX, le ROM del monitor e i binari CP/M. Per ricompilare in seguito, spostatevi nel checkout (cd ~/TZFS); su macOS eseguite prima source ./tzfs_env.sh per aggiungere GNU coreutils e bash 4 al PATH; quindi eseguite ./build.sh (oppure ./build.sh -m per rielaborare anche i sorgenti MZF). Su Windows, eseguite ./build.sh da Git Bash all'interno del checkout.

Compilazione (manuale / FusionX)

# Compila le ROM TZFS per tutte le macchine target
./build.sh --tzfs

# Compila CP/M (il CBIOS fa parte dell'albero sorgente TZFS)
./build.sh --cpm

# Compila tutto (ROM, TZFS, CP/M, driver, CPLD)
./build.sh --all

Siti di riferimento

Risorsa	Link
Pagina del progetto TZFS	/sharpmz-upgrades-tzfs/
Manuale utente TZFS	/sharpmz-upgrades-tzfs-usermanual/
Guida tecnica TZFS	/sharpmz-upgrades-tzfs-technicalguide/