Initial version of README.md.

README.md

@@ -1,2 +1,106 @@
 # Zapple-II
-Tools for building and running Z80 code under ProDOS on an Apple II with a Z80 Softcard (or clone)
+Tools for building and running Z80 code under ProDOS on an Apple II with a
+Z80 Softcard (or clone)
+
+- Z80 cross assemblers running under ProDOS on the Apple II
+- CP/M BDOS emulation to allow CP/M programs to run under ProDOS
+- Sample program: Processor Technology's SOL-20 BASIC/5
+
+# Z80 Cross Assemblers & Tools
+I didn't fancy writing a Z80 assembler from scratch, and I wasn't able to
+find any existing Z80 cross-assemblers for 6502. In order to get something
+up-and-running quickly, I searched for small Z80 assemblers written in C.
+
+## Z80Asm
+
+The first suitable candidate I found was `Z80Asm`, which was developed by Udo
+Munk back in the 1988 to 1990 timeframe.  (Hr. Munk is still active and has
+repositories here on GitHub.)  I am using an older version of Z80Asm (v1.1)
+which is written in K&R (pre-ANSI) C, so it was easy to get it to compile on
+Aztec C for the Apple II.
+
+The program is rather large for Aztec C's compiler, and the resulting binary
+was also too large to run in the available memory.  I made a few minor
+modifications:
+
+- I split the largest source file `z80arfun.c` into eight pieces because
+  Aztec C can't handle files larger than around 500 lines.
+- Slimmed down a few buffers to save some RAM.
+- Reduced the number of supported files from 512 to 10.  
+- I had to compile the code to Aztec C VM code using `cci` rather than to
+  native 6502 code using `cc`.  The natively compiled version creates an
+  executable which is too large to run.
+
+The resulting assembler runs but it is quite slow due to the use of the Aztec
+VM and can't assemble large programs with lots of symbols without running out
+of memory.  However I have been using it successfully to develop the BDOS
+emulation.
+
+`Z80Asm` also builds and runs on Linux which allows larger files to be
+assembled and is much faster than running on 6502 at 1Mhz.
+
+## Z80as
+
+Udo Munk pointed me towards an alternative assembler, `Z80as`, which was
+originally developed by the Mark Williams Company and which ran on PDP-11
+under Coherent.  This assembler has the advantage of small size, and is also
+written in K&R C.
+
+`Z80as` generates Intel HEX files rather than BIN files, so I wrote a simple
+converter called `HEX2BIN`.
+
+`Z80as` also builds and runs on Linux which allows larger files to be
+assembled and is much faster than running on 6502 at 1Mhz.
+
+## HEX2BIN
+
+This is a quick-and-dirty conversion program for converting the HEX files
+generated by `Z80as` into BIN files that can be loaded on the Apple II using
+`BLOAD`.
+
+HEX files can have 'holes' in them, and `HEX2BIN` takes care of zero-filling
+the holes.
+
+# CP/M BDOS Emulation
+
+I have started work on a CP/M BDOS emulation layer.  The plan is to add
+support for all the CP/M 2.2 system calls, which should allow a CP/M program
+to run on the Softcard Z80 CPU and have all the system calls routed to the
+6502 and serviced using the Apple II ROM monitor routines and the ProDOS MLI.
+
+This is at an embryonic stage at the moment as it only provides three system
+calls:
+
+- BDOS call 01h: `C_READ` - Console input
+- BDOS call 02h: `C_WRITE` - Console output
+- BDOS call 0Bh: `C_STAT` - Console status
+
+There are two parts to the BDOS emulation:
+
+- `softcard80.asm` - This is the Z80 code to handle BDOS calls and send them
+  to the 6502 to be processed.  Written in Z80 assembler.  I am currently
+  assembling this using `Z80asm` (but will probably switch to `Z80as` when it
+  grows too large.
+- `softcard65.asm` - This is the 6502 back end code.  Written in Merlin8 v2.58.
+
+# Sample Programs
+
+## BASIC/5
+
+This is one of the BASIC interpreters from the Processor Technologies SOL-20
+system.  The source code was provided as an example with z80as.
+
+It is a 5K BASIC, so it is rather primitive.  However it does have a floating
+point package and trig functions.
+
+BASIC/5 only uses three system calls: `C_READ`, `C_WRITE` and `C_STATUS`.
+
+There is currently no support for loading or saving BASIC programs, but I may
+add this later.
+
+The manual for BASIC/5 is included in this GitHub repo, in PDF format.
+
+# How to Run The Code
+
+TODO: Write this!
+