rz80 - run Z-80 programs

rz80 takes a Z-80 program in .cmd, .hex or .cas format and runs it until it hits a HALT instruction or a JP/JR that branches to itself (i.e., a trivial infinite loop). Useful for developing or unit testing Z-80 code without the overhead of a GUI emulator for a Z-80 system.

The Z-80 runs in a "bare bones" environment with 64K of RAM and 3 I/O ports:

• $F8 - OUT sends character to standard output
• $EB - IN reads a character from standard input in binary mode
• $EB - OUT sends character to standard output in binary mode

"binary mode" only makes a difference on Windows where it sidesteps CR/LF to LF translation.

A precompiled binary for Windows is included along with the source code which can easily be compiled on Mac and Linux systems. These program loading routines are the same ones used in my TRS-80 Model I/III/4 emulator.

Option Reference

-t	Output a disassembly of each instruction executed. If specified twice the output will include a register dump. Also turns on the -s option.
-a hex	Start with A register loaded with the given hexadecimal value instead of FF. Use it to select different functions in a single program.
-s	Use the slower but known to be 100% accurate Z-80 interpreter. The "fast" Z-80 by default does not emulate the R register and has a (very small) chance of having a bug.
-nostats	Do not output the run-time statistics when done.
-memsame	Stop only when all 64K RAM is filled with the same value thus proving not all options are useful.

An Example

Suppose we have the following Z-80 source code in a file hw.z:

        org     $8000
start:  ld      hl,message
lp:     ld      a,(hl)
        inc     hl
        or      a
        jr      z,done
        out     ($f8),a
        jp      lp
done:   jr      done
message:
        ascii   'Hello, world.',0
        end     start

Assemble it to a /CMD file using zmac:

   zmac hw.z

Run it with:

   rz80 zout/hw.cmd

And you'll see something like:

Hello, world.
looping at $800d
636 cycles 83 instructions
0.002 seconds, 0.337 MHz
7.66 ave. cycle/instruction

Try these commands for a blow-by-blow account of what the Z-80 program is doing.

   rz80 -t zout/hw.cmd
   rz80 -t -t zout/hw.cmd

Future Plans

Make Z-80 code execution even faster.

Detect every possible situation where no more I/O will occur. Professor Turing says this is not possible but that's only on machines with infinite memory so I'm saying there's a chance!

---

George Phillips, October 10, 2022. george -at- 48k.ca