Skip to content

MEGA65 emulator for testing

Jump to bottom
LGB edited this page Dec 10, 2024 · 15 revisions

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.

It's also important to mention that certain features needs some "fake keys" pressed by the emulator itself (like with any "auto command" let it be -autoload or -prg for example). This is because automation can be done only this way, no ROM patching or PC value monitoring is possible (unlike with C64 emulators like VICE), since we have hundreds of different ROMs. So it's possible your program senses the RETURN key-press for example which was faked by the emulator. However a clever program anyway would ignore initial key-presses as with real hardware too it's possible the program "sees" the RETURN still user pressed after typing RUN.

Depending on the time when you read this, it's possible that certain features described by this documentation is not yet available in the master builds (aka "stable") but only in the next builds.

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

The -prg goodies

When you use the -prg FILENAME to start a program directly from command line, you have other neat possibilities. This can be used:

  • Run "unit tests" used by the MEGA65 project
  • For your own experiments when you need custom memory initialization and you don't have your loader ready yet, to do so at your own

The following CLI switches are only valid if you also use the -prg FILENAME switch.

-prgtest 'BIN1@8192;BIN2@$C000;SYS8192:RUN' (this is just an example of course) like syntax can be used to do custom memory initialization and configuration of the startup sequence. Without this switch the default for -prg is not having extra memory initialization and the default startup sequence is simply RUN. The string parameter of the -prgtest switch consists of sub-strings separated by ;. If a sub-string contains a @ character it specifies a memory initialization in the filename@address syntax. The address can be a straight number (base-10) or a $ prefixed hexadecimal (base-16) number. The address can be anywhere in the 256Mbyte address space of MEGA65, though the ROM area is write protected, so probably you can't overwrite it this way. The sub-string which does not have a @ is interpreted as part of the startup sequence which is sent for BASIC65, so it must be a command (or commands) valid for BASIC65. In this example it's SYS8192:RUN. Please note, that the startup sequence cannot exceed the number of screen columns - 1, as these commands are put on the screen with direct memory write and only a RETURN key press is faked for the emulator.

-prgexit is a boolean switch (it does not require a parameter). It will cause the emulator automatically exit if the READY. prompt appears on the screen again after the issuing the startup sequence. It's meant more for unit-testing when the result is passed through the hyper-serial port anyway, but the unit-test suite requires to walk through various tests automatically without human interaction.

Attic RAM initialization

CLI switch -initattic FILENAME can be used to initialize the content of the Attic RAM from a file. Please note, that the same can be done through the -prgtest feature (see above, "The -prg goodies"), which also allows to initialize any other part of the memory. However -initattic works without -prg as well, in all cases, while the -prgtest mechanism requires a program to be injected with -prg.

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. Note: it's totally different than -fastclock (see below) this option makes emulation to be felt faster, but programs inside still sees the same CPU clock, while -fastclock causes the CPU clock to be altered.
  • -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).

Also, there is the -prgexit possibility, please read the chapter "The -prg goodies" above for an explanation.

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.

Examples for (MEGA65) UNIT testing

Examples for executing tests written for MEGA65. This needs a file b65support.bin from the mega65-tools (https://github.com/MEGA65/mega65-tools/) repository which must be loaed to $15FE.

-prg program_to_test.prg -prgtest 'b65support.bin@$15fe;SYS$1600:RUN' -hyperserialfile b65tests.log

-prg program_to_test.prg -prgtest 'b65support.bin@$15fe' -hyperserialfile b65tests.log

The difference between the two forms, that the first one initializes b65support, while the second does not (default startup RUN). In theory the first is used by MEGA65 tests, but in some cases (like with https://github.com/MEGA65/mega65-tools/blob/development/src/tests/571-mcfix-test10.prg), the second is sufficient as the program itself does the SYS$1600. Note, the $1600 syntax here is not for Xemu (unlike the $15fe with the bin file), but it is understood by BASIC65. The -hyperserialfile option specifies a file to store the output of the hyperserial port which is used by the tests via the b65support.bin test "framework". It has a special (binary) format, which must be interpreted in similar way as with unit-tests for the MEGA65

For enhanced experience, you can add more options:

  • -prgexit causes the emulator automatically exits at the end of the test (assuming the test program returning to BASIC prompt!)
  • -fastboot causes to switch to "turbo" mode during HYPPO initialization (SD-card, etc), resulting in shorter test time
  • -sleepless causes the emulator to remain in "turbo" mode all the time. It's a great win for test speed (eg, with the 571 test it requires 1.5sec while normally it's 16sec) however some timing sensitive test may suffer. If this switch is used -fastboot is pointless, since it's "turbo" all the time
  • -headless causes the emulator not to show its window at all, probably better for automated testing

Further information:

INDEX PAGE

Build Status Gitter Download

Clone this wiki locally