# Zapple-II
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
- Simple CP/M Command Console Processor (CCP)
- Sample program: Processor Technology's SOL-20 BASIC/5

Aztec C v3.2 can be found [on this website](http://aztecmuseum.ca).

# 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` compiled 'out-of-the-box' under Aztec C on the Apple II, without any
modification.

This assembler 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.

I have most of the calls now and most of them have been tested to some degree
and aren't *totally* broken.

The directory calls do not return any size information in the FCB yet.  I will
fix this in due course.  There are doubtless loads of other issues and bugs.
See `SOFTCARD80.ASM` for TODO comments.

- BDOS call 00h: `C_TERMCPM` - System reset
- BDOS call 01h: `C_READ` - Console input
- BDOS call 02h: `C_WRITE` - Console output
- BDOS call 06h: `C_RAWIO` - Direct console I/O
- BDOS call 07h: `GET_IOB` - Get IOBYTE
- BDOS call 08h: `SET_IOB` - Get IOBYTE
- BDOS call 09h: `C_WRITESTR` - Console write string
- BDOS call 0Ah: `C_READSTR` - Read console string
- BDOS call 0Bh: `C_STAT` - Console status
- BDOS call 0Ch: `S_BDOSVER` - Return version number
- BDOS call 0Dh: `DRV_ALLRESET` - Reset disks
- BDOS call 0Eh: `DRV_SET` - Select disk
- BDOS call 0FH: `F_OPEN` - Open file
- BDOS call 10H: `F_CLOSE` - Close file
- BDOS call 11H: `F_SFIRST` - Search for first match in directory
- BDOS call 12H: `F_SNEXT` - Search for next match in directory
- BDOS call 13H: `F_DELETE` - Delete file
- BDOS call 14h: `F_READ` - Read file sequentially
- BDOS call 15h: `F_WRITE` - Write file sequentially
- BDOS call 16H: `F_MAKE` - Create (and open) file
- BDOS call 17H: `F_RENAME` - Rename file
- BDOS call 18H: `DRV_LOGVEC`- Return bitmap of logged-in drives
- BDOS call 19H: `DRV_GET` - Return current drive
- BDOS call 1AH: `F_DMAOFF` - Set DMA address
- BDOS call 1BH: `DRV_ALLOCVEC` - Return address of allocation map
- BDOS call 1CH: `DRV_SETRO` - Software write-protect current drive
- BDOS call 1DH: `DRV_ROVEC` - Return bitmap of read-only drives
- BDOS call 1FH: `DRV_DPB` - Get Drive Parameter Block address
- BDOS call 20H: `F_USERNUM` - Get/set user number
- BDOS call 21H: `F_READRAND` - Random access read record
- BDOS call 22H: `F_WRITERAND` - Random access write record
- BDOS call 23H: `F_SIZE` - Compute file size
- BDOS call 24H: `F_RANDREC` - Update random access pointer
- BDOS call 25H: `DRV_RESET` - Selectively reset disk drives
- BDOS call 28H: `F_WRITEZF` - Random access write record zero-filled

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` under Linux (it got too large to assemble
  with `Z80asm` under ProDOS on the Apple II.
- `softcard65.asm` - This is the 6502 back end code.  Written in Merlin8 v2.58.
  Loads at $0900 in 6502 space.  This is less than 100 bytes of code!

# 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.

I assembled this code under `Z80as` on Linux, since it defines too many
symbols to assemble natively on the Apple II in the available memory.  I plan
to take a look at the Aztec C build configuration to see if it is possible
to find more memory for dynamic allocation (ie: `malloc()`).

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.

Interestingly, there was a bug in the original BASIC/5 source that caused it
to initialize one byte of memory too many, blowing away the first byte of the
BDOS implementation at the top of memory.  This has been patched by adding a
`DEC HL` instuction at line 47 (shout-out to Qkumba for finding what the
issue was!)

BASIC/5 can now be started from the CCP prompt: `B:BASIC5`

## Other CP/M 2.2 Programs that work (to some degree)

- `DDT` debugger
- `ZSID` v1.4 debugger
- `DUMP` hex dump utility
- `PIP` (can copy files using `PIP DEST.COM=SOURCE.COM`)
- `STAT` (at least `STAT DSK` and `STAT filename` seem to work)
- `NSWEEP` file manager 

Probably lots of other small, simple programs should also work.

## Programs known not to work yet

Most of these are two big for my current TPA (around 32K).  I need to
rearrange things to make a bigger TPA, and this will probably involve
using auxiliary RAM.

- `MBASIC` - I think it tries to patch the BIOS.
- Wordstar - My eventual goal is to get this to work.
- Turbo Pascal - My eventual goal is to get this to work.


# How to Build the Code

You don't really need to build the code unless you want to make changes.
Pre-compiled versions of everything are included in this repository.

The 800K ProDOS disk image `zapple2.po` has all the files you should need.

## Building `Z80asm` using Aztec C

- Two scripts are provided to do the build: `compile` and `link`
- Run the script `compile`.  This takes a long time!
- Run the script `link`.  This just takes a couple of minutes.
- `z80asm` executable is created.

Note that `z80asm` can only be run from the Aztec C shell.  It should be
possible to build it as a normal ProDOS application, but I have not done this
yet.
 
## Building `Z80as` using Aztec C

I didn't provide a script for this.  Just build all the C files in Aztec C
as follows:

```
cc as0.c
cc as1.c
cc as2.c
cc as3.c
cc as4.c
cc as5.c
cc as6.c
ln -o z80as as0.o as1.o as2.o as3.0 as4.0 as5.0 as6.0 -lc
```
## Building `HEX2BIN` using Aztec C

- You can just run the script `makeh2b` in Aztec C
- This just does the following:

```
cc hex2bin.c
ln hex2bin.o -lc
```

## Building `SOFTCARD65` using Merlin8 2.58

- Start Merlin8 (v2.58)
- Hit 'D' for disk commands, enter `PREFIX /ZAPPLE2`
- Hit 'L' for load, enter `SOFTCARD65` and hit return.
- Hit 'E' for edit.
- Type `ASM` to assemble.
- Type 'Q' to go to the main menu.
- Hit 'O' to save the object file `SOFTCARD65` to disk, and hit return.
- Hit 'Q' to quit to ProDOS.

## Building `SOFTCARD80.BIN` using `Z80asm`

- In the Aztec C shell, enter the following commands:
- `cd /zapple2`
- `z80asm softcard80.asm` 

*Update:* The code has grown too large to build natively on the Apple II. I
have been using `z80asm` under Linux instead.

# How to Run The Code

The code assumes a Z80 Softcard (or clone) in slot 4.  This can be changed
by modifying the `SOFTCARD` address in `SOFTCARD65.S` and `SOFTCARD80.ASM`
if your card is in a different slot.

To run the code, use `zapple2.po`, which is a ready made 800K disk image.
You need to boot ProDOS from some other device, because this image is not
bootable (I should fix that!)

Run `SOFTCARD65` to start everything.  This will relocate itself to high
memory and then load the Z80 code `SOFTCARD80`.  The system will then
start the CCP and show the familiar `A>` prompt.

There are three CP/M 'drives' (actually ProDOS subdirectories) on the diskette
image: A, B and C.

The following commands are implemented:

- `DIR`
- `TYPE`
- `ERA`
- `REN`
- Changing drives using `A:`, `B:`, etc.
- Launching a `.COM` file (just type the name and any arguments)

Wildcards using `*` are not yet supported.

`REN`, `USER` and `SAVE` built-in commands are not supported yet either.

## Some things to try

- `DIR` - show files on current drive
- `DIR A:` - show files on another drive
- `DIR ABC?????.TXT` - show matching files using `?` wildcards
- `TYPE TEST.TXT` - view a text file
- `A:PIP B:MY.TXT=A:TEST.TXT` copy `TEST.TXT` from A: to B:, renaming it as `MY.TXT`
- `ERA MY.TXT` erase file `MY.TXT`
- `REN B:NEWNAME.TXT=OLDNAME.TXT`
- `STAT DRV` - show info on the virtual drive
- `DDT MYPROG.COM` - debug `MYPROG.COM` using DDT (8800 debugger)
- `ZSID MYPROG.COM` - debug `MYPROG.COM` using ZSID (Z80 debugger)
- `DUMP MYPROG.COM` - hex dump of file
- `NSWEEP` - simple interactive file manager
- `BASIC5` - Processor Technology SOL-20 BASIC/5