MEMU requires that you specify in some detail what code/data gets uploaded into what locations in the memory map.
It also requires that you pick what is emulated, and how well.
In the following examples we assume memu
(or memu.exe and portaudio_x86.dll on Windows)
is already on the PATH.
Run with no arguments to see the usage :-
$ memu
usage: memu [flags]
flags: -iobyte iobyte specify IOBYTE (initially 0x00)
-subpage subpage set ROM subpage register (initially 0)
-addr addr set the address (initially 0x0000)
-mem file load file at address
-mem-blocks n number of 16KB memory blocks (default 4)
-mem-mtx500 equivelent to -mem-blocks 2
-n-subpages rom n set number of subpages
-romX file load ROM X from file
-rompairX file load ROM X and X+1 from file
-vid-win emulate VDP and TV using a graphical window
-vid-win-big,-v make window twice as large (realistic size)
-vid-win-hw-palette use an alternate palette
-vid-ntsc refresh at 60Hz (instead of 50Hz)
-snd-portaudio,-s emulate sound chip using portaudio
-snd-latency value instruct portaudio to use a given latency
-mon-win emulate 80 column card using a graphical window
-mon-win-big,-mw make window twice as high (realistic aspect ratio)
-mon-win-mono green screen monochrome
-mon-th,-mt emulate 80 column card using full screen text mode
-mon-console,-mc emulate 80 column card using console only
-mon-console-nokey keyboard status shows no keys pressed
-mon-ignore-init ignore writes to non-emulated registers
-kbd-remap remaps MTX keyboard (despite shift state)
-kbd-country n sets the country code switches to n (default 0)
-kbd-type string auto type keys in this string
-kbd-type-file fn auto type keys in this file
-joy,-j enable joystick support
-joy-buttons string define left,right,up,down and fire buttons
-joy-central n percentage off-centre to press direction
-serial1-in fn serial 1 input from file/device/pipe
-serial2-in fn serial 2 input from file/device/pipe
-serial1-out fn serial 1 output to file/device/pipe
-serial2-out fn serial 2 output to file/device/pipe
-sdx-tracks n specify tracks of first drive (default 80)
-sdx-mfloppy file specify .mfloppy file in SDX first drive
-sdx-tracks2 n specify tracks of second drive (default 80)
-sdx-mfloppy2 file specify .mfloppy file in SDX second drive
-sidisc-huge enable Silicon Disc huge mode
-sidisc-no-save don't save Silicon Disc content on termination
-sidisc-file n file specify Silicon Disc content for a drive
-prn-file file specify file to receive printer output
-tape-dir path .mtx files are in this directory
-tape-overwrite SAVE can overwrite an existing file
-tape-disable don't patch INOUT to LOAD/SAVE/VERIFY .mtx files
-tap-file fn specify ZX tape file (default memu.tap)
-sna-file fn specify ZX snapshot file (default memu.sna)
-cpm emulate CP/M BDOS
-cpm-drive-a path where CP/M BDOS finds A: files (default: .)
-cpm-invert-case invert between CP/M and host filenames
-cpm-tail tail construct CP/M command tail
-cpm-open-hack don't insist on EX,S1,S2,RC being 0
-sdx SDX support in ROM 5 (or -sdx3 for ROM 3)
-fdxb FDXB CP/M support
-speed hz set CPU speed (default is 4000000, ie: 4MHz)
-fast don't limit speed, run as fast as possible
file.com tail ... -cpm -iobyte 0x80 -addr 0x0100 -mem file.com
file.run -iobyte 0x00 -addr 0xAAAA (from header)
file.mtx subsequent LOAD/SAVE/VERIFY "" will use this file
Arguments are processed one at a time, allowing you to load up different files into different places in the address map. Then execution starts with the IOBYTE reflecting the most recently set value, and with PC set to the most recently set address value.
You can specify a .com or .COM file,
followed by the CP/M command line tail, at the end of the MEMU command.
If you do this, MEMU internally sets the IOBYTE to 0x80,
enables the CP/M support, loads the file at 0x0100, and executes it
from there.
Obviously you could acheive a similar effect by using a combination
of -cpm, -iobyte, -addr and
-mem, but this way saves on typing.
You can specify a .run or .RUN file,
at the end of the MEMU command.
If you do this, MEMU internally sets the IOBYTE to 0x00 and starts
executing MTX BASIC from 0x0000.
However, it patches it so that once MTX BASIC is initialised, it will
disable interrupts, load the file contents into memory, and execute it.
Obviously you could acheive a similar effect by using a combination of
of -iobyte, -addr and -mem,
but this way saves on typing and works with more files.
This is because certain .RUN files are dependant on MTX
BASIC having initialised and set up variables in high memory.
Simply loading the .RUN file into memory and executing
it would bypass that initialisation.
You can specify the name of an .mtx or .MTX
file, at the end of the MEMU command.
If you use LOAD "" from MTX BASIC, this is the file
that will be read.
If you haven't specified an .MTX file, then
LOAD "" will attempt to load default.mtx
from the current directory.
If you use LOAD "Something", then MEMU will
attempt to load Something.mtx from the current directory.
Specifying the name of the file on the command line neatly avoids the
tape program name limitation in MTX BASIC (many of the .mtx
files have very long names, but MTX BASIC can only load a file with
upto 15 characters in its name).
SAVE and VERIFY will use the same filename.
MEMU cannot overwrite an existing .mtx file,
unless the -tape-overwrite option is used.
This is to prevent damaging the samples supplied with MEMU.
Some of them don't auto-run when LOADed,
and If you run them, they attempt to SAVE a bad copy
of themselves on top of the original.
The -sdx installs SDX support.
You can then use commands such as USER LOAD "FILE.BAS" and
USER RUN "FILE.RUN" to load programs.
Because the SDX support builds on portions of CP/M code,
the -cpm-drive-a and -cpm-invert-case command
line options affect the mapping between SDX filenames and host filenames.
When typing into the video window (not the 80 column one), note that to type certain characters into the MTX keyboard, you must type different characters into the host PC keyboard. See the MTX Keyboard section of the Emulation page for further details. This isn't likely to bother you if you are using MEMU to play arcade style games.
MEMU has an auto-type feature, as described in the Auto-type section of the Emulation page. This can be handy to get games to auto-start.
There are additional command line options, described on the Diagnostics page, which are of interest when debugging Z80 programs, and when debugging MEMU itself.
The serial port features (DART emulation) is only present in the Linux version, as to be effective it relies on UNIX style named pipes.
To run MTX BASIC :-
$ memu -vid-win-big -snd-portaudio
Use LOAD "Program" to try to load a program called
Program from within the file called Program.mtx
in the current directory.
Use LOAD "" to load a program of any name from within the
.mtx file named on the command line, or from within
default.mtx.
An example using auto-type which avoids typing a LOAD command into MTX BASIC :-
$ memu -vid-win-big -snd-portaudio -kbd-type "<Wait20><ALPHALOCK>LOAD \"Snakes\"<RET>"
If you have a .RUN file, such as ALPHA.RUN
intended to be loaded at location 0x8100,
of length 0x3000 bytes, then the
first 4 bytes of the file will be 0x00 0x81 0x00 0x30,
and the actual 0x3000 bytes of machine code then follow.
You could load and run it like this :-
$ memu -addr 0x80fc -mem ALPHA.RUN \
-addr 0x8100 \
-vid-win-big -snd-portaudio
Or, you could let MEMU read the header and work out where to load the file, then run MTX BASIC initialisation, and then load and execute the program using :-
$ memu -vid-win-big -snd-portaudio ALPHA.RUN
Note: None of my games require you to use the second approach,
though obviously its preferrable from a typing point of view, but
certain files, such as HAWKWARS.RUN, BAKERY.RUN
and PACMAN.RUN seem to be dependant on MTX BASIC having done
its initialisation.
Or, you can let the SDX support handle it :-
$ memu -vid-win-big -snd-portaudio -sdx ROM 5 USER RUN "ALPHA.RUN"
Or, you could use the CP/M RUN.COM program :-
$ memu -vid-win-big -snd-portaudio RUN.COM ALPHA.RUN
To run a simple non-interactive CP/M program (such as my special enhanced directory listing program), using the host console as the monitor output :-
$ memu -iobyte 0x80 -addr 0x0100 -mem SDIR.COM \
-mon-console -cpm -cpm-tail '*.SAV' -fast
The -cpm-tail argument is 'quoted', to stop the host
shell from expanding it using globbing.
On Windows, it should be "double quoted".
We want it processed per CP/M FCB parsing rules.
Using the shorthand syntax :-
$ memu -mon-console -fast SDIR.COM '*.SAV'
Note the use of -fast as there is no need for this
program to run as slow as it does on a real FDX/SDX.
To run a CP/M program which uses the monitor (and keyboard) interactively, in a full screen text mode (such as my text mode adventure game) :-
$ memu -mon-th ORBCPM.COM
To run a CP/M program which uses the monitor (and keyboard) interactively, in a full screen text mode, and even prints special characters found on the 80 column card (such as a hypothetical chess program which makes use of the chess set characters) :-
$ memu -mon-win-big CHESS.COM
To run a CP/M program which does MTX graphics (but doesn't need the
monitor) and uses the sound chip, such as one of my games supplied in
.COM file format :-
$ memu -vid-win-big -snd-portaudio SMG2M.COM
Another CP/M game, this time displaying with a richer (and supposedly closer to the actual hardware) palette :-
$ memu -vid-win-big -vid-win-hw-palette -snd-portaudio QUASAR.COM
Some simple command line CP/M programs
(such as the CRCK44.COM file checksum calculator)
poll the keyboard as they run.
This is a problem when running with -mon-console, as it
will cause the emulation to suspend until a line of text is supplied.
The -mon-console-nokey argument can be used to ensure
that whenever the program checks key status, the answer is none-pressed.
This next example is what you'd use to start the MTX up and have it use a game on a ROM. Note the way we set the IOBYTE, set the address to where paged ROMs appear in the address space, load the ROM image, then reset the IOBYTE and address prior ready to start execution :-
$ memu -iobyte 0x70 -addr 0x2000 -mem alpha.rom \
-iobyte 0x00 -addr 0x0000 \
-vid-win-big -snd-portaudio
You might have to type ROM 7 from MTX BASIC to transfer
execution to the ROM, or it might have an autostart signature in it which
causes MTX BASIC to automatically select and jump to it.
An alternative shorthand way is to :-
$ memu -rom7 quasar.rom \
-vid-win-big -snd-portaudio
This technique has been used to load the NODE ROM into memory. It is thought the NODE ROM would usually sit in ROM slot 6.
ROM subpages are supported, see the Memory section of the Emulation page.
If you have any MTX ROM images (other than the 3 in every MTX, the SDX ROM and the NODE ROM), please send them.
Another example is the Danish piggy-back ROM. This was a 1KB ROM (repeating 8 times), piggy-backed on top of one of the other ROMs, wired to be selected as ROM 7. It redefines certain characters to be Danish glyphs, and it hooks the keyboard to change the behaviour of the control key with certain characters. It can be used like so :-
$ memu -rom7 roms/danish.rom \
-vid-win-big -snd-portaudio
Sometimes cassette tapes had a MTX BASIC loader, followed by a chunk of
machine code which was loaded to a particular address and then executed.
Some Continental Software cassette tapes were like this.
If you have a file of the machine code, which was loaded to
0x8000 and executed starting at 0x8400 you can :-
$ memu -addr 0x8000 -mem GAME.TAPEDATA \
-addr 0x8400 \
-vid-win-big -snd-portaudio
As an alternative to using MEMUs emulation of CP/M, you can run the real boot ROM (and SDX ROM) and CP/M itself, using the underlying keyboard, 80 column and SDX FDC hardware emulations :-
$ memu -rom4 roms/boot-type07.rom \
-rom5 roms/sdx-type07.rom \
-mem-blocks 36 \
-mon-ignore-init \
-sdx-mfloppy mfloppy/andy_sys.mfloppy \
-sdx-mfloppy2 mfloppy/games.mfloppy \
-mon-win-big -vid-win-big -snd-portaudio
This example is a fully loaded system, with 64KB base and 512KB extra memory and disks in both drives. The sample disk images also configure the extra memory as RAM Disc.
This approach is more authentic (in that you get to interact with
the CP/M prompt), but on the flip-side, it requires you to use tools like
cpmtools to read and write files in the .mfloppy disk images.
Another example, testing an 8MB SD Card partition from REMEMOrizer, by pre-loading it into a Silicon Disc :-
$ memu -rom4 roms/boot-type07.rom \
-mem-blocks 36 \
-mon-ignore-init \
-sdx-mfloppy mfloppy/andy_sys.mfloppy \
-sidisc-file 1 ../rememorizer/firmware/sddisc.bin \
-mon-win-big -vid-win-big -snd-portaudio
Then when it boots :-
A>CONFIG G:4F A>DIR G:
Note that the disk geometry for 8MB SD Card partitions (type codes 18 to 1F) and the 8MB Silicon Disc (type code 4F) are exactly the same, which is what allows the above trick to work.
Using MEMU's CP/M emulation :-
$ memu -fdxb -mon-win-big -vid-win-big -snd-portaudio FXDB.COM BOMBER.BAS
The -fdxb flag makes MEMU patch the FXDB binary so
that it invokes MEMUs CP/M emulation.
As a benefit, it can access files directly on the host filesystem.
Or, alternatively, use the full CP/M approach, and simply run
the SDX version of FDXB.COM, typically renamed as
SDXB.COM.
As a drawback, the files must be within .mfloppy disk images.