Systeme de fichiers tranZPUter (TZFS) -- Guide du developpeur

Guide du developpeur TZFS

Ce guide est une presentation detaillee du code source et de l'environnement de developpement du TZFS (tranZPUter Filing System). Il explique les concepts du langage assembleur Z80, parcourt chaque module source, documente l'architecture de commutation de banques TZMM et montre comment ajouter de nouvelles commandes, modifier des modules existants et porter TZFS sur de nouvelles plateformes materielles.
Pour les details de l'architecture materielle, consultez le Guide technique. Pour l'utilisation quotidienne, consultez le Manuel utilisateur.

Introduction a l'assembleur Z80

Registres
Registre Taille Role
A 8 bits Accumulateur – registre principal pour l’arithmetique, la logique et les operations E/S.
B, C 8 bits Usage general. BC forme une paire 16 bits, souvent utilisee comme compteur de boucle.
D, E 8 bits Usage general. DE est une paire 16 bits, souvent utilisee comme pointeur.
H, L 8 bits Usage general. HL est le pointeur memoire principal 16 bits.
IX, IY 16 bits Registres d’index – pour l’adressage base+deplacement.
SP 16 bits Pointeur de pile.
PC 16 bits Compteur de programme.
F 8 bits Registre de drapeaux – Z, C, S, P/V.

Instructions cles
  • LD dest, src -- Charger (copier) des donnees.
  • CALL addr -- Appeler un sous-programme.
  • RET -- Retourner d'un sous-programme.
  • JP addr -- Saut inconditionnel.
  • DJNZ offset -- Decrementer B et sauter si non zero.
  • IN A, (port) / OUT (port), A -- Lire/ecrire un port E/S.

Arborescence des sources

Chemin Contenu
asm/tzfs.asm Bank 0 : point d’entree, dispatcheur de commandes, tables de saut
asm/tzfs_bank2.asm Bank 1 : messages, aide, routines d’impression, conversion Sharp/ASCII
asm/tzfs_bank3.asm Bank 2 : utilitaires memoire, E/S, compensation bande, commandes CPU/emulation
asm/tzfs_bank4.asm Bank 3 : assembleur et desassembleur Z80 complets (occupe 52 Ko)
asm/include/tzfs_definitions.asm Constantes de configuration et definitions de ports E/S
asm/include/tzfs_svcstruct.asm Definitions des commandes et structures de service K64F
build.sh Script de compilation principal

Commutation de banques en detail

Mode TZMM Valeur 0xE800-0xEFFF 0xF000-0xFFFF Utilise par
TZMM_TZFS 0x22 Noyau TZFS (bank 0) Noyau TZFS (bank 0) Operation normale
TZMM_TZFS2 0x23 Noyau TZFS (bank 0) tzfs_bank2 (bank 1) Aide, messages
TZMM_TZFS3 0x24 Noyau TZFS (bank 0) tzfs_bank3 (bank 2) Utilitaires memoire
TZMM_TZFS4 0x25 – tzfs_bank4 (bank 3) Assembleur/desassembleur
Dans les modes TZMM_TZFS, TZMM_TZFS2 et TZMM_TZFS3, la fenetre 0xE800-0xEFFF mappe toujours sur le meme code noyau TZFS (bank 0). Seule la fenetre 0xF000-0xFFFF change. Les stubs de commutation de banques dans tzfs.asm sont toujours accessibles.

Parcours des modules

tzfs.asm -- Dispatcheur de commandes (Bank 0)
Point d'entree pour toutes les fonctionnalites TZFS. Contient la table de saut externe, les stubs inter-banques, la table de commandes (CMDTABLE) et la boucle du dispatcheur.

tzfs_bank2.asm -- Messages et aide (Bank 1)
Toute la sortie texte : conversion de jeu de caracteres (PRINTASCII), impression formatee (PRINTMSG), affichage de noms de fichiers (PRTFN) et ecran d'aide (HELPSCR).

tzfs_bank3.asm -- Utilitaires (Bank 2)
Edition memoire, vidage hex, copie de blocs, remplissage, acces ports E/S, compensation bande, controle d'emulation hardware et commutation CPU.

tzfs_bank4.asm -- Assembleur / Desassembleur (Bank 3)
Assembleur et desassembleur Z80 interactifs complets utilisant 52 Ko (0x1200-0xCFFF + 0xF000-0xFFFF).

Ajouter une nouvelle commande moniteur

  1. Ecrire le gestionnaire dans le fichier de banque appropriate.
  2. Ajouter un stub ?-prefixe dans tzfs.asm.
  3. Ajouter une entree a CMDTABLE dans tzfs.asm.
  4. Ajouter le texte d'aide a HELPSCR dans tzfs_bank2.asm.
  5. Executer ./build.sh.

Conseils de debogage

Activer la sortie de debogage : ENADEBUG EQU 1 dans tzfs_definitions.asm.
Sonder les ports E/S avec RIO/WIO. Inspecter le bloc de variables TZFS : D EC80. Inspecter le bloc de service K64F : D ED80.

Environnement de compilation

La compilation de TZFS utilise l'assembleur Z80 GLASS (fourni dans le depot) et le script de build global FusionX. Seuls un environnement d'execution Java et git sont necessaires pour compiler les composants en assembleur Z80. La methode recommandee est le script de configuration automatise propre a votre plateforme (voir Configuration et build automatises ci-dessous) ; les etapes de build manuelles et FusionX qui suivent s'adressent aux utilisateurs avances et aux rebuilds partiels.

Configuration et build automatises (recommande)
La methode recommandee pour compiler TZFS est le script de configuration autonome propre a votre plateforme. Il installe les prerequis (Java pour l'assembleur Z80 GLASS, ainsi que git/perl/coreutils ; sous Windows, Git Bash + Java), clone le depot, recupere le bundle de contenu et peut compiler les images ROM — le tout de maniere interactive, avec des valeurs par defaut sensees que vous pouvez accepter en appuyant sur Entree. Copiez uniquement le fichier correspondant a votre plateforme et executez-le.

macOS / Linux / WSL — setup_TZFS.sh

chmod +x setup_TZFS.sh
./setup_TZFS.sh
Le script installe Java (qui execute l'assembleur GLASS, tools/glass-0.5.1.jar), une chaine d'outils C + make (pour compiler le sous-module cpmtools), perl et git ; sous macOS il installe egalement GNU coreutils et bash 4, en les ajoutant au PATH via un fichier tzfs_env.sh genere. Lorsqu'il est absent, il recupere le bundle de contenu TZFS_Files.zip (~110 Mo de contenu MZF/DSK/CPM/CAS/BAS/BASIC).

Windows 10 / 11 — setup_TZFS_windows.ps1 (Git Bash natif, sans WSL). Depuis PowerShell :

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_TZFS_windows.ps1
Le script Windows utilise winget pour installer Git for Windows (qui fournit bash, coreutils, perl et curl) et la Temurin 17 JRE (Java), clone le depot, recupere le bundle de contenu et execute ./build.sh via Git Bash. Un tools\cpmcp.exe precompile est fourni, donc aucun compilateur C n'est requis sous Windows.

Questions posees par la configuration, et que faire. Chaque invite a une valeur par defaut securisee entre crochets — la lettre majuscule est la valeur par defaut, donc appuyer sur Entree l’accepte.

macOS / Linux / WSL (setup_TZFS.sh) :

Invite Defaut Que faire
Install now? [Y/n] (pour les paquets manquants) Oui Entree — installe les prerequis manquants ; peut demander votre mot de passe sudo.
Repo URL [https://git.eaw.app/eaw/TZFS.git] depot public Entree pour le depot public, ou collez une autre URL (privee).
Install directory [~/TZFS] ~/TZFS Entree pour ~/TZFS, ou saisissez un chemin.
Download and install them now? [Y/n] (bundle de contenu) Oui Entree pour recuperer le contenu MZF/DSK/CPM/CAS/BAS/BASIC necessaire a un build complet.
Run the build now (./build.sh …)? [Y/n] Oui Entree pour compiler immediatement (verifie l’environnement).

Windows (setup_TZFS_windows.ps1) :

Invite Defaut Que faire
Repo URL [https://git.eaw.app/eaw/TZFS.git] depot public Entree pour le depot public, ou collez une autre URL.
TZFS checkout directory [%USERPROFILE%\TZFS] %USERPROFILE%\TZFS Entree pour le defaut, ou saisissez un chemin.
Download and install them … now? [Y/n] (bundle de contenu) Oui Entree pour recuperer le bundle de contenu.
Build the TZFS firmware now (runs ./build.sh via Git Bash)? [Y/n] Oui Entree pour compiler immediatement via Git Bash.
Definissez la variable d'environnement TZFS_REPO_URL pour remplacer l'URL de depot par defaut sans editer le script.
Sortie et recompilation. Les images ROM sont ecrites dans roms/ — par exemple tzfs.rom, les variantes FusionX, les ROMs moniteur et les binaires CP/M. Pour recompiler ensuite, placez-vous dans la copie de travail (cd ~/TZFS) ; sous macOS, executez d'abord source ./tzfs_env.sh pour ajouter GNU coreutils et bash 4 au PATH ; puis lancez ./build.sh (ou ./build.sh -m pour retraiter aussi les sources MZF). Sous Windows, executez ./build.sh depuis Git Bash dans la copie de travail.

Compilation (manuelle / 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

Sites de reference

Ressource Lien
Page du projet TZFS /sharpmz-upgrades-tzfs/
Manuel utilisateur TZFS /sharpmz-upgrades-tzfs-usermanual/
Guide technique TZFS /sharpmz-upgrades-tzfs-technicalguide/
Guide du developpeur FusionX /tranzputer-fusionx-developersguide/