Installing CPM

The CP/M system comprises a custom CP/M BIOS and the BDOS (Basic Disk Operating System) and command line processor, CPP (Console Command Processor).

The Open Source status of CP/M has fairly recently been clarified so I feel safe including the Digital Research portions of the system in this Git repository.

Before you begin

Installing software onto the Z80-Retro requires copy and pasting hex code from your computer (generally from this repo) into your terminal window. This will only work successfully if you have hardware flow control enabled and you're using a USB-serial converter that has RTS/CTS flow control pins (many don't!).

I use the DSD TECH USB to TTL Serial Adapter with FTDI Chip which I got from Amazon and other places. The thing to watch out for is that you have the CTS and RTS signals. Some devices using the same chip don't make these pins available, without them you have no flow control. Read more on my development hardware page.

BIOS

CP/M is a layered system with, effectivly, a hardware abstraction layer called the BIOS (Basic Input/Output System). This is the only component that needs to be modified to port CP/M to a new system. I've written a BIOS for my system that utilises the ZLoader/ZIOS core functions to provide I/O. In this way the BIOS itself is kept fairly small, maximising the Transient Programme Area (TPA) and reducing the development overhead.

Main features:

• Utilises the ZIOS core functions for I/O
• Understands the ZIOS virtual disk model, allowing access to any of the potential 1023 virtual 4MB 'disks' per SDCard.
• Leaves console I/O to the underlying system

Installing CP/M

The BIOS along with the CP/M code resides in the apps/cpm22 directory. A precomiled CP/M system is provided in the images top-level directory. You need to follow these steps to get a working CP/M system:

1. Format a virtual disk to host your CP/M system
2. Copy the compiled CPM system to the prepared virtual disk
3. Add an entry to the Zloader boot system
4. Install download.com to facilitate bulk loading of applications
5. Install common CP/M applications

Format a CP/M disk

You don't need to understand the disk format CP/M uses, all you need to know is how to create a suitable 'empty' structure. Luckily all this requires is for the start of the disk to contain the byte 0xE5 repeated a number of times. You can do this from ZLoader as follows, assuming CP/M is to be installed on virtual drive A:

> f 0 0 e5
> wi 80:A 8000 8000

The first line fills all memory with the byte E5. The second line writes that data to drive A starting from sector 128 (0x80), which is right after the first 64K bytes. Once you've done this the disk is ready for CP/M.

Note that in this implementation the first 64K of any disk used for CP/M is reserved for the system.

Install CP/M

CP/M is going to reside in the first logical track of the virtual disk. It only needs a fraction of that space! The steps to get the CP/M system onto the track are as follows:

1. Obtain an Intel Hex file containing the CP/M you want to run (eg images/cpm22.hex). You can build your own version, or make your own changes using these build instructions
2. Load the Intel Hex CP/M file into application space RAM
3. Write the image to the start of the target virtual disk

This can be achieved via Zloader as follows:

> F 0 0 0
> L
paste Intel Hex format version of CP/M here
> WI 0:A DD00 FE00

The F command clears all application memory to zero. L allows you to transfer an Intel hex format file into application memory. Finally WI writes data to one of the virtual disks on one of the SDCards. In this case DB00 and FE00 are the range of application space memory to write. 0:A is where to write it (start of the virtual disk mounted on A). NOTE: the range may be different for your version of CP/M.

Updating the Zloader boot menu

Zloader manages a boot menu of applications that can be run from the SDCard. The loader knows nothing about the application other than what's in the boot menu structure.

You can see a list of currently installed boot items by entering bos? at the Zloader prompt.

To add the CP/M that you've installed into this menu you need the following information:

• Where the code to load exists on the SDCard
• Where to start loading that image into application memory (0xDB00)
• How many bytes to load into memory from that starting location (0x2300)
• The execution address which can be found in the build instructions or the README in the images directory (0xF10C)
• An available boot application ID. List the existing menu items using bos? and choose an ID that doesn't appear in the menu

The values in (braces) are the values correct at time of writing but may change as CP/M is updated.

Once you have all this information you can add an entry to the boot menu with:

WB 1 0:A DD00 2100 F30C 01 CP/M

Parameters here are:

• 1: the unique ID for this image, as selected above. There will be an error if there's already an image with this ID (see below).
• 0:A: Where to load the image from the SDCard. Should match where you placed CP/M in the last section.
• DD00: Where to place loaded data in application memory
• 2100: The number of bytes to load into memory
• F30C: The execution address (where to run the code)
• 01: Flag byte (see below)
• CP/M: The name of this application. Maximum 8 characters

The unique ID is an 8 bit number. You can boot a specific image using BOS n where n is the unique ID you assigned in this command. If you want to automatically boot into an operating system, for example CP/M, use 1 as the ID and DIP Switches correctly to auto-boot from the SDCard.

The flag byte is a bitmask:

• bit 0: Whether this application uses ZIOS (CP/M does)
• bit 1: Whether ZIOS should intercept break characters to return to Zloader. No for CP/M

Assuming you have the parameters right you now have a functional CP/M system. You can test that it works by using the Zloader bos X command where X is the ID that you used in the WB command above.

Install download.com

The first application you'll want to install is Grant Searle's download.com, the use of which allows you to bootstrap any other application. Get hold of download.hex, which is an Intel Hex version of download.com. This is currently available in the cpmtools directory.

Start up Zloader and do the following:

> F 0 0 0
> L
paste the content of `download.hex`
> BOS n
CP/M starting...
a>save 4 download.com
a>dir
DOWNLOAD.COM

Where:

• F clears all application space memory to zero
• L loads an Intel hex format image into application memory
• BOS loads CP/M from the SDCard (n is the ID that you used with the WB command above)
• save is the CP/M CCP built in command to write data from memory onto the SDCard. In this case writing 4x128 byte CP/M sectors to disk

Loading applications

download.com is an efficient way of bulk loading applications onto a CP/M disk. You'll need a suitable package of tools.

The file images/cpm22apps.pkg contains a collection of the basics and some of my favourites.

NOTE: for download to work effectively you will need hardware flow control enabled in your terminal emulator.

• Start CP/M from Zloader with the bos n command
• Once into CP/M (having already installed download.com as per the previous section) simply paste the contents of images/cpm22apps.pkg into the terminal window. Note: at the a> prompt paste the contents of the file. Do not type the word download or anything before pasting the file contents.

Assuming there are no errors you'll have a bunch of common CP/M tools installed on the A drive.

Other applications

The internet holds a wealth of legacy CP/M tools. You can download these to your system using the download.com file, either individually or concatenating them together into a single file as I've done with cpm22apps.pkg.

I've included a small node programme in the tools subdirectory of this repo. This will take any file or directory of files and convert it/them into a format suitable of pasting into your terminal window using the download tool. Assuming you have a recent version of Node.js installed on your computer conversion is as simple as typing the following into a shell/command line window:

node ../path/to/bin2cpmhex.js file.com > dnld.cpm

bin2cpmhex takes one or more files or directory names and creates a stream of hex data and download.com command lines, sent to stdout. Generally redirect this into a file and you have a package that can be easily imported into a CP/M computer with the download.com executable installed.

If a file with a '.hex' extension is seen this is taken as an Intel hex form of a CP/M .com file. The output is renamed to the .com version and the hex data extracted and assumed to to load from 100h

Output format is:

A:DOWNLOAD fname
U0
:{hexdata}
>LLCC

Where:

• {hexdata} is a sequence of hex character pairs (one per byte)
• LL is the lower 8 bits of a count of all the bytes in the hexdata set (size of binary)
• CC is the checksum, calculated by adding every byte in the hexdata set and taking the least significant 8 bits.

Where more than one file is included in the package the above format is repeated for each file.