                       SIMPLE Z80 MONITOR WITH FORTH
                       -----------------------------

V 0.14, 01-JUN-2013, Bernd Ulmann

What's new
----------
V 0.14a  + Added John Kerr's Z80 disassembler.
         + Added get_word system-call.

Important
---------
 The various disk function mentioned below will NOT WORK on the Z80_mini board
since there is no expansion capability which would be necessary for either the
TTL-based IDE-interface or the 82C55-IDE-implementation!

Introduction
------------

 In September 2011, I built a small Z80 computer thinking of my childhood
when I was socialized with a ZX81, followed by a ZX Spectrum. This particular
system which is described in http://www.vaxman.de/projects/tiny_z80/ consists
currently of a CPU card holding the Z80 CPU itself, 32 kB RAM, 32 kB EPROM,
and a 16550C UART. A second card contains an IDE-controller with a CF-card
adapter.

 Hardware alone is not enough and so I began writing a more or less simple
monitor to be able to actually do something (useful) with this Z80 system.
At first this monitor did not much more than just initializing the serial
line and offering some basic functions for dumping and loading memory etc.

 In January 2012 my friend Ingo Kloeckl came for a visit and we implemented
a readonly FAT16 file system for the monitor which allowed to load programs
crossassembled/compiled on a host system to be read and started from disk
(a CF card in this particular case).

 In early 2012 I found Andrew Lynch's N8VEM Z80 single board computer (see 
http://n8vem-sbc.pbworks.com/) and ported my monitor to this system. Since 
the N8VEM has different IO-addresses for its controllers and since it relies
on a 8255 parallel IO-chip as its IDE-controller (you need the PPIDE-board to
use this feature), the monitor was quite extensively modified to support both
systems, my own Z80 computer and the N8VEM.

 In June 2012 I found Brad Rodriguez' wonderful CAMEL-Forth implementation (see 
http://www.camelforth.com) and I decided to embed this into the monitor. 

 In June 2013 I found the incredible Z80 disassembler written by John Kerr which
was published in the SUBSET column of "Personal Computer World" 1987. This has
been included into the monitor.

Assembler
---------

 The assembler used to build the monitor and its additional components like
Forth is zasm which can be found at the following URL.
http://k1.dyndns.org/Develop/projects/zasm/distributions/

 The reason for this choice is simple: I needed something which would run on
a UNIX system since I did not want to resort to a CP/M system with TASM or the
like. Some things are handled differently by zasm compared with other Z80
assemblers which required substantial changes in the CAMEL-Forth sources.

Directory structure
-------------------

monitor:
        README.txt                  This text
        camel                       CAMEL-Forth source files
                CAMEL80.S           CAMEL-Forth source
                CAMEL80D.S          CAMEL-Forth source
                CAMEL80H.S          CAMEL-Forth source
                CAMEL_LOADABLE.asm  Source to build a loadable CAMEL-Forth
                CAMEL_ADAPTER.asm   Contains the adapter to the monitor
        clean.bash                  Clean-up script - removes output files
        disassembler                Disassembler sources
                dis_z80.asm         Source of the disassembler
                dis_z80_loadable.asm    Used to build a loadable disassembler
        examples                    Example assembler programs
                mandel.asm          Compute a Mandelbrot set
        hb_z80.asm                  Source to build the monitor for my Z80 sys.
        make.bash                   Calls zasm with the necessary flags
        monitor                     Monitor source
                mondef.asm          Definitions etc. for the monitor and all
                                    programs running under the monitor
                monitor.asm         Source-code of the monitor
        n8vem.asm                   Source to build the monitor for the N8VEM

Building
--------

 To build the monitor with Forth for my Z80 system just execute

./make.bash Z80_mini.asm

 This will result in a file Z80_mini.rom.hex which is in the Intel hex format 
suitable for EPROM programmers and should be stored in a 27256 EPROM (32 kB).

 To build the monitor for the N8VEM just assemble the file n8vem.asm instead
of the file mentioned above. The resulting n8vem.rom.hex can then be programmed
into an 27C801 EPROM suitable for the N8VEM SBC.

 In case you want a CAMEL-Forth which is loadable from IDE-disk (CF-card), you 
have to assemble the file CAMEL_LOADABLE.asm (your working directory should be 
camel in this case). Since no EPROM will be burned, assemble these files just 
with zasm, not with make.bash. This will result in a file CAMEL_LOADABLE.rom 
which can then be copied onto a FAT16 formatted CF-card.

Using the monitor
-----------------

 On power-on the monitor prints a welcome message like this:

Simple Z80-monitor - V 0.13 (B. Ulmann, Sep. 2011 - May 2013)

Z> 

 All commands are grouped into command-groups which are selected by a single
character. Each such group (except the help-group, selected with H) holds a 
set of commands which are selected by a second character. Pressing H will print
the command structure currently implemented.

 Usually one wants to mount a CF-card, which is done by entering DM, short for
Disk-group, Mount. To get a file directory listing, enter FD, short for 
File-group, Directory. Please note that no ENTER-key has to be pressed - just
the individual keys to select the commands in their respective command-groups.

 To start Forth, press SF, short for Subsystem-group, Forth. 

 CAMEL-Forth has been modified to be able to load programs from the FAT16 
formatted CF-card. If Forth is started, a program can be loaded by entering the 
word "load" which then prompts the user for a file name. 
