skx / z80-playground-cpm-fat

CP/M for the Z80 Playground that runs on the FAT disk format

• Overview
• Contents
• Source Code
  • Bootloader
• CP/M Distribution Overview
  • CP/M System Changes
    • CLS
    • Search Path
    • Input Handling
    • Removals
    • TODO?
  • CP/M Binaries
  • Bootloader Changes
• Useful Links
• Future Plans?

Overview

This repository contains a distribution of CP/M 2.2, which can run upon the "Z80 Playground" board. The Z80 Playground single-board computer uses an external FAT-filesystem stored upon a USB-Stick to provide storage, giving it very easy interoperability with an external computer.

For more details of the board please see the official homepage:

• https://8bitStack.co.uk
  • The forums contain more useful content too.
• You can also see various videos on youtube:
  • Z80 Playground Playlist

Contents

This repository contains two things:

• The assembly language source-files which will build CP/M.
• A set of binaries, organized into distinct drives, which can be copied to your USB-stick to produce a useful system.
  • Some of the binaries are generated from the sources beneath utils/, others are were obtained from historical release archives.

Source Code

The source code available here is made of a couple of different files:

• core.asm - The core routines for accessing the hardware.
• bios.asm - A stub of a CP/M BIOS.
• bdos.asm - Implementation of the CP/M BDOS, as written by John Squires.
• ccp.asm - The standard Digital Research CCP.
• z80ccp.asm - An enhanced/expanded CCP.

You can compile these via the pasmo compiler, or look at the latest versions upon our releases page. If you have make and pasmo installed you can generate the compiled versions via:

 $ make

(The system will rebuild intelligently if you edit any included files.)

Regardless of whether you build from source, or download the prebuilt versions, you should place them upon your USB-stick beneath the top-level /CPM directory.

Bootloader

To get the system started there is a boot loader compiled and stored within the EEPROM. If you have a EEPROM programmer you should upload the contents of CPM.HEX to it, which is compiled from cpm.asm.

• I wrote some simple notes on updating the bootloader.

The bootloader runs a simple monitor and allows CP/M to be launched. Launching CP/M involves reading /CPM/cpm.cfg which contains the list objects to read into RAM, along with the addresses to which each should be loaded. Once the files are loaded the system jumps into the monitor, from which you can launch CP/M, TinyBASIC, & etc.

CP/M Distribution Overview

The full content of the USB stick supplied with the kit can be found beneath the dist/ directory.

CP/M doesn't have the concept of sub-directories, so all files are arranged at the top-level, however for organization different "drives" are used. To help keep things organize I've shuffled some of the contents around such that the binaries are grouped into a set of logical collections:

Drive	Contents	Notes
A:	All general-purpose utilities.
B:	BASIC Code and interpreter.	Type SYSTEM to exit :)
C:	AzTec C Compiler	Simple overview
D:
E:	Editor - WordStar
F:	FORTH - DxForth
G:	Games - all types
H:
I:
J:
K:
L:
M:
N:
O:
P:	Turbo Pascal 3.00A	Getting started with Turbo Pascal.

To look at the list of games, for example, you'll run something like this:

A> G:
G> DIR
..

Or:

A> DIR G:*.COM

CP/M System Changes

In terms of changing the system-core I have patched the CCP (command-processor) component of CP/M to change a couple of things:

CLS

There is a new built-in command CLS which will clear your screen.

Search Path

I've added a naive "search path", which allows commands to be executed from a different drive if not found in the present one. By default the system is configured to search for binaries which were not found within the A: drive:

 A>srch
 Search drive set to A

If you wish to disable this run SRCH 0, otherwise you can change the drive:

 B>srch a
 Search drive set to A
 B>srch b
 Search drive set to B

Input Handling

I've updated the input-handler ("Read Console Buffer" / BIOS function 1) such that:

• The backspace key deletes the most recently entered character.
  • (This is in addition to the keystroke C-h continuing to work in that same way.)
• Ctrl-c cancels input.
  • (It returns an empty input-buffer, so it allows easy discarding.)

Now these two keystrokes work in a natural fashion at the CP/M prompt.

Removals

I've removed the undocumented (imp)ort and (exp)ort commands, to cut down on space, and avoid confusion.

This meant I could remove a little code from the CCP source, includeing:

• debug:
• ADD32: / SUBTRACT32:
• display_hl32: and show_c_in_hex:

If required those could be replaced by the existing code in message.asm - just add an include and use them as-is.

TODO?

Possible future changes might involve:

• Optimize for size.
• Look at message.asm
  • Which is a bit of a messy piece of code.

CP/M Binaries

• I've added a copy of DX Forth beneath F:.
• I've added a copy of the Turbo Pascal compiler beneath P:.
  • I wrote a simple getting started with Turbo Pascal guide.
  • Included is also a sample "hello.pas" file.
• I've added Zork 1, 2, & 3 beneath G:.
  • I've designated the G: drive as the game-drive, and moved other games there too.
• I added vi.com to A:.
  • This was obtained from https://github.com/udo-munk/s/.
  • While not a perfect version of vi it is pretty amazing considering.
• I added ql.com ("quick list")
  • After reading this guide to text-pagers on CP/M.
• I added a couple of simple utilities to A:, with source beneath utils/:
  • locate.com
    • Find files matching a given pattern on all drives:
      • LOCATE *.COM.
    • or show all user-numbers which contain matches upon a single drive:
      • LOCATE A:*.COM USER.
      • Note that user-numbers seem to be slightly broken in this distribution.
  • monitor.asm
    • Jump back to the monitor, from within the CP/M environment.
    • Essentially page in the ROM, then reboot.
• I removed duplicate file-contents from various drives.
• The copy of ls.com located upon the A: drive has been updated.
  • Via a couple of pull-requests to the upstream source.

Bootloader Changes

• I've patched TinyBASIC such that the EXIT keyword will restart the system.
  • Otherwise there was no way back to the BIOS/menu short of hitting the reset-switch.

Useful Links

• CP/M help and information:
  • CP/M Commands
• CP/M Software
  • Commercial CP/M Software Archive
  • The HUMONGOUS CP/M Software Archives
• WordStar Keyboard Bindings

This repository contains a copy of Turbo Pascal, along with a guide to using it, you can find a couple of simple games online here:

• Snake
• Quatris ("tetris")

Future plans?

• Optimize some of the assembly for size.
  • Obvious easy-win is replacing instructions such as ld b,0 with xor b.
• Make a couple of minor changes to ccp:
  • Would be nice to have command-history, accessible via M-n/M-p, or the arrow-keys.
  • I added cls.com, it might make more sense to build that into the CCP-shell.

z80-playground-cpm-fat's Issues

Drop `F:STAT.COM`

There is already a STAT present in A:.

Implement CLS as a built-in

This is better than having the external command.

Add a C-compiler

BDS-C is a decent C-compiler, available from the following site:

• http://www.cpm.z80.de/develop.htm

To resolve this bug we need to do three things:

• Add the binaries beneath C:> (for "(C)-compiler).
• Add a document to show examples, much like I did with the turbo-pascal link.
• Confirm it works on the real hardware.
  • So far I've only run the compiler under an emulator.

Sample program:

int main( arc, argv )
   int arc;
   char *argv[];
{
    int i;

    /*  greetings */
    printf("Hello, world!\n");

    /* show arguments we received */
    for ( i = 1; i < arc; i++ ) {
        printf("%d:%s\n", i, argv[i]);
    }

    return 0;
}

Compile like so:

    A>cc main.c
    BD Software C Compiler v1.60  (part I)
    ..

Once compiled you need to link:

    A>clink main.crl
    BD Software C Linker   v1.60
    ..

Finally run it:

    A>main foo bar
    Hello, world!
    1:FOO
    2:BAR

NOTE: The zip contains a bunch of directories, we want to install/use the contents of the bdsc160 sub-directory, and note that the various "*.LBR" files are archives and can be unpacked for sources/examples, etc.

Ctrl-c should reboot

In the line-input function Ctrl-c aborts input, returning an empty result (string of zero length).

Apparently at the start of the line Ctrl-C should reboot.

Add paging to `type`

This is less annoying than having to use the scrollback from terraterm/gnu screen/etc.

Remove second copy of wordstar

There are copies in D: and E:.

Nuke the one in D: and call E: Editor.

SRCH built-in doesn't really work so well

When you execute a command the shell gets replaced, so the value you set before gets over-written.

Implementation was cute, but we should just hardware A: as the search-path.

Alternative CCP - CCPZ

Hi SKX, in case you don't get notifications from the root cpm_fat site, thought I would drop an issue here to note the command processor CCPZ here. As I indicate this works well on my board though not fully tested yet.

I would be interested to know if you manage to get CCPZ running on a real Z80 Plaground.

I use the .COM extension rather than .bin - loads through the cpm.cfg file just as well - because in the future I was going to look at creating a CP/M loader to change the CCP on the fly. Shouldn't be to hard? Simply load the new CCP at DE00h and then jump to 0000h?

Anyway hope this works for you?

Turbo pascal works, but is incomplete

P: has turbo pascal, but the distribution is incomplete.

Add the whole thing. If only for the terminal reconfiguration ability.

Future plan comment re: optimisation with xor

Hi skx,
Just to potentially save you some future debug effort, your comment in README.md:

"Obvious easy-win is replacing instructions such as ld b,0 with xor b."

won't work - "xor b" means "xor a,b". The "xor a" trick only works on a.
Cheers!