# Usage

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
           -romX file           load ROM X 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-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
           -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 `LOAD`ed, 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.

## Example command lines

### MTX BASIC

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>"

### RUN files

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
    USER RUN "ALPHA.RUN"

Or, you could use the CP/M `RUN.COM` program :-

    $ memu -vid-win-big -snd-portaudio RUN.COM ALPHA.RUN

### CP/M programs

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.

### ROMs

This next example is my guess as to 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 0x60 -addr 0x2000 -mem alpha.rom \
           -iobyte 0x00 -addr 0x0000 \
           -vid-win-big -snd-portaudio

You might have to type `ROM 6` 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 -rom6 alpha.rom \
           -vid-win-big -snd-portaudio

This technique has been used to load the NODE ROM into memory.

ROM 2 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

### Raw tape data

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

### Full CP/M support

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.

### FDX Basic

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.