Sistema de archivos tranZPUter (TZFS) -- Guia del desarrollador

Guia del desarrollador TZFS

Esta guia es una presentacion detallada del codigo fuente y el entorno de desarrollo del TZFS (tranZPUter Filing System). Explica conceptos de lenguaje ensamblador Z80, examina cada modulo fuente, documenta la arquitectura de conmutacion de bancos TZMM y muestra como agregar nuevos comandos, modificar modulos existentes y portar TZFS a nuevas plataformas hardware.

Para la arquitectura hardware consulte la Guia tecnica. Para el uso diario consulte el Manual del usuario.

Introduccion al ensamblador Z80

Registro	Tamano	Rol
A	8 bits	Acumulador – registro principal para operaciones aritmeticas, logicas y E/S.
B, C	8 bits	Uso general. BC forma un par de 16 bits.
H, L	8 bits	Uso general. HL es el puntero de memoria principal de 16 bits.
IX, IY	16 bits	Registros indice – para direccionamiento base+desplazamiento.
SP	16 bits	Stack Pointer.
PC	16 bits	Program Counter.

Arbol de fuentes

Ruta	Contenido
`asm/tzfs.asm`	Bank 0: punto de entrada, despachador de comandos, tablas de salto
`asm/tzfs_bank2.asm`	Bank 1: mensajes, ayuda, rutinas de impresion, conversion Sharp/ASCII
`asm/tzfs_bank3.asm`	Bank 2: utilidades de memoria, E/S, compensacion de cinta, comandos CPU/emulacion
`asm/tzfs_bank4.asm`	Bank 3: ensamblador y desensamblador Z80 completos (ocupa 52 KB)
`asm/include/tzfs_definitions.asm`	Constantes de configuracion y definiciones de puertos E/S

Conmutacion de bancos en detalle

Modo TZMM	Valor	0xE800-0xEFFF	0xF000-0xFFFF	Usado por
TZMM_TZFS	0x22	Nucleo TZFS (bank 0)	Nucleo TZFS (bank 0)	Operacion normal
TZMM_TZFS2	0x23	Nucleo TZFS (bank 0)	tzfs_bank2 (bank 1)	Ayuda, mensajes
TZMM_TZFS3	0x24	Nucleo TZFS (bank 0)	tzfs_bank3 (bank 2)	Utilidades de memoria
TZMM_TZFS4	0x25	–	tzfs_bank4 (bank 3)	Ensamblador/desensamblador

Recorrido de modulos

tzfs.asm -- Despachador de comandos (Bank 0)

Punto de entrada para todas las funcionalidades TZFS. Contiene tabla de salto externa, stubs inter-banco, tabla de comandos y bucle del despachador.

tzfs_bank2.asm -- Mensajes y ayuda (Bank 1)

Toda la salida de texto: conversion de juego de caracteres, impresion formateada, visualizacion de nombres de archivo y pantalla de ayuda.

tzfs_bank3.asm -- Utilidades (Bank 2)

Edicion de memoria, volcado hex, copia de bloques, relleno, acceso a puertos E/S, compensacion de cinta, control de emulacion y conmutacion de CPU.

tzfs_bank4.asm -- Ensamblador / Desensamblador (Bank 3)

Ensamblador y desensamblador Z80 interactivos completos que utilizan 52 KB.

Agregar un nuevo comando de monitor

Escribir el manejador en el archivo de banco apropiado.

Agregar un stub con prefijo ? en tzfs.asm.

Agregar una entrada a CMDTABLE en tzfs.asm.

Agregar el texto de ayuda a HELPSCR en tzfs_bank2.asm.

Ejecutar ./build.sh.

Entorno de compilacion

El build de TZFS usa el ensamblador Z80 GLASS (incluido en el repositorio) y el script global de compilacion de FusionX. Solo se necesita un entorno de ejecucion Java y git para compilar los componentes de ensamblado Z80. La forma recomendada de compilar es el script de instalacion automatizado para su plataforma (vease Instalacion y build automatizados mas abajo); los pasos manuales y de FusionX que siguen son para usuarios avanzados y recompilaciones parciales. Para un build completo que incluya los modulos del kernel, los bitstreams CPLD y la imagen completa de Linux, consulte la Guia del Desarrollador FusionX -- Configuracion del entorno de desarrollo.

Requisitos previos

# 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

Instalacion y build automatizados (recomendado)

La forma recomendada de compilar TZFS es el script de instalacion autonomo para su plataforma. Instala los prerrequisitos (Java para el ensamblador Z80 GLASS, mas git/perl/coreutils; en Windows, Git Bash + Java), clona el repositorio, obtiene el paquete de contenido y puede compilar las imagenes ROM, todo de forma interactiva, con valores por defecto sensatos que puede aceptar pulsando Enter. Copie unicamente el archivo correspondiente a su plataforma y ejecutelo.

macOS / Linux / WSL — setup_TZFS.sh

chmod +x setup_TZFS.sh
./setup_TZFS.sh

El script instala Java (que ejecuta el ensamblador GLASS, tools/glass-0.5.1.jar), una cadena de herramientas C + make (para compilar el submodulo cpmtools), perl y git; en macOS tambien instala GNU coreutils y bash 4, agregandolos al PATH mediante un tzfs_env.sh generado. Cuando falta, obtiene el paquete de contenido TZFS_Files.zip (~110 MB de contenido MZF/DSK/CPM/CAS/BAS/BASIC).

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

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

El script de Windows usa winget para instalar Git for Windows (que proporciona bash, coreutils, perl y curl) y el Temurin 17 JRE (Java), clona el repositorio, obtiene el paquete de contenido y ejecuta ./build.sh a traves de Git Bash. Se incluye un tools\cpmcp.exe precompilado, por lo que no se requiere compilador C en Windows.

Preguntas que hace el instalador, y que hacer. Cada solicitud tiene un valor por defecto seguro entre corchetes; la letra en mayuscula es el valor por defecto, asi que pulsar Enter lo acepta.

macOS / Linux / WSL (setup_TZFS.sh):

Solicitud	Por defecto	Que hacer
`Install now? [Y/n]` (para paquetes que falten)	Si	Enter: instala los prerrequisitos que faltan; puede pedir su contrasena de `sudo`.
`Repo URL [https://git.eaw.app/eaw/TZFS.git]`	repo publico	Enter para el repo publico, o pegue otra URL (privada).
`Install directory [~/TZFS]`	`~/TZFS`	Enter para `~/TZFS`, o escriba una ruta.
`Download and install them now? [Y/n]` (paquete de contenido)	Si	Enter para obtener el contenido MZF/DSK/CPM/CAS/BAS/BASIC necesario para un build completo.
`Run the build now (./build.sh …)? [Y/n]`	Si	Enter para compilar de inmediato (verifica el entorno).

Windows (setup_TZFS_windows.ps1):

Solicitud	Por defecto	Que hacer
`Repo URL [https://git.eaw.app/eaw/TZFS.git]`	repo publico	Enter para el repo publico, o pegue otra URL.
`TZFS checkout directory [%USERPROFILE%\TZFS]`	`%USERPROFILE%\TZFS`	Enter para el valor por defecto, o escriba una ruta.
`Download and install them … now? [Y/n]` (paquete de contenido)	Si	Enter para obtener el paquete de contenido.
`Build the TZFS firmware now (runs ./build.sh via Git Bash)? [Y/n]`	Si	Enter para compilar de inmediato a traves de Git Bash.

Defina la variable de entorno TZFS_REPO_URL para sustituir la URL del repositorio por defecto sin editar el script.

Salida y recompilacion. Las imagenes ROM se escriben en roms/, por ejemplo tzfs.rom, las variantes FusionX, las ROM del monitor y los binarios de CP/M. Para recompilar mas tarde, entre en el checkout (cd ~/TZFS); en macOS ejecute primero source ./tzfs_env.sh para poner GNU coreutils y bash 4 en el PATH; luego ejecute ./build.sh (o ./build.sh -m para reprocesar tambien las fuentes MZF). En Windows, ejecute ./build.sh desde Git Bash dentro del checkout.

Compilacion (manual / FusionX)

# Build TZFS ROMs for all target machines
./build.sh --tzfs

Consejos de depuracion

Activar salida de depuracion: ENADEBUG EQU 1 en tzfs_definitions.asm.

Sondear puertos E/S con RIO/WIO. Inspeccionar el bloque de variables TZFS: D EC80. Inspeccionar el bloque de servicio K64F: D ED80.

Sitios de referencia

Recurso	Enlace
Pagina del proyecto TZFS	/sharpmz-upgrades-tzfs/
Manual del usuario TZFS	/sharpmz-upgrades-tzfs-usermanual/
Guia tecnica TZFS	/sharpmz-upgrades-tzfs-technicalguide/