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.
Avviare dischi floppy da TZFS (GETBOOTDSK)
Da TZFS v1.8.3, TZFS puo avviare un disco floppy MZ-80A / MZ-700 / MZ-800 — incluso CP/M dell'MZ-800 — direttamente dall'interno del filing system, e tornare a TZFS premendo l'interruttore RESET hardware dopo che l'OS avviato da floppy ha girato. La routine che fa questo e
Accettazione del machine-ID e rilevamento IPLPRO
GETBOOTDSK. Reimplementa, nella finestra della User ROM, il comportamento dell'IPL nativo della macchina (l'IPL disco nativo 9Z-504M) in modo abbastanza fedele da impedire a un boot loader di secondo stadio sul disco di accorgersi che sta girando sotto TZFS anziche sotto il monitor di fabbrica. Questa sezione documenta il dettaglio a livello di sviluppatore di tale routine e delle modalita di memoria che la supportano.
Il primo settore di un disco Sharp avviabile contiene un identificatore di macchina e la firma ASCII
Pre-paginazione del blocco 7 per OS che caricano sotto 1000H
"IPLPRO". Le versioni precedenti di TZFS accettavano un solo machine id cablato; GETBOOTDSK ora accetta qualsiasi machine id Sharp valido — 01 (MZ-2000), 02 (MZ-80A/MZ-80K) e 03 (MZ-700/MZ-800) — e valida il settore di boot confrontando la firma "IPLPRO" anziche presumere una macchina fissa. E questo che permette a una singola build di TZFS di avviare i set di dischi di tutte e tre le macchine: il byte del machine id seleziona il comportamento di caricamento/esecuzione, e la corrispondenza della firma e il test go/no-go per "questo e un disco avviabile". Un settore che non porta ne un id riconosciuto ne la firma viene rifiutato e il controllo torna al prompt di TZFS.
Alcuni OS su disco — in particolare CP/M dell'MZ-800 — caricano il loro primo stadio sotto l'indirizzo
Passaggio del controllo con BC = 0200H
1000H, nella regione che normalmente contiene l'area di lavoro del monitor e la DRAM bassa. Prima di cedere il controllo, GETBOOTDSK pre-pagina il blocco 7 della DRAM in 0000H-0FFFH, cosi che il programma caricato veda li DRAM nativa in lettura/scrittura anziche l'immagine del monitor. Questo rispecchia l'IPL nativo della macchina, che smappa la boot ROM ed espone la DRAM prima che il programma caricato inizi a essere eseguito, ed e la stessa correzione di aliasing della RAM bassa applicata in generale sul picoZ80 (mappatura di 0000H-0FFFH dal bank 7 sotto TZFS), cosi che un programma che esegue un LDIR del codice nella RAM bassa e poi cambia modalita video veda la stessa memoria sia sul percorso nativo sia su quello TZFS.
L'IPL nativo
Domare il clock 8253 (SORES) prima del JP (HL)
9Z-504M cede il controllo al programma caricato con la coppia di registri BC = 0200H — un loader di secondo stadio si affida a questo valore (un conteggio di settori da 512 byte / parametro di lettura della directory) per pilotare la propria lettura della directory. GETBOOTDSK riproduce il passaggio esattamente: imposta BC = 0200H immediatamente prima del JP (HL) che trasferisce il controllo al primo stadio appena caricato, cosi che un loader che legge la propria directory usando il valore che trova in BC si comporti in modo identico sotto TZFS. Sbagliare questo fa la differenza tra un disco che si avvia e uno che si blocca su "no system file" perche il suo loader ha letto il numero sbagliato di settori.
Il timer a intervalli programmabile 8253 dello Sharp genera un interrupt periodico. Un loader di disco tipicamente riabilita gli interrupt (
Eseguire l'OS: TZMM_DSKLOAD / TZMM_DSKRUN
EI) presto nel proprio avvio, e se l'8253 e ancora in esecuzione libera alla sua frequenza nativa il conseguente flusso di interrupt RST 38H puo inondare lo Z80 e interrompere il loader prima che finisca. L'IPL nativo evita questo nella sua routine SORES (sound reset); GETBOOTDSK la rispecchia. Immediatamente prima del passaggio con JP (HL):
- Riprogramma il counter 2 dell'8253 a circa 1 Hz, cosi che la sorgente di interrupt scandisca lentamente anziche alla sua frequenza nativa, e
- Maschera il bit 2 della porta C dell'8255 (PC2), il gate che lascia arrivare l'uscita del counter alla linea di interrupt.
EI anticipato nel loader CP/M lasciava in precedenza che un counter a esecuzione rapida lo interrompesse a morte prima che potesse leggere il proprio system file.
Due modalita di gestione della memoria dedicate portano il boot fino a un OS in esecuzione. Sotto il firmware picoZ80, TZMM_DSKLOAD e TZMM_DSKRUN caricano e poi eseguono un OS avviato da floppy nella DRAM nativa del block-0 della macchina — esattamente il layout di memoria che userebbe l'IPL nativo della macchina — anziche in un bank SRAM di TZFS.
Tornare a TZFS al reset hardware
DSKREAD di TZFS trasmette in streaming i settori di boot in quella DRAM; sull'MZ-800 questo e agevolato dal fetch handler di accelerazione hardware FDC MZ1E05_IO_A10Toggle dell'MZ-1E05, che effettua l'OR della linea DRQ dell'FDC con il bit di indirizzo A10 a 0xF3FE / 0xF7FE, cosi che DSKREAD possa trasmettere in streaming un settore di boot sull'MZ-800 esattamente come gia fa sull'MZ-80A. Una volta che i settori sono nella DRAM nativa, viene selezionata TZMM_DSKRUN e il controllo viene trasferito, cosi che l'OS giri contro la memoria reale del block-0 con il monitor e la User ROM di TZFS fuori dai piedi.
Poiche la ROM e la RAM del block-0 fanno alias della stessa PSRAM sul picoZ80, un OS in esecuzione sotto
TZMM_DSKRUN sovrascrive le immagini del monitor block-0 e della User ROM di TZFS man mano che usa la memoria bassa. Quando si preme l'interruttore /RESET hardware, il percorso di reset-restore del firmware ricarica il monitor block-0 intatto piu la UROM di TZFS e poi esegue un cold-boot di TZFS, cosi che l'interruttore di reset riporti l'utente al prompt di TZFS anziche precipitare nel nudo monitor 1Z-013A. Due dettagli del picoZ80 mantengono il video corretto attraverso questa transizione: il tracciamento del cgWindow dell'MZ-800 consente a un OS in modalita MZ-800 che carica un font PCG (tramite IN 0xE0) di raggiungere la vera CG-ROM / CG-RAM sotto TZFS — correggendo il testo confuso del disk-BASIC senza toccare giochi nativi come Flappy — e il percorso di reset riesegue initVideoText una volta rilasciato /RESET (dopo un ritardo di assestamento di ~10 ms perche il GDG / 8255 a bordo completino il proprio reset hardware), cosi che il GDG effettui un nuovo rescan e la sincronizzazione HBLK del monitor si completi in modo pulito.
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
Setup e build automatizzati (consigliato)
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.
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
Compilazione (manuale / FusionX)
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.
# 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/ |