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.

Arrancar discos flexibles desde TZFS (GETBOOTDSK)

A partir de TZFS v1.8.3, TZFS puede arrancar un disco flexible de MZ-80A / MZ-700 / MZ-800 — incluido CP/M de MZ-800 — directamente desde dentro del sistema de archivos, y regresar a TZFS con el interruptor RESET del hardware una vez que el sistema operativo arrancado desde disquete ha terminado de ejecutarse. La rutina que hace esto es GETBOOTDSK. Reimplementa, en la ventana de la User ROM, el comportamiento del propio IPL de la maquina (el IPL de disco nativo 9Z-504M) con la fidelidad suficiente para que un cargador de arranque de segunda etapa en el disco no pueda distinguir que se esta ejecutando bajo TZFS en lugar de bajo el monitor de fabrica. Esta seccion documenta el detalle a nivel de desarrollador de esa rutina y los modos de memoria que la soportan.

Aceptacion del ID de maquina y deteccion de IPLPRO

El primer sector de un disco Sharp arrancable lleva un identificador de maquina y la firma ASCII "IPLPRO". TZFS aceptaba anteriormente un unico id de maquina fijo; GETBOOTDSK ahora acepta cualquier id de maquina Sharp valido — 01 (MZ-2000), 02 (MZ-80A/MZ-80K) y 03 (MZ-700/MZ-800) — y valida el sector de arranque comparando la firma "IPLPRO" en lugar de asumir una maquina fija. Esto es lo que permite que un mismo build de TZFS arranque los conjuntos de discos de las tres maquinas: el byte del id de maquina selecciona el comportamiento de carga/ejecucion, y la coincidencia de la firma es la prueba de si/no para "esto es un disco arrancable". Un sector que no lleva ni un id reconocido ni la firma se rechaza y el control regresa al prompt de TZFS.

Prepaginacion del bloque 7 para SO que cargan por debajo de 1000H

Algunos SO de disco — CP/M de MZ-800 en particular — cargan su primera etapa por debajo de la direccion 1000H, en la region que normalmente contiene el area de trabajo del monitor y la DRAM baja. Antes de ceder el control, GETBOOTDSK prepagina el bloque 7 de DRAM en 0000H-0FFFH para que el programa cargado vea alli DRAM nativa de lectura/escritura en lugar de la imagen del monitor. Esto refleja el propio IPL de la maquina, que desmapea la ROM de arranque y expone la DRAM antes de que el programa cargado comience a ejecutarse, y es la misma correccion de aliasing de RAM baja aplicada de forma general en la picoZ80 (mapear 0000H-0FFFH desde el bank 7 bajo TZFS) de modo que un programa que hace LDIR de codigo a la RAM baja y luego cambia el modo de video vea memoria identica tanto en la ruta nativa como en la de TZFS.

Traspaso con BC = 0200H

El IPL nativo 9Z-504M cede el control al programa cargado con el par de registros BC = 0200H — un cargador de segunda etapa depende de este valor (un contador de sectores de 512 bytes / parametro de lectura de directorio) para gobernar su propia lectura de directorio. GETBOOTDSK reproduce el traspaso con exactitud: fija BC = 0200H inmediatamente antes del JP (HL) que transfiere el control a la primera etapa recien cargada, de modo que un cargador que lee su directorio usando el valor que encuentra en BC se comporta de forma identica bajo TZFS. Equivocarse en esto es la diferencia entre un disco que arranca y uno que se atasca en "no system file" porque su cargador leyo el numero de sectores equivocado.

Domar el reloj 8253 (SORES) antes del JP (HL)

El temporizador de intervalo programable 8253 del Sharp genera una interrupcion periodica. Un cargador de disco tipicamente reactiva las interrupciones (EI) al principio de su propio arranque, y si el 8253 sigue funcionando libremente a su frecuencia nativa el flujo resultante de interrupciones RST 38H puede inundar al Z80 y abortar el cargador antes de que termine. El IPL nativo evita esto en su rutina SORES (sound reset); GETBOOTDSK la refleja. Inmediatamente antes del traspaso con JP (HL):

Reprograma el contador 2 del 8253 a aproximadamente 1 Hz, de modo que la fuente de interrupcion pulse lentamente en lugar de a su frecuencia nativa, y

Enmascara el bit 2 del puerto C del 8255 (PC2), la compuerta que deja que la salida del contador alcance la linea de interrupcion.

Con el contador ralentizado y la compuerta enmascarada, un cargador que activa las interrupciones pronto no puede ser desbordado. Esta es la correccion especifica para el fallo "P-CP/M80 → No system file", donde un EI temprano en el cargador de CP/M dejaba anteriormente que un contador de marcha rapida lo interrumpiera hasta matarlo antes de que pudiera leer su archivo de sistema.

Ejecutar el SO: TZMM_DSKLOAD / TZMM_DSKRUN

Dos modos de gestion de memoria dedicados llevan el arranque hasta un SO en ejecucion. Bajo el firmware de la picoZ80, TZMM_DSKLOAD y TZMM_DSKRUN cargan y luego ejecutan un SO arrancado desde disquete en la DRAM nativa del bloque 0 de la maquina — exactamente la disposicion de memoria que usaria el propio IPL de la maquina — en lugar de en un banco SRAM de TZFS. El DSKREAD de TZFS transmite los sectores de arranque a esa DRAM; en la MZ-800 esto se ayuda con el manejador de captacion de aceleracion hardware del FDC MZ1E05_IO_A10Toggle de la MZ-1E05, que hace un OR de la linea DRQ del FDC con el bit de direccion A10 en 0xF3FE / 0xF7FE para que DSKREAD pueda transmitir un sector de arranque en la MZ-800 exactamente como ya lo hace en la MZ-80A. Una vez que los sectores estan en la DRAM nativa, se selecciona TZMM_DSKRUN y se transfiere el control, de modo que el SO se ejecuta contra la memoria real del bloque 0 con el monitor y la User ROM de TZFS apartados.

Regresar a TZFS con el reset del hardware

Como la ROM y la RAM del bloque 0 hacen alias de la misma PSRAM en la picoZ80, un SO que se ejecuta bajo TZMM_DSKRUN sobrescribe las imagenes del monitor del bloque 0 y de la User ROM de TZFS a medida que usa la memoria baja. Cuando se pulsa el interruptor /RESET del hardware, la ruta de restauracion del reset del firmware recarga el monitor prístino del bloque 0 mas la UROM de TZFS y luego arranca en frio TZFS, de modo que el interruptor de reset devuelve al usuario al prompt de TZFS en lugar de caer al monitor 1Z-013A desnudo. Dos detalles de la picoZ80 mantienen el video correcto a lo largo de esta transicion: el seguimiento del cgWindow de la MZ-800 permite que un SO en modo MZ-800 que carga una fuente PCG (via IN 0xE0) alcance la CG-ROM / CG-RAM real bajo TZFS — corrigiendo el texto ininteligible de disk-BASIC mientras deja intactos juegos nativos como Flappy — y la ruta de reset vuelve a ejecutar initVideoText una vez que /RESET se libera (tras un retardo de asentamiento de ~10 ms para que el GDG / 8255 integrados terminen su reset hardware) de modo que el GDG reescanea y la sincronizacion HBLK del monitor se completa limpiamente.

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/