SpectranGSX

An experimental Spectranet device driver for CP/M's GSX subsystem

This project consists of two parts:

• A driver for CP/M's GSX subsystems, written in Z80 assembly, cross-compiled
  on UNIX systems using Pasmo compiler (see comments in the code). Its operation
  entirely depends on Spectranet device FID driver (spectran.fid, see
  Spectranfid project) that must be loaded on CP/M boot.

• A remote display server which also acts as a Spectran terminal server and
  a Spectran remote disk image server. It depends on my libgsxrender library.

Getting it

To fetch the code along with the required submodules, use recursive cloning:

$ git clone --recursive https://git.code.sf.net/p/spectrangsx/code.git spectrangsx

Building it

The GSX driver part

Build it on UNIX by:

$ pasmo --prl ddspcnet.asm ddspcnet.prl

Then copy it (namely, the ddspcnet.prl file) to the same place where your GSX
application is to be executed.

The remote display server part

The source code of this server depends on SDL2, SDL2_gfx and alsa-lib libraries.

To build spectrangsxd executable file, just invoke make command in the
spectrangsxd directory.

Usage

The ddspcnet GSX driver

The ddspcnet.prl driver for the CP/M's GSX subsystem needs to be copied to a
place where your GSX application is to be executed. It also needs to be
referred from the assign.sys file which also must exist in the same place; it
is a short text file with just a single line:

01 @:DDSPCNET

It states that the device with an identifier (a device number) 1 is handled by
our DDSPCNET driver (the ddspcnet.prl file).

Your GSX application will also need the gsx.sys file, usually shipped with any
GSX distribution. Also, remember to run the gengraf utility on your
application's executable .com file in order to make it a proper GSX program.

Note that in order to work, this GSX driver communicates (by means of CP/M's
BIOS calls) with the Spectranet networking device FID driver (spectran.fid).
Make sure it is running in your system: check that the N: drive is accessible
and the SPCNET: device is on a list of available physical devices, e.g. by
invoking the device command:

> device

Physical Devices:
I=Input,O=Output,S=Serial,X=Xon-Xoff
CRT    NONE  IO     LPT    NONE  O
SIO    9600  IOS    SPCNET NONE  IO
SERIAL 1200  IOS

Current Assignments:
CONIN:  = CRT
CONOUT: = CRT
AUXIN:  = SERIAL
AUXOUT: = SERIAL
LST:    = LPT

Enter new assignment or hit RETURN


>

When your GSX application is started, this GSX driver passes all of the GSX
calls to the Spectranet device FID driver which encapsulates them into remote
disk R/W requests performed on an non-existing track 0xffff. The 'spectran'
protocol server running on the other side of the TCP connection (namely, the
spectrangsxd server described next) recognizes those requests and executes the
drawing operations by calling SDL2_gfx library functions.

The spectrangsxd server

This multi-purpose server combines and exposes the following functionalities:

• remote display for GSX graphics (and GSX audio 'escapes'),
• remote disk image,
• terminal emulator (using the same display output as the GSX graphics) exposed
  as a console server compatible with the spectran.fid driver,
• MIDI commands filter with MIDI ALSA pass through (similar to passmidi utility
  from the retromidi project).

To start the spectrangsxd executable, you need to provide the following
parameters:

• TCP wait port for the remote console server (usually 2423),
• TCP wait port for the remote disk server (usually 2424),
• the name of the disk image file (see below),
• optionally, the name of ALSA MIDI port to pass filtered out MIDI commands to.

For the third parameter, you can provide any (previously used) CP/M disk image
and this is a convenient way of copying wast amount of files across CP/M
systems. Yet if you don't have any such image, you can prepare an empty image
with the fillowing make command invocation (started in the spectrangsxd
disectory of this project):

$ make formatted.rawimg

The make command given above creates freshly formatted image, which in case of
CP/M means that every byte of the disk image has a value of 0xe5.

Note that the only supported (by the FID driver) image size is 16MB
(16777216 bytes).

The fourth parameter is optional and it allows passing MIDI commands through
to a selected ALSA synth. To list all of the available ALSA MIDI synths, you
can use following command:

$ aplaymidi -l

If you don't have any real hardware ALSA-controlled MIDI synth connected
(e.g. through an USB adapter), you can start fluidsynth (with one of its sound
fonts) which is a popular ALSA-compatible software synth. You can start it with
following command:

$ fluidsynth -a pulseaudio -m alsa_seq /usr/share/sounds/sf2/FluidR3_GM.sf2

Now aplaymidi -l should list fluidsynth as one of the available MIDI synths:

$ aplaymidi -l
 Port    Client name                      Port name
128:0    FLUID Synth (19365)              Synth input port (19365:0)

You can give 128:0 port name as the fourth parameter of the spectrangsxd
invocation.

After that, during the CP/M Plus boot process, the Spectranet device FID driver
should establish the two TCP connections with your spectrangsxd server
instance.

Having both TCP connections established, you can redirect the CP/M's console to
the remote console server by typing (in the CP/M command line):

device con:=spcnet

A CP/M command line prompt should appear in the spectrangsxd window. From
now on, you can control your CP/M system from your UNIX host.

As a side note. This console implementation uses SDL2 functions to read a
joystick hat (a typical way of reading 80's Atari-compatible joysticks connected
through an USB adapter, e.g. Megadrive Controller Adapter). Joystick movements
are translated to the terminal keypresses: 6 for left, 7 for right, 8 for
up, 9 for down and 0 for fire (this is the same way CP/M Plus on ZX Spectrum
+3/+3e expresses readings of the movements of a joystick connected to the
Sinclair Joystick Port 1).

Similarly to the con: console port, other system ports (aux: and lst:) can
too be simultaneously redirected to the spcnet: device. For example, the
DX-Forth examples from the retromidi project are sending MIDI commands to the
lst: port. You can redirect it to spcnet: so both con: and lst: ports
will be redirected to the same device:

> device lst:=spcnet

Physical Devices:
I=Input,O=Output,S=Serial,X=Xon-Xoff
CRT    NONE  IO     LPT    NONE  O
SIO    9600  IOS    SPCNET NONE  IO
SERIAL 1200  IOS

Current Assignments:
CONIN:  = SPCNET
CONOUT: = SPCNET
AUXIN:  = SERIAL
AUXOUT: = SERIAL
LST:    = SPCNET


>

As it is easy to distinguish VT52 and MIDI control codes, spectrangsxd can
filter out the MIDI commands and pass them through to the selected ALSA MIDI
port. If your music program sends MIDI commands to the aux: port, you can
redirect it the same way.

Still the most important role of the spectrangsxd server is to render GSX
graphics. You can try to run example programs shipped with Turbo Pascal GSX
library, or with libgsx C library (the cpm-libgsx project) or with gsx.src
library for DX-Forth (the cpmgsx-dxforth project). They test both simple and
advanced GSX functions (e.g. color graphics, style changes, text rendering,
'escapes', accelerated primitives drawing). Also, thanks to the SDL2 library,
GEM-specific sound 'escapes' are executed producing simple tones of a given
frequency and duration.