spectranfid: A Spectranet networking device FID driver for CP/M Plus

This is a FID driver for CP/M Plus system exposing networking capabilities
of the Spectranet device.

This driver can work along with the spectram.fid driver exposing unused part
of Spectranet's RAM as the M: ramdisk. These two drivers can be installed in
your CP/M Plus system in any order.

Building it

Configure this code before build! E.g. set connect_ip correctly.

The building process is following:

First on UNIX:

$ pasmo --prl spectran.asm spectran.fid

...then on CP/M:

> fidcsum spectran.fid

(get fidcsum.com from https://www.seasip.info/Cpm/software/fidcsum.com).

After the preparations described above, copy the spectran.fid file to your
bootable CP/M Plus floppy disk (or a bootable .dsk +3 disk image for being
booted from a Gotek device).

WARNING! Don't use Gotek's jumper solution to force it to be A: drive!
This can smash your onboard disk controller! If you really need your Gotek
device to become A: drive, equip your Spectrum computer with a hardware A/B
drive switch as described on this page:
https://zxnet.co.uk/spectrum/floppy_drive_swap.

One possible way to copy spectran.fid file to your bootable CP/M Plus image is
following:

• Using dsktrans tool (shipped with John Elliott's libdsk library) create
  compatible .dsk disk image (e.g. spectranfid.dsk) as follows:

$ mkdir spectranfid.tmp
$ cat >spectranfid.tmp/.libdsk.ini <<LibDskIni
; This file is formatted like a Windows INI file,
; but it must have only one section and that
; section must be:
[RCPMFS]
; Filesystem parameters are:
BlockSize=1024 ; Size of CP/M block
DirBlocks=2    ; Number of blocks for the directory
TotalBlocks=175  ; Number of directory and data blocks
SysTracks=1    ; Number of system tracks
Version=3      ; Filesystem version (CP/M 2 or 3, or ISX)
Format=pcw180
LibDskIni
$ cp spectran.fid spectranfid.tmp
$ dsktrans -itype rcpmfs -otype dsk spectranfid.tmp spectranfid.dsk
$ rm -rf spectranfid.tmp

• Copy spectranfid.dsk file to your Gotek USB memory stick.
• Boot CP/M Plus from Gotek A: drive as usual.
• Change A: disk image in Gotek to spectranfid.dsk.
• Press Ctrl + c in the CP/M prompt (ExtendMode + c on the ZX Spectrum +3
  keyboard, or LeftShift + LeftAlt + c in the FUSE emulator) to inform the
  system that the disk in the drive A: has changed.
• Run fidcsum spectran.fid command (as advised above) if you didn't do that
  before (it is safe to run it several time, the fidcsum command should inform
  you whether its execution was actually needed).
• Copy spectran.fid to the 3 inch disk in the B: drive (e.g. using pip3
  command, usually renamed to copy).
• Change A: disk image in Gotek back to your bootable CP/M Plus disk image.
• Press Ctrl + c in the CP/M prompt again.
• Copy spectran.fid from the 3 inch disk in the B: drive to your bootable
  CP/M Plus disk image by now back in the drive A:.

If your CP/M system has ramdisk configured, it is recommended to use it for this
copying operation instead of engaging the B: floppy drive.

Usage

This driver should initialize Spectranet device, hence it is recommended that
Spectranet firmware will not do that on power-up. Fortunately, it is possible
to prevent the firmware from starting. Just close both of the Disable onboard
jumpers. Also, the +2A/+3 jumper needs to be closed. A similar setup can be
established in the FUSE emulator.

When started, this driver initializes Spectranet device with its pre-configured
MAC and IP addresses. Then it tries to connect remote host with connect_ip at
two TCP ports: CONSOLE_CONNECT_PORT on which a telnet server
(e.g. stdiotelnetd) should wait for connections and DISK_CONNECT_PORT on which
the spectrand server (described below) should wait for connections.

This driver allows connection to a remote disk image registered as the N:
drive and a remote character device (e.g. serial console) registered as
SPCNET:. Namely, one can type:

> device aux:=spcnet

...to redirect AUX: to SPCNET: and use it as a serial port over ethernet,
which can be utilized by the CP/M's serial terminal programs like qterm (named
qtplus3 on ZX Spectrum +3's CP/M Plus).

Configure Spectranet device emulation in the FUSE emulator

Although FUSE emulartor can emulate Spectranet device quite well, it does not
provide any configuration option for providing its firmware at startup. Hence
it must be installed after each startup of the emulator.

I assume that FUSE emulates one of the CP/M Plus compatible machines:

• ZX Spectrum +3
• ZX Spectrum +3e

There are reports of succesfully running CP/M Plus on a ZX Spectrum +2A machine
equipped widh the Dandator device, yet this option is not yet available in
the FUSE emulator.

Note that usually the emulated Spectranet device's IP address is setup as
127.0.0.1, hence only the localhost to localhost connections are possible.
Effectively, connect_ip in this FID driver's source code must be also set as
127.0.0.1 if it is intended to run in an emulation.

Install Spectranet firmware in FUSE

There are two ways of obtaining the Sectranet firmware:

1. Download the installer.tap file from this address:
   http://spectrum.alioth.net/downloads/installer.tap.

2. Clone git repository from https://github.com/spectrumero/spectranet.git and build it from the sources.

In order to build the firmware from its sources, GNU as assembler (distributed
as a part of the binutils package) is needed. It must be able to target Z80
platforms, hence it's best to build binutils suite locally in the user's home
directory with the target flag specified to the configure script as follows:

$ configure --target=z80-unknown-coff --prefix=$HOME/z80-unknown-coff

After make and make install invocations, all the necessary build-time utils
should be installed into the $HOME/z80-unknown-coff directory.

To build Spectranet firmware (with the installer), enter the directory with its
cloned git repository and invoke make as follows:

$ PATH=$HOME/z80-unknown-coff/bin:$PATH make

This building process should create installer.tap file in the installer
directory.

Having installer.tap file ready to use, go to the
Options/Peripherals/Genral... menu in FUSE and tick both Spectranet and
Spectranet disable boxes. Reset the emulated machine (Machine/Reset...)
after that. From power-up menu (assuming this is ZX Spectrum +3 or +3e
emulation) select the 48 BASIC option. It should start the ZX Spectrum 48k
BASIC compatibility mode with the "(C) 1982 Amstrad" welcome message. As you
press the ENTER key, you should see usual ZX BASIC prompt.

Open the installer.tap file in the Media\Tape\Open... menu option. Enter the
following commands in the ZX BASIC prompt:

CLEAR 26999
LOAD "" CODE
RANDOMIZE USR 27000

You may not be familiar with 48k model keyboard on which every ZX BASIC command
has its own key assigned. These are keys that you need to use:

• x for CLEAR
• j for LOAD
• LeftAlt + p for the " character
• LeftShift + LeftAlt + i for CODE
• t for RANDOMIZE
• LeftShift + LeftAlt + l for USR
• LeftShift + 0 for backspace, if needed (although normal backspace key should
  also work as expected)

Entering above ZX BASIC commands should start the Spectranet firmware installer.
Successfull installation should end with a "0 OK, 0:1" status report.
Although the firmware should be installed by now, to make it useable it needs to
be configured. Go to the Options/Peripherals/General... menu and remove tick
from the Spectranet disable box. Reset the machine after that
(Machine\Reset...).

You can notice that no matter which machine FUSE emulates, with the Spectranet
device enabled it always resets to the 48k BASIC compatibility mode. Therefore,
in order to boot CP/M Plus, the device must be disabled again. But first, it
must be configured. The configuration routine is started by sending an NMI
interrupt. Select Machine/NMI menu option, it should start the
"Spectranet NMI menu". Press the 'a' key to open the network configuration
menu.

Two things need to be configured: Hostname (as it is bunch of non-printable
rubbish by default) and the IP address. Press the h key and enter a new host
name (e.g. fuse) and press ENTER key to confirm that. Then press the b key
to enter the new IP address. In case of FUSE emulator it should always be
127.0.0.1. After entering it, press ENTER for confirmation. Back in the
network configuration menu, press 'i' key to save the changes. Back in the main
NMI menu, press 'e' to exit. You may notice that pressing e entered the REM
command into ZX BASIC prompt. Press backspace (or LeftShift + 0) to erase it.

Enter following two commands to commit the configuration changes:

%cfgnew
%cfgcommit

Note that you need to press LeftAlt + 5 for the % character.

Now you can go to the Options/Peripherals/General... menu and tick the
Spectranet disable box. Reset the machine after that
(Machine\Reset...). Usual +3 power-up menu should appear. Your machine
is now ready to boot CP/M from drive A: (go to the
Media\Disk\+3\Drive A:\Insert... menu option and pick the bootable CP/M Plus
image to which spectran.fid file prepared earlier was copied).

Unfortunately, in the most recent version of the FUSE emulator there is still
no way to correctly record a snapshot of this state of the emulator, hence those
steps need to be repeated on every start of the FUSE emulator.

The spectrand server

As mentioned before, during its initialization, the specranfid driver tires to
establish two TCP connections: a telnet connection at TCP port 2423 and a
remote disk connection at port 2424 (both these ports can be changed in the
FID driver source code). For handling telnet connection, any telnet server
should be sufficient, e.g. see the stdiotelnetd project based on the libtelnet
library. As for remote disk connection, the spectrand server program can be
used. It is the other part of this project, see spectrand directory.

To build spectrand executable file, just invoke make command in the
spectrand directory of this project. To start this server, execute spectrand
with two parameters: TCP wait port and a file name holding an CP/M disk image,
e.g.:

$ ./spectrand 2424 formatted.rawimg

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 fillowing make command
invocation (started in the spectrand 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).