MZ-80A RomDisk — Entwicklerhandbuch

RomDisk Entwicklerhandbuch

Einfuehrung in Z80-Assembler fuer Nicht-Assembler-Programmierer

Quellenbaum

Die Assembler-Quelldateien und ihre Rollen:

Konfiguration: rfs_definitions.asm

; SPI hardware selection — exactly ONE must be 1:
HW_SPI_ENA    EQU 1    ; Hardware SPI on RomDisk v2+ PCB (74HCT595/165 shift registers)
SW_SPI_ENA    EQU 0    ; Software bit-bang SPI via Z80 I/O port bits
PP_SPI_ENA    EQU 0    ; Parallel printer port SPI (v1 boards only)

; Platform options:
FUSIONX_ENA   EQU 1    ; Include tranZPUter FusionX support
KUMA80_ENA    EQU 0    ; Target has Kuma 40/80 upgrade installed
VIDEOMODULE_ENA EQU 0  ; Target has 40/80 column colour video module

; Build target — exactly ONE must be 1:
BUILD_ROMDISK EQU 1    ; Build for the MZ-80A RomDisk card
BUILD_SFD700  EQU 0    ; Build for the SFD-700 floppy interface
BUILD_PICOZ80 EQU 0    ; Build for the picoZ80 board

; Debugging:
ENADEBUG      EQU 0    ; Enable debug output during assembly (1 = enable)

UROMADDR     EQU 0E800H          ; Base of User ROM window
UROMBSTBL    EQU UROMADDR + 020H ; Bank-switch table entry point (0xE820)
RFSJMPTABLE  EQU UROMADDR + 0B0H ; Jump table start (0xE8B0)
FDCROMADDR   EQU 0F000H          ; Floppy AFI ROM address

; Bank control registers (only accessible after coded latch unlock):
BNKCTRLRST   EQU 0EFF8H    ; Read here 16 times to unlock control registers
BNKCTRLDIS   EQU 0EFF9H    ; Read here once to re-lock (disable) control registers
HWSPIDATA    EQU 0EFFBH    ; Hardware SPI data register (read/write)
HWSPISTART   EQU 0EFFCH    ; Hardware SPI start trigger (write to begin transfer)
BNKSELMROM   EQU 0EFFDh    ; Monitor ROM bank select register
BNKSELUSER   EQU 0EFFEh    ; User ROM bank select register
BNKCTRL      EQU 0EFFFH    ; Bank control register (read/write)

BELL    EQU 007H    ; Terminal bell
CR      EQU 00DH    ; Carriage return
LF      EQU 00AH    ; Line feed
CS      EQU 00CH    ; Clear screen (FF)
SPACE   EQU 020H    ; ASCII space
DELETE  EQU 07FH    ; Delete key

Bank-Switching im Detail

; One command table entry:
;
;   DB  FLAGS          ; 1 byte: END|MATCH|BANK[5:3]|SIZE[2:0]
;   DB  "COMMAND"      ; SIZE bytes: the command string (no null terminator)
;   DW  HANDLER_ADDR   ; 2 bytes: address of the handler routine in the named bank
;
; Flags byte bit fields:
;   Bit 7 = 1: End of table marker (last entry).
;   Bit 6 = 1: Exact match required (entire input must match; no trailing characters).
;   Bits 5:3   Bank number where HANDLER_ADDR lives (0–7 maps to User ROM banks 0–7).
;   Bits 2:0   Length of the command string in bytes (1–7).
;
; Example — the 'D' (dump) command, handler in bank 3, 1-character string:
    DB  000H | 000H | 018H | 001H    ; not-end, not-exact, bank 3 (011<<3=0x18), length 1
    DB  "D"
    DW  DUMPX

Modul-Durchgaenge

SPI-Treiber: Hardware vs. Software

HW_SPI_ENA   EQU 1    ; 74HCT595/74HCT165 hardware shift registers on RomDisk v2+ PCB
SW_SPI_ENA   EQU 0    ; Software bit-bang SPI using the RomDisk v2+ I/O port bits
PP_SPI_ENA   EQU 0    ; Software bit-bang SPI via the Sharp MZ-80A parallel printer port

Einen neuen Monitor-Befehl hinzufuegen

Schritt 1: Handler in rfs_bank3.asm schreiben

; In rfs_bank3.asm (bank 3, memory utilities):
PEEK:   CALL  HLHEX              ; Parse 4-digit hex address from input buffer into HL
        LD    A,(HL)              ; Read the byte at that address
        CALL  PRTHX              ; Print A as 2 hex digits
        RET

Schritt 2: Befehlstabelleneintrag in rfs.asm hinzufuegen

; In rfs.asm, within the CMDTABLE block (inside IF BUILD_ROMDISK+BUILD_PICOZ80 = 1):
;
; Flags byte: not-end (bit7=0), not-exact (bit6=0),
;             bank 3 (bits5:3 = 011 = 0x18), length 4 (bits2:0 = 100 = 0x04)
    DB  000H | 000H | 018H | 004H
    DB  "PEEK"
    DW  PEEK

Schritt 3: Hilfetext in rfs_bank6.asm hinzufuegen

; In rfs_bank6.asm, within the HELPSCR block (before the 000H terminator):
    DB  "PEEKXXXX - read byte at XXXX",    00DH

Schritt 4: Kompilieren

cd /dvlp/Projects/MZ80A_RFS/software/RFS
./build.sh

Neue Hardware-Unterstuetzung hinzufuegen

PP2_SPI_ENA  EQU 0    ; Second parallel port SPI variant (custom hardware)

; Guard: only one SPI flag may be set at a time.
; GLASS does not have a built-in ASSERT directive, so encode this as a build-time
; value check. If more than one flag is set, the total sum exceeds 1 and the error
; manifests as wrong code being assembled into the SPI driver functions.
; (Document this constraint prominently in the comment block above SDINIT.)

SPIOUT:     IF HW_SPI_ENA = 1
              ; Hardware SPI path (existing code)
              LD    (HWSPIDATA),A
              LD    (HWSPISTART),A
              RET
            ELSE
              IF SW_SPI_ENA = 1
                ; Software bit-bang path (existing code)
              ELSE
                IF PP2_SPI_ENA = 1
                  ; New PP2 path:
                  ; (implement bit-bang for the new port layout here)
                  RET
                ELSE
                  ; Original PP_SPI_ENA (centronics) path (existing code)
                ENDIF
              ENDIF
            ENDIF

Debugging-Tipps

Referenzseiten