This repository contains a CP/M emulator, with integrated CCP ("Console Command Processor", i.e. shell), which is designed to run CP/M binaries. The project was initially created to run a text-based adventure game, which I wrote a few years ago, to amuse my child. (That was written in Z80 assembly language targeting CP/M, later I ported to the ZX Spectrum.)
Over time this project has become more complete, and I've now implemented enough functionity to run many of the well-known CP/M programs:
As things stand this project is "complete". I'd like to increase the test-coverage for my own reassurance, but I've now reached a point where all the binaries I've tried to execute work as expected. If you find a program that doesn't work please open an issue, beyond that I think this project is "complete" and future development will be minimal, and sporadic.
NOTE I've not implemented any notion of disk-support. This means that opening, reading/writing, and closing files is absolutely fine, but any API call that refers to tracks, sectors, or disks will fail (with an "unimplemented syscall" error).
A companion repository contains a collection of vintage CP/M software you can use with this, or any other, CP/M emulator:
This emulator is written using golang, so if you have a working golang toolchain you can install in the standard way:
go install github.com/skx/cpmulator@latestIf you were to clone this repository to your local system you could build, and install it, by running:
go build .
go install .If neither of these options are suitable you may download a binary from our release page.
Releases will be made as/when features seem to justify it, but it should be noted that I consider the CLI tool, and the emulator itself, the "product". That means that the internal APIs will change around as/when necessary - so far changes have been minor, but I'm not averse to changing parameters to internal packages, or adding/renaming/removing methods as necessary without any regard for external users.
git clone https://github.com/skx/cpm-dist.git /tmp/cpm-distcpmulator -cd /tmp/cpm-dist -directoriesThe CP/M input handlers need to disable echoing when reading (single) characters from STDIN. There isn't a simple and portable solution for this in golang, although the appropriate primitives exist so building such support isn't impossible.
Usage of is demonstrated in the standard library:
Unfortunately there is no code there for reading only a single character, rather than a complete line. In the interest of expediency I resort to executing the stty binary, rather than attempting to use the x/term package to manage echo/noecho state myself, and this means the code in this repository isn't 100% portable; it will work on Linux and MacOS hosts, but not Windows.
I've got an open bug about fixing the console (input), #65.
If you launch cpmulator with no arguments then the default CCP ("console command processor") will be launched, dropping you into a familiar shell:
$ cpmulator
A>dir
A: LICENSE . | README .MD | CPMULATO. | GO .MOD
A: GO .SUM | MAIN .GO | RET .COM
A>TYPE LICENSE
The MIT License (MIT)
..
A>You can terminate the CCP by typing EXIT. The following built-in commands are available:
There are a pair of CCP implementations included within the emulator, and they can be selected via the -ccp command-line flag:
cpmulator -ccp=ccp .., or use A:!CCP CCP to change to it at run-time.GET 0100 FOO.COM" will load a binary into RAM, at address 0x100. Then "JMP 0100" will launch it.PEEK and POKE commands which can show/set memory contents.LIST file.ext will "print" the contents of file.ext, but see the note later about printer-output (TLDR; We write it to print.log.)#) will be ignored, which is useful for commenting purposes inside SUBMIT files.You can also launch a binary directly by specifying it's path upon the command-line, followed by any optional arguments that the binary accepts or requires:
$ cpmulator /path/to/binary [optional-args]There are several command-line options which are shown in the output of cpmulator -help, but the following summary shows the most important/useful options:
-cd /path/to/directory
-directories
-log-path /path/to/file
A:!DEBUG 1 to enable "quick debug logging", and A:!DEBUG 0 to turn it back off again, at runtime.-prn-path /path/to/file
-list-syscalls
-version
When the CCP is launched for interactive execution, we allow commands to be executed at startup:
SUBMIT.COM and AUTOEXEC.SUB exist on A:AUTOEXEC.SUB will be executed.
SUBMIT AUTOEXEC" to achieve this.This allows you to customize the emulator, or perform other "one-time" setup via the options described in the next section.
There are a small number of extensions added to the BIOS functionality we provide, and these extensions allow changing the behaviour of the emulator at runtime.
The behaviour changing is achieved by having a small number of .COM files invoke the extension functions, and these binaries are embedded within our emulator to improve ease of use, via the static/ directory in our source-tree - This means no matter what you'll always find some binaries installed on A:, despite not being present in reality.
NOTE To avoid naming collisions all our embedded binaries are named with a
!prefix, except for#.COMwhich is designed to be used as a comment-binary.
We default to loading the enhanced CCP, but allow the original from Digital Research to be used via the -ccp command-line flag. The binary A:!CCP.COM lets you change CCP at runtime.
Traditionally pressing Ctrl-C would reload the CCP, via a soft boot. I think that combination is likely to be entered by accident, so in cpmulator we default to requiring you to press Ctrl-C twice in a row to reboot the CCP.
The binary A:!CTRLC.COM which lets you change this at runtime. Run A:!CTRLC 0 to disable the Ctrl-C behaviour, or A:!CTRLC N to require N consecutive Ctrl-C keystrokes to trigger the restart-behaviour (max: 9).
We default to pretending our output device is an ADM-3A terminal, this can be changed via the -console command-line flag at startup. Additionally it can be changed at runtime via A:!CONSOLE.COM.
Run A:!CONSOLE ansi to disable the output emulation, or A:!CONSOLE adm-3a to restore it.
You'll see that the cpm-dist repository contains a version of Wordstar, and that behaves differently depending on the selected output handler. Changing the handler at run-time is a neat bit of behaviour.
We expect that all real debugging will involve the comprehensive logfile which is created via the -log-path argument to the emulator, however we
have a "quick debug" option which will merely log the syscalls which are invoked, and this has the advantage that it can be enabled, or disabled, at
runtime.
A:!DEBUG.COM will show the state of the flag, and it can be enabled with A:!DEBUG 1 or disabled with !DEBUG 0.
I've placed a copy of my own lighthouse of doom game within the dist/ directory, to make it easier for you to get started:
$ cd dist/
$ ../cpmulator LIHOUSE.COM
..
Written by Steve Kemp in 2021, version unreleased-git.
https://github.com/skx/lighthouse-of-doom
Any references to the Paw Patrol are entirely deliberate.
Press any key to start.A companion repository contains a larger collection of vintage CP/M software you can use with this emulator:
By default when you launch cpmulator with no arguments you'll be presented with the CCP interface, with A: as the current drive. In this mode A:, B:, C:, and all other drives, will refer to the current-working directory where you launched the emulator from (i.e. they have the same view of files). This is perhaps the most practical way to get started, but it means that files are repeated across drives:
A:FOO" is the same as "B:FOO", and if you delete "C:FOO" you'll find it has vanished from all drives.
FOO" will exist on drives A: all the way through to P:.If you prefer you may configure drives to be distinct, each drive referring to a distinct sub-directory upon the host system (i.e. the machine you're running on):
$ mkdir A/ ; touch A/LS.COM ; touch A/FOO.COM
$ mkdir B/ ; touch B/DU.COM ; touch B/BAR.COM
$ mkdir G/ ; touch G/ME.COM ; touch G/BAZ.COMNow if you launch the emulator you'll see only the files which should be visible on the appropriate drive:
$ cpmulator -directories
A>DIR A:
A: FOO .COM | LS .COM
A>DIR B:
B: BAR .COM | DU .COM
A>DIR G:
G: BAZ .COM | ME .COM
A>DIR E:
No fileA companion repository contains a larger collection of vintage CP/M software you can use with this emulator:
This is arranged into subdirectories, on the assumption you'll run with the -directories flag, and the drives are thus used as a means of organization. For example you might want to look at games, on the G: drive, or the BASIC interpreters on the B: drive:
frodo ~/Repos/github.com/skx/cpm-dist $ cpmulator -directories
A>g:
G>dir *.com
G: HITCH .COM | LEATHER .COM | LIHOUSE .COM | PLANET .COM
G: ZORK1 .COM | ZORK2 .COM | ZORK3 .COM
G>dir b:*.com
B: MBASIC .COM | OBASIC .COM | TBASIC .COMYou can also point specific drives to particular paths via the -drive-X command-line arguments. For example the following would have A: and B: pointed to custom paths, and C:-P: using the current working directory:
$ cpmulator -ccp=ccpz -drive-a /tmp -drive-b ~/Repos/github.com/skx/cpm-dist/G/You can see the list of implemented syscalls, along with a mention of how complete their implementation is, by running:
$ cpmulator -list-syscalls
BDOS
00 P_TERMCPM
01 C_READ
02 C_WRITE
03 A_READ
..snip..
BIOS
00 BOOT
01 WBOOT
..snip..Items marked "FAKE" return "appropriate" values, rather than real values. Or are otherwise incomplete.
The only functions with significantly different behaviour are those which should send a single character to the printer (BDOS "L_WRITE" / BIOS "LIST"), they actually send their output to the file
print.login the current-directory, creating it if necessary. (The path may be altered via the-prn-pathcommand-line argument.)
The implementation of the syscalls is the core of our emulator, and they can be found here:
When an unimplemented BIOS call is attempted the program it will abort with a fatal error, for example:
$ ./cpmulator FOO.COM
{"time":"2024-04-14T15:39:34.560609302+03:00",
"level":"ERROR",
"msg":"Unimplemented syscall",
"syscall":255,
"syscallHex":"0xFF"}
Error running FOO.COM: UNIMPLEMENTEDIf things are mostly working, but something is not quite producing the correct result then we have some notes on debugging:
For reference the memory map of our CP/M looks like this:
CLS, EXIT, HALT & QUIT built-in commands.The testing that I should do before a release:
SAVE "FOO", and SAVE "FOO", A.)Let me know by filing an issue.
Steve