MEGA65 emulator for testing

Using Xemu for MEGA65 as a testing tool

Foreword/warning

Please note, that some of the options here are not so much well tested and can be buggy or even defunct. Also, there can be serious conflicts between some options. Unfortunately this area of the emulator is the least used in general, so it gives too little love from me, because of my limited free time for my Xemu hobby project. Anyway, any bug reports are welcome, though I cannot promise in advance that I can deal with those "ASAP" or "at all" in some cases. Thanks for the understanding.

Custom configuration file

This document contains lots of CLI options. In some cases it's annoying to use a large command line, hard to overview and maintain. So some can use a custom configuration file as well. For this to wok, you need some CLI switches anyway:

-skipconfigfile -config FILENAME.cfg

The first -skipconfigfile option (note: if this switch is used, it must be the first switch) causes not to read/use the default config file which may override some of your settings in your custom file. The -config FILENAME.cfg part instructs the emulator to load/use the specified file as the config file.

The format of the config file is simple. Lines starting with # are comments, otherwise the format:

gui = osd
besure

for example. The first line is the same as -osd gui in command line (you can see, the initial - is not used in config file). The second line is a format, when the switch is "boolean" kind, ie does not require a parameter.

Generic useful switches

• -besure causes to answer "Yes" automatically for "Are you sure?" kind of prompts from the emulator
• -hickup FILENAME loads an external HYPPO, instead of Xemu's built-in one. Beware, Xemu is not very well tested with newer HYPPO versions!
• -rom FILENAME instructs Xemu to use the given file as the ROM, must be a 128K valid C65 or MEGA65 ROM image
• -gui GUINAME selects GUI for Xemu, can be useful in some cases to avoid GUI stuff, like with -gui none. Also in general -gui osd can be interesting (but not so much for testing) it causes the internal emulator screen is used to draw the GUI instead of using things like GTK2 or native windows/Mac GUI (specify -gui osd and then right click into the emulator window ...)
• -extbanner -extchrwom -extcramutils -extflashutil -extfreezer -extinitrom -extonboard: all of these needs filename as parameter! These CLI options load external binaries instead of Xemu's built-in ones. In most cases people don't ever needs these
• -skipunhandledmem can be useful if you are not interested in getting Xemu warning windows on referencing memory areas which are not decoded (ie "nothing there"). In 99.99% of cases these kind of events are bugs, so it's enabled by default to help people to find bugs (real MEGA65 would not warn you of course)

Loading programs automatically

• -8 FILENAME.D81 does not load anything, but attaches a disk image automatically. The same description goes for the -9 FILENAME.D81 option
• -autoload automatically loads the first program from the attached disk image
• -prg FILENAME injects a program directly into a memory and RUNs it, but it should be a BASIC program or at least an ML program with the "BASIC stub". Detecting C64 ("GO64") or C65/M65 is automatic based on the load address of the PRG (two first bytes). Auto detection can be overridden with an additional option: -prgmode n where n must be 64 or 65
• -importbas FILENAME imports a BASIC program from ASCII text form. Beware, this is very much not tested well, and problematic because of the upper/lower case problems, and special PETSCII characters. It may also conflict with -8 as it uses an in-memory D81 to do the trick utilizing BASIC65's ability to load a SEQ type text file as a BASIC program rather than a tokenized one

Headless mode

Sometimes the testing is done from script, and output is also parsed automatically, thus you don't need or want the emulator window at all. You can achieve this with the -headless CLI option.

Speed control

Often, it's more desired the test to run quickly, more quicker than real-time emulation. For this, two CLI options are provided:

• -fastboot causes to shorten the time needed for HYPPO to initialize the machine (running the emulation as fast as possible by your PC/Mac), but as soon the ROM code starts to run, real time emulation speed is restored
• -sleepless causes the entire emulation to run as fast as possible, not just the "boot" part
• -fastclock N sets a given MHz value for "fast" clock, ie the standard 40.5MHz MEGA65 usually have in fast mode can be overridden this way

Do not use the two option together, which would not make sense either, as -sleepless covers both the HYPPO init, and rest of the emulation session already.

Exiting the emulator by the test software

Option -testing must be set for this to work! The reason is security, do not allow normally for random programs to make the emulator exit (either by will, or by chance).

If -testing is used, storing value $42 into register $D6CF will cause Xemu to exit. If -testing is not used, this would be an "FPGA reconfiguration" request on the real MEGA65, but for the emulator (as it's a software, not an FPGA) it means restarting emulation (exit only happens with -testing, again).

Sending information from emulation to the outside world

For sure, you may want to create some sort of information during testing, which can be examined later. Some of the possibilities:

• Attach a disk image with -8 and save a file on it by the test program. You can then extract that file and process
• Use the -dumpmem FILENAME CLI option to dump the content of the "fast" RAM on exit, then you can process the memory content later
• Use the -dumpscreen FILENAME CLI option to dump the content of the screen in form of ASCII to file, which can be processed later. Of course it makes sense only if the screen was in text mode originally, also the screen code to ASCII conversion can cause problems. Probably you may want to use -dumpmem FILENAME in most cases when you're free to parse the memory content as you wish
• Use the -screenshot FILENAME CLI option to save a PNG file (of the screen) on exit
• Use the -hyperserialfile FILENAME CLI option to save the content written to the "hyper serial port" to a file. You can also specify the -hyperserialascii switch to instruct the emulator to convert stored data into ASCII, however it can causes unwanted results depending on the nature of the written data

The last one is probably the most mystical as the first glance. There is a HYPPO trap which can write that port, thus you must utilize that.