tranZPUter-Dateisystem (TZFS) -- Entwicklerhandbuch

TZFS Entwicklerhandbuch

Dieses Handbuch ist eine detaillierte Durchgehung des TZFS-Quellcodes (tranZPUter Filing System) und der Entwicklungsumgebung. Es erklaert Z80-Assembler-Konzepte fuer Entwickler, die moeglicherweise nicht mit der Sprache vertraut sind, fuehrt durch jedes Quellmodul, dokumentiert die TZMM-Bank-Switching-Architektur und zeigt, wie neue Befehle hinzugefuegt, vorhandene Module geaendert und TZFS auf neue Hardwareplattformen portiert werden koennen.
Fuer Hardwarearchitektur und Build-System-Details siehe den Technischen Leitfaden. Fuer die benutzerorientierte Bedienung siehe das Benutzerhandbuch.

Einfuehrung in Z80-Assembler fuer Nicht-Assembler-Programmierer

Register
Der Z80 hat keine "Variablen" -- stattdessen hat er einen kleinen Satz von Registern (schnelle Speicherorte innerhalb der CPU):
Register Groesse Rolle
A 8-Bit Akkumulator – das primaere Register fuer Arithmetik, Logik und I/O-Operationen.
B, C 8-Bit Allgemein. BC zusammen bildet ein 16-Bit-Paar, haeufig als Schleifenzaehler verwendet.
D, E 8-Bit Allgemein. DE zusammen ist ein 16-Bit-Paar, haeufig als Quell- oder Zielzeiger.
H, L 8-Bit Allgemein. HL zusammen ist der Haupt-16-Bit-Speicherzeiger.
IX, IY 16-Bit Indexregister – fuer Basis+Offset-Speicheradressierung.
SP 16-Bit Stack Pointer – zeigt auf die Spitze des Aufrufstapels.
PC 16-Bit Program Counter – die Adresse des aktuellen Befehls.
F 8-Bit Flags-Register – Z (Zero), C (Carry), S (Sign), P/V (Parity/Overflow).

Wichtige Befehle
  • LD dest, src -- Laden (kopieren) von Daten.
  • CALL addr -- Unterprogramm aufrufen.
  • RET -- Aus Unterprogramm zurueckkehren.
  • JP addr -- Unbedingter Sprung.
  • DJNZ offset -- B dekrementieren und springen wenn nicht Null.
  • IN A, (port) / OUT (port), A -- I/O-Port lesen/schreiben.
  • PUSH rr / POP rr -- 16-Bit-Registerpaar auf dem Stack speichern/wiederherstellen.

GLASS-Assembler-Syntax
  • Kommentare beginnen mit ;.
  • EQU definiert eine Konstante: MMCFG EQU 060H.
  • DB (Define Byte) fuegt Rohbytes ein.
  • DW (Define Word) fuegt 16-Bit Little-Endian-Werte ein.
  • ORG addr setzt den Assemblierungsursprung.
  • IF / ENDIF bedingte Assemblierung.

Quellbaum

Pfad Inhalt
asm/tzfs.asm Bank 0: Einstiegspunkt, Initialisierung, Befehlsdispatcher, Sprungtabellen
asm/tzfs_bank2.asm Bank 1: Nachrichten, Hilfebildschirm, Druckroutinen, Sharp/ASCII-Konvertierung
asm/tzfs_bank3.asm Bank 2: Speicher-Utilities, I/O-Port R/W, Tape-Kompensation, CPU/Emulationsbefehle
asm/tzfs_bank4.asm Bank 3: Vollstaendiger Z80-Assembler und -Disassembler (belegt 52 KB)
asm/include/ Gemeinsame Definitionen und Konfigurationsdateien
asm/include/tzfs_definitions.asm Alle Konfigurationskonstanten und I/O-Port-Definitionen
asm/include/tzfs_svcstruct.asm K64F-Servicebefehl- und Strukturdefinitionen
build.sh Top-Level-Build-Skript
tools/ Build-Werkzeuge einschliesslich glass.jar

Konfiguration: tzfs_definitions.asm

Build-Ziel-Flags 
BUILD_FUSIONX EQU 0    ; 1 = running on tranZPUter FusionX hardware
BUILD_PICOZ80 EQU 1    ; 1 = running on picoZ80 board
ENADEBUG      EQU 0    ; 1 = enable additional diagnostic output

Adresskonstanten 
UROMADDR    EQU 0E800H   ; Base address of the TZFS entry point
TZVARMEM    EQU 0EC80H   ; TZFS variable block
TZSVCMEM    EQU 0ED80H   ; K64F service communication block
BANKRAMADDR EQU 02000H   ; Base address for bank4 assembler/disassembler tables

TZMM-Modus-Konstanten 
MMCFG       EQU 060H     ; I/O port for memory management config register
TZMM_TZFS   EQU 022H     ; Mode 0x22: bank 0 — main TZFS code
TZMM_TZFS2  EQU 023H     ; Mode 0x23: bank 1 — tzfs_bank2
TZMM_TZFS3  EQU 024H     ; Mode 0x24: bank 2 — tzfs_bank3
TZMM_TZFS4  EQU 025H     ; Mode 0x25: bank 3 — tzfs_bank4

Bank-Switching im Detail

Bank-Switching ist der zentrale Architekturmechanismus von TZFS. Das native Monitor-ROM belegt 0x0000-0xDFFF. Das User-ROM-Fenster bei 0xE800-0xEFFF gibt TZFS nur 2 KB permanent sichtbaren Adressraum -- viel zu klein fuer das gesamte System. Banking ermoeglicht es TZFS, verschiedene Code-Module im selben Adressbereich bei Bedarf darzustellen.
TZMM-Modus Wert 0xE800-0xEFFF 0xF000-0xFFFF Verwendet von
TZMM_TZFS 0x22 TZFS-Kern (Bank 0) TZFS-Kern (Bank 0) Normalbetrieb
TZMM_TZFS2 0x23 TZFS-Kern (Bank 0) tzfs_bank2 (Bank 1) Hilfe, Nachrichten
TZMM_TZFS3 0x24 TZFS-Kern (Bank 0) tzfs_bank3 (Bank 2) Speicher-Utilities, Emulation
TZMM_TZFS4 0x25 – tzfs_bank4 (Bank 3) Assembler/Disassembler

Befehlstabellenformat (tzfs.asm) 
; One TZFS command table entry:
;   DB  FLAGS          ; 1 byte: END|MATCH|BANK[5:3]|SIZE[2:0]
;   DB  "COMMAND"      ; SIZE bytes: the command string
;   DW  HANDLER_ADDR   ; 2 bytes: handler routine address

Sprungtabellen

Externe Sprungtabelle bei 0xE880 (TZFSJMPTABLE) 
CMT_RDINF  EQU UROMADDR+80H  ; 0xE880
CMT_RDDATA EQU UROMADDR+83H  ; 0xE883
CMT_WRINF  EQU UROMADDR+86H  ; 0xE886
CMT_WRDATA EQU UROMADDR+89H  ; 0xE889
CMT_VERIFY EQU UROMADDR+8CH  ; 0xE88C
CMT_DIR    EQU UROMADDR+8FH  ; 0xE88F
CMT_CD     EQU UROMADDR+92H  ; 0xE892
SET_FREQ   EQU UROMADDR+95H  ; 0xE895

Inter-Bank-Funktions-Stubs (?-Praefix)
Jede Funktion, die von einer anderen Bank als der, in der sie sich befindet, aufgerufen werden muss, hat einen entsprechenden ?-praefixierten Stub in tzfs.asm. Der Aufrufer schreibt einfach CALL ?PRINTMSG und der Bank-Switch wird transparent gehandhabt.

Modul-Durchgaenge

tzfs.asm -- Befehlsdispatcher (Bank 0, TZMM_TZFS)
Der Einstiegspunkt fuer alle TZFS-Funktionalitaet. Enthaelt die externe Sprungtabelle, Inter-Bank-Stub-Tabelle, Befehlstabelle (CMDTABLE), Hauptdispatcher-Schleife und Variablenspeicher.

tzfs_bank2.asm -- Nachrichten und Hilfe (Bank 1, TZMM_TZFS2)
Alle benutzerorientierten Textausgaben: Zeichensatzkonvertierung (PRINTASCII), formatierter Nachrichtendruck (PRINTMSG), Dateinamensanzeige (PRTFN) und der Hilfebildschirm (HELPSCR).

tzfs_bank3.asm -- Utilities (Bank 2, TZMM_TZFS3)
Speicherbearbeitung, Hex-Dump, Blockkopie, Fuellen, I/O-Portzugriff, Tape-Kompensation, Hardwareemulationssteuerung, CPU-Umschaltung und Videomodus-Steuerung.

tzfs_bank4.asm -- Assembler / Disassembler (Bank 3, TZMM_TZFS4)
Vollstaendiger interaktiver Z80-Assembler und -Disassembler. Diese Bank ist architektonisch einzigartig: TZMM_TZFS4 bildet Bank 3 ueber den gesamten User-RAM-Bereich (0x1200-0xCFFF) sowie 0xF000-0xFFFF ab, was 52 KB Arbeitsplatz ergibt.

K64F-Serviceaufrufe

; Step 1 — Set command and parameters
LD   A, TZSVC_CMD_LOADFILE
LD   (TZSVCCMD), A

; Step 2 — Signal request to K64F
LD   A, TZSVC_STATUS_REQUEST
LD   (TZSVCRESULT), A
OUT  (SVCREQ), A

; Step 3 — Poll result
WAIT:
    LD   A, (TZSVCRESULT)
    CP   TZSVC_STATUS_REQUEST
    JR   Z, WAIT

; Step 4 — Check result
LD   A, (TZSVCRESULT)
OR   A
JR   NZ, ERROR

Einen neuen Monitorbefehl hinzufuegen

  1. Handler in der passenden Bank-Datei schreiben. Fuer einen Utility-Befehl in tzfs_bank3.asm eine Routine hinzufuegen.
  2. ?-Praefix-Stub in tzfs.asm hinzufuegen im TZFSJMPTABLE-Abschnitt.
  3. Eintrag zu CMDTABLE in tzfs.asm hinzufuegen mit Bank-Index und Handler-Adresse.
  4. Hilfetext zu HELPSCR in tzfs_bank2.asm hinzufuegen.
  5. ./build.sh ausfuehren.

Eine neue Hardwareplattform hinzufuegen

  1. Build-Flag in tzfs_definitions.asm hinzufuegen.
  2. I/O-Port- und TZMM-Modus-Konstanten hinzufuegen.
  3. Bedingte Assemblierungsbloecke im Quellcode hinzufuegen.
  4. K64F-Service-API auf der neuen Plattform implementieren.
  5. build.sh aktualisieren.

Debugging-Tipps

Debug-Ausgabe aktivieren: ENADEBUG EQU 1 in tzfs_definitions.asm setzen.
I/O-Ports direkt mit RIO/WIO pruefen: RIO port liest jeden I/O-Port. WIO port,value schreibt einen Wert.
TZFS-Variablenblock inspizieren: D EC80 fuer den TZVARMEM-Bereich.
K64F-Serviceblock inspizieren: D ED80 fuer den TZSVCMEM-Bereich.
Assemblierten Code mit DASM verifizieren: Nach dem ASM-Befehl sofort DASM addr,endaddr verwenden.

Build-Umgebung

Der TZFS-Build verwendet den GLASS-Z80-Assembler (im Repository enthalten) und das globale FusionX-Build-Skript. Zum Bauen der Z80-Assembler-Komponenten werden nur eine Java-Laufzeitumgebung und git benoetigt. Der empfohlene Weg zum Bauen ist das automatisierte Setup-Skript fuer Ihre Plattform (siehe Automatisiertes Setup und Build unten); die nachfolgenden manuellen und FusionX-Build-Schritte sind fuer fortgeschrittene Benutzer und Teil-Builds gedacht.

Automatisiertes Setup und Build (empfohlen)
Der empfohlene Weg, TZFS zu bauen, ist das in sich geschlossene Setup-Skript fuer Ihre Plattform. Es installiert die Voraussetzungen (Java fuer den GLASS-Z80-Assembler sowie git/perl/coreutils; unter Windows Git Bash + Java), klont das Repository, holt das Inhaltspaket und kann die ROM-Images bauen — alles interaktiv, mit sinnvollen Standardwerten, die Sie durch Druecken von Enter uebernehmen koennen. Kopieren Sie einfach die einzelne Datei fuer Ihre Plattform und fuehren Sie sie aus.

macOS / Linux / WSL — setup_TZFS.sh

chmod +x setup_TZFS.sh
./setup_TZFS.sh
Das Skript installiert Java (das den GLASS-Assembler tools/glass-0.5.1.jar ausfuehrt), eine C-Toolchain + make (um das cpmtools-Submodul zu bauen), perl und git; unter macOS installiert es zusaetzlich GNU coreutils und bash 4 und fuegt sie ueber ein generiertes tzfs_env.sh zum PATH hinzu. Falls nicht vorhanden, holt es das Inhaltspaket TZFS_Files.zip (~110 MB MZF/DSK/CPM/CAS/BAS/BASIC-Inhalte).

Windows 10 / 11 — setup_TZFS_windows.ps1 (natives Git Bash, kein WSL). In PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_TZFS_windows.ps1
Das Windows-Skript verwendet winget, um Git for Windows (das bash, coreutils, perl und curl bereitstellt) und die Temurin 17 JRE (Java) zu installieren, klont das Repository, holt das Inhaltspaket und fuehrt ./build.sh ueber Git Bash aus. Ein vorgefertigtes tools\cpmcp.exe ist enthalten, sodass unter Windows kein C-Compiler erforderlich ist.

Fragen, die das Setup stellt, und was zu tun ist. Jede Eingabeaufforderung hat einen sicheren Standardwert in Klammern — der Grossbuchstabe ist der Standard, sodass Druecken von Enter ihn uebernimmt.

macOS / Linux / WSL (setup_TZFS.sh):

Eingabeaufforderung Standard Was zu tun ist
Install now? [Y/n] (fuer fehlende Pakete) Ja Enter — installiert die fehlenden Voraussetzungen; fragt evtl. nach Ihrem sudo-Passwort.
Repo URL [https://git.eaw.app/eaw/TZFS.git] oeffentliches Repo Enter fuer das oeffentliche Repo oder eine andere (private) URL einfuegen.
Install directory [~/TZFS] ~/TZFS Enter fuer ~/TZFS oder einen Pfad eingeben.
Download and install them now? [Y/n] (Inhaltspaket) Ja Enter, um die fuer einen vollstaendigen Build benoetigten MZF/DSK/CPM/CAS/BAS/BASIC-Inhalte zu holen.
Run the build now (./build.sh …)? [Y/n] Ja Enter, um sofort zu bauen (verifiziert die Umgebung).

Windows (setup_TZFS_windows.ps1):

Eingabeaufforderung Standard Was zu tun ist
Repo URL [https://git.eaw.app/eaw/TZFS.git] oeffentliches Repo Enter fuer das oeffentliche Repo oder eine andere URL einfuegen.
TZFS checkout directory [%USERPROFILE%\TZFS] %USERPROFILE%\TZFS Enter fuer den Standard oder einen Pfad eingeben.
Download and install them … now? [Y/n] (Inhaltspaket) Ja Enter, um das Inhaltspaket zu holen.
Build the TZFS firmware now (runs ./build.sh via Git Bash)? [Y/n] Ja Enter, um sofort ueber Git Bash zu bauen.
Setzen Sie die Umgebungsvariable TZFS_REPO_URL, um die Standard-Repository-URL zu ueberschreiben, ohne das Skript zu bearbeiten.
Ausgabe und Neu-Bauen. ROM-Images werden nach roms/ geschrieben — zum Beispiel tzfs.rom, die FusionX-Varianten, die Monitor-ROMs und die CP/M-Binaerdateien. Um spaeter neu zu bauen, wechseln Sie in den Checkout (cd ~/TZFS); unter macOS fuehren Sie zuerst source ./tzfs_env.sh aus, um GNU coreutils und bash 4 in den PATH zu legen; dann fuehren Sie ./build.sh aus (oder ./build.sh -m, um auch die MZF-Quellen erneut zu verarbeiten). Unter Windows fuehren Sie ./build.sh aus Git Bash im Checkout aus.

Bauen (manuell / FusionX) 
sudo apt install -y default-jre git
git clone https://git.eaw.app/eaw/tzpuFusionX.git
cd tzpuFusionX
git submodule update --init --recursive

./build.sh --tzfs
./build.sh --cpm
./build.sh --all
Ausgabe Beschreibung
software/roms/tzfs_mz80a_fusionx.rom TZFS-Firmware fuer MZ-80A
software/roms/tzfs_mz700_fusionx.rom TZFS-Firmware fuer MZ-700
software/roms/tzfs_mz2000_fusionx.rom TZFS-Firmware fuer MZ-2000
software/roms/cpm223_*.bin CP/M 2.2-Binaerdateien

Referenzseiten

Ressource Link
TZFS-Projektseite /sharpmz-upgrades-tzfs/
TZFS Benutzerhandbuch /sharpmz-upgrades-tzfs-usermanual/
TZFS Technischer Leitfaden /sharpmz-upgrades-tzfs-technicalguide/
FusionX Entwicklerhandbuch /tranzputer-fusionx-developersguide/
GLASS Z80-Assembler Enthalten in tools/glass-0.5.1.jar