Porting ZXZVM

ZXZVM is composed of two modules: a machine-independent interpreter core and a machine-dependent front end. If you want to port it to another system, it should be sufficient to write a new front end.

In all existing systems, the interpreter core loads at 7000h (though this could easily be changed by reassembling vm.zsm at a different base address). If you do change this, then you'll have to adjust any addresses below in the 7000h-70FFh range.

The addresses used by the front ends differ depending on the host system.

The jump table

The key to the interface between the two components is the jump table. This is described in the source file in_zxzvm.inc; it is located at address ZJT, which is 0E020h under ResiDOS and 04000h in the other versions. The table has 41 functions, covering access to Z-machine memory, screen I/O and file I/O.

Startup

In the Spectrum version, the startup code is in the form of a short BASIC program that loads the two machine-code modules and jumps to the interpreter entry point at 7000h. In the two PCW versions, the startup code is incorporated in the front-end programs (JOYCEIO.COM and ANNEIO.PRG respectively). Either way, the startup code loads both modules into memory and makes a call to 7000h.

Memory from 705Ch-70FFh can be used to store parameters for the front end, such as the filename to load or (in the case of the Spectrum versions) which font to use. The front end initialisation will be called with DE holding the address of this area. Memory from 7003h-705Bh is reserved for parameters for the interpreter itself. Currently, only the byte at 7003h is used; it holds the system type. This is usually 7 (Commodore 128), though the PcW16 front end sets it to 2 (Apple IIe).

Pretty much the first thing the interpreter core does is call the code at ZJT, to initialise the front end. At this point the front end would load some or all of the Z-code file (either using the filename at 705Ch, or asking interactively), initialise the screen, and so on.

Z-Memory

The Z-machine has 64k of RAM and up to 448k of ROM. Representing all of this in the Z80's 64k address space along with the two ZXZVM modules and the host operating system can be something of a challenge.

The Spectrum +3 version allocates memory as follows:

• 0000-3FFF: BASIC ROM
• 4000-5AFF: Front end
• 5B00-6AFF: BASIC loader and Z80 stack
• 6B00-6FFF: 32-column fonts
• 7000-BFFF: Interpreter core and Z-machine stack
• C000-FFFF: Banked memory. Banks 0,1,3,4 hold the first 64k of Z-machine address space; Bank 6 holds the +3DOS sector cache; and Bank 7 holds the video RAM and +3DOS working buffers.

The ResiDOS version allocates memory as follows:

• 0000-3FFF: Banked memory - BASIC ROM, or buffered sections of the story file
• 4000-5AFF: Video RAM
• 5B00-6AFF: BASIC loader and Z80 stack
• 6B00-6FFF: 32-column fonts
• 7000-DFFF: Interpreter core and Z-machine stack
• E000-FFFF: Front end

The PCW10 version allocates memory as follows:

• 0000-00FF: CP/M Zero Page
• 0100-1FFF: Front end
• 2000-3FFF: Unused
• 4000-407A: Jump table
• 407B-6FFF: Unused
• 7000-(BDOS-768): Interpreter core and Z-machine stack.
• (BDOS-768)-BDOS: Z80 stack
• The entire story file is loaded into the PCW's banked memory (normally used to provide a RAMdisc); 16k blocks are paged into the C000-FFFF range as and when required.

The PcW16 version allocates memory as follows:

• 0000-3FFF: Reserved by operating system.
• 4000-6FFF: Front end.
• 7000-FFFF: Interpreter core and Z-machine stack.
• The entire story file is loaded into the PCW's banked memory, as for the PCW10.

Note that with all of these systems, there is at least 64k of extra banked memory containing the Z-machine's RAM. This isn't to say that all implementations must use banked memory; it's just that if banked memory isn't available, you'll have to find some other way of getting the same effect. Swapping to floppy may not perform well enough.

Screen model

The existing implementations all use screen drivers which can position the cursor, do reverse video (and in some cases other special effects), erase a line, and scroll a number of lines at the bottom of the screen while leaving the top untouched. In addition, the PCW10 and Spectrum front ends use software font redefinition to provide the Beyond Zork graphics font.

Colour support in ZXZVM is untested as none of the existing front ends implement it.

Timer

Versions 4 and later of the Z-machine allow text input to be interrupted by a timeout. Ideally your system should have a clock with 1/10 sec resolution; the PCW10 version uses the CP/M 3 clock and therefore has a 1 sec resolution.

Filesystem

ZXZVM's demands on the filesystem are fairly modest (apart from anything else, it has to support the PcW16, a system that allows at most two files open at any one time). For Z-machine file operations, it doesn't require anything fancy; just the ability to open a file and do sequential reads or writes.

If there isn't enough memory available to hold the whole gamefile, then you will have to write a virtual memory system capable of paging bits of it in and out as required. Under these circumstances, such features as random access will become necessary.

Exercises for the interested reader

• Add full colour support to the Spectrum 32-column version.
• Create other Spectrum output modes - perhaps 42-column like The Hobbit, or 51-column like +3 CP/M.
• Write a generic CP/M front end. This is probably best accomplished by starting with the PCW10 one (joyce*.zsm) and removing the dependencies on PCW hardware and banked memory.
• Port to other processor architectures. I've experimented in the past with versions for the 8080 and 8086 processors, using automated conversion tools for most of the work.

John Elliott 2006-05-05