ZMON Remote Command mode tool

This is a tool which works with Memotech boot ROMs which have the Remote Command feature built into them.

Usage

To see the usage of the tool :-

$ ./remcmd -?
usage: remcmd {flags}
flags: -t tty     set tty (default /dev/ttyS0)
       -p port    set port (default 0x00)
       -v value   set value (default 0x00)
       -s addr    set MTX src address (default 0x0100)
       -d addr    set MTX dst address (default 0x0100)
       -x addr    set MTX exe address (default 0x0100)
       -g d:t     set drive letter:config (default B:03)
       -f fn      set local filename (default remcmd.dat)
       -l length  set length (default 0x0000)
       -c         toggle compressed read/write mode (default uncompressed)
       -F         send file (good for testing connectivity)
       -X         send to MTX dst in Intel Hex and jump to MTX exe address
       -I         input from port
       -O         output value to port
       -R         read length bytes from MTX src address and write to file
       -W         read bytes from file and write to MTX dst address
       -G         read length bytes from MTX RAM Disc and write to file
       -P         read bytes from file and write to MTX RAM Disc
       -D         read length bytes from MTX Disc and write to file
       -S         read bytes from file and write to MTX Disc
       -C         copy length bytes from MTX src to MTX dst
       -J         jump to MTX exe address
       -K         call MTX exe address

There is a general pattern that lower-case options set values which are used by upper-case command options that follow them.

On Windows, the default tty is COM1.

Examples

To test your RS232 null modem cable between your PC and MTX serial port B, interrupt the MTX boot ROM and run command D (aka the "Dialog" command), and then run :-

$ ./remcmd -f somefile.txt -F
send(somefile.txt)

As a result, the file content should appear on the MTX screen.

If you have a file you wish to download and execute, interrupt the MTX boot ROM and use command R (aka the "Read and Run" command). Then you use a command like this :-

$ ./remcmd -f ALPHA.COM -d 0x0100 -x 0x0100 -X
send_intel_hex(ALPHA.COM,0x0100,0x0100)

This transfers the file in the flavor of Intel Hex format that the boot ROM understands. Intel Hex format is a textual format, and so is not the fastest way to do this - a faster way is shown later.

The following commands require that you interrupt the MTX boot ROM and use the C command (aka the "Remote Command mode" command).

To input from an MTX port, eg: from port 0x03 :-

$ ./remcmd -p 0x03 -I
in(0x03) -> 0x78

To output to an MTX port, eg: program the memory mode in which ROMs are visible and ROM 2 is selected) :-

$ ./remcmd -p 0x00 -v 0x20 -O
out(0x00,0x20)

To read MTX memory to a file (assuming you ran the previous command to set the page port) :-

$ ./remcmd -s 0x2000 -l 0x2000 -f copy-of-rom-2.bin -R
read(0x2000,copy-of-rom-2.bin)

To write into MTX memory (assuming you'd set the page port back to 0x80) :-

$ ./remcmd -f ALPHA.COM -d 0x0100 -W
write(ALPHA.COM,0x0100)

To read from the memory areas used for RAM Disc, assuming a type 52 320KB sized RAM Disc (-G is for "get"):-

$ ./remcmd -l 327680 -f ramdisc.mfloppy-52 -G
read_ramdisc(ramdisc.mfloppy-52)

To initialise the RAM Disc from a local file (-P is for "put") :-

$ ./remcmd -f ramdisc.mfloppy-52 -P
write_ramdisc(ramdisc.mfloppy-52)

Note that the -G and -P functions are just convenient ways to automate the setting the MTX page port and read/writing chunks of data from/to RAM Disc pages.

To read from a normal MTX Disc to a local file (-D is for "dump") :-

$ ./remcmd -g B:07 -l 655360 -f boot.mfloppy-07 -D
read_disc(boot.floppy-07)

To initialize a (formatted) MTX Disc from a disc image (-S is for "store") :-

$ ./remcmd -g B:07 -f boot.mfloppy-07 -S
write_disc(boot.mfloppy-07)

Note that the -D and -S functions are just convenient ways to automate calling the boot ROM routines for configuring, reading and writing discs, combined with transferring the data in or out. They only transfer complete 128 byte sectors.

To copy memory from one location to another inside the MTX :-

$ ./remcmd -s 0x2000 -d 0x4000 -l 0x2000 -C
copy(0x2000,0x4000,0x2000)

To execute a specific location, by jumping to it :-

$ ./remcmd -x 0x0100 -J
jump(0x0100)

To execute a specific location, calling it and returning the value of the A register afterwards :-

$ ./remcmd -x 0x0100 -K
call(0x0100) -> 0x12

Multiple commands can be executed one after another, so you should see that this example is similar to the previous Intel Hex example, only faster :-

$ ./remcmd -f ALPHA.COM -d 0x0100 -W -x 0x0100 -J
write(ALPHA.COM,0x0100)
jump(0x0100)

Of course, after jumping to code, control will not return to the boot ROM, and no further commands can be issued.

The data transfer between PC and MTX performed by the -R, -W, -G, -P, -D and -S commands can be uncompressed or run-length compressed. This is enabled or toggled using the -c flag. So the following can be a much quicker way to initialise the RAM Disc :-

$ ./remcmd -f ramdisc.mfloppy-52 -c -P
write_ramdisc(ramdisc.mfloppy-52)

As an example, the 320KB RAM Disc image used on REMEMOTECH takes 194s to transfer uncompressed, but only 143s compressed. For mostly empty RAM Disc images with only a few files on them, the difference could be much larger. A RAM Disc image comprised completely of zeros transfers in 11s.

Transfers to and from real (not RAM) discs are slow with or without compressed data transfer, but it should help somewhat.

Memory ranges

When the Remote Command mode is running in the boot ROM, the ROM itself has been copied to above 0xe000 in memory and is running there. The stack is at 0xe000 growing downwards. In addition, when using the -D and -S commands, a 128 byte sector buffer is used at 0xdf00. Therefore safe areas to write to should really be below 0xdf00.

Because the code and stack is above 0xc000, it is safe to program the page port register to any value you like, making it possible to read ROMs as well as read/write RAM. This is part of what allows the put/get RAM Disc commands to work as they do.

Why does this tool exist?

Consider that PCs with floppy disks are getting harder to find. USB floppy disks have simpler controllers and are only able operate in the usual PC compatible disk formats, not the formats used by MTX drives. So this creates a problem of how to transfer data to and from MTX floppy discs.

One solution is to use an FDX or SDX which has a boot ROM that supports RAM Disc and the Remote Command mode, and which has RAM Disc.

To transfer data to the MTX floppy, interrupt the boot ROM, use the C command, then use the -P command to put a RAM Disc image into RAM Disc memory. You can then reboot to the RAM Disc and copy content from it to the floppy.

To transfer data from the floppy, boot either from floppy or RAM Disc and copy the files you care about to the RAM Disc. Then reboot and interrupt the boot ROM and use the C command, and then use the -G command to get the RAM Disc memory to a PC RAM Disc image file.

This solution works even if you don't have bootable floppy disks to start with, because you download a bootable RAM Disc image.

Helpfully a type 52 320KB RAM Disc has the exact same disk layout as a type 03 320KB floppy disc image.

Even if your MTX does not have RAM Disc, you can still use this tool. Instead you read or write to the disc surface directly using the -D and -S commands.

Download

This code can be downloaded from http://www.nyangau.org/remcmd/remcmd.zip.

Copying of this program is encouraged, as it is fully public domain. Even the source code is included in the package. It was created on the authors time and equipment. Caveat Emptor.

The author of the code and this documentation is Andy Key (email andy.z.key@googlemail.com).

{{{ Andy