Skip to content

targets mega65

Jump to bottom
LGB edited this page Feb 9, 2021 · 36 revisions

The Mega65 emulator of Xemu

Beware, this is a highly OUTDATED and OLD page, which is here only for some still relevant references. You can be about 99.9999% sure that you want to visit this link instead (especially if you are not involved in Xemu development, ie being a "regular user"): https://github.com/lgblgblgb/xemu/wiki/MEGA65-quickstart

This is about Mega65, to learn more, visit this site: http://mega65.org/

Please read this page before you try to use Xemu/Mega65.

M65 project status - M65 C65 emulator differences explained

Mega65 target is a slightly modified Commodore 65 emulation. WARNING: This is NOT a full Mega65 emulation but only the minimal feature sub-set of Mega65 which is enough for some purproses, like Kickstart ROM development and debugging. Do NOT expect that it runs Mega65 specific software in general (at least not yet ...)!

Mega65 mode is only used if the emulator can load KICKUP.M65 (case sensitive name ... at least on UNIX like machines). You should have one, placed into the rom/ directory for example (or the current directory, xemu tries different places, see emu_load_file() function in common/emutools.c about this). Without KICKUP.M65 the machine boots and functions like a C65, even C65GS I/O keying won't be supported (however this mode is not tested too much, for this, please use the c65 target instead of this one).

You must also provide an image file of the SD-card for the Mega65. The file name should be mega65.img with the same rules of placement as with KICKUP.M65 for sure. This is a simple image file, really. On UNIX-like system, you can even try to symlink the device node of a real SD-card reader, but be careful with the access rights, so Xemu can open it at all. Without this image Kickstart won't be able to use the emulated SD-card controller normally, of course. Please visit the "Download" section for a working SD-card image.

In theory, there is Makefile support (in directory rom) for creating an SD-card image, but it's better to ignore it for now, and provide a really working one :)

Important: logging

Xemu does some ugly printf's throughout the code. Almost all converted to use the DEBUG() macro. By default it does not do anything, but it is not recommended to use this way, if the intent is developing. You may want to set environment variable XEMU_DEBUG_FILE to a file name (possible with path info). In this case, Xemu/Mega65 will use that file to write those crazy messages. That file can be used to fancy purposes, just one example:

$ XEMU_DEBUG_FILE=/tmp/debug build/bin/xmega65.native

(after exiting .. or even during the run, from another terminal, etc)

$ grep SDCARD /tmp/debug  | sort | uniq -c | sort -n
  1 SDCARD: cool, SD-card image mega65.img is open
  1 SDCARD: reading SD status $D680 result is $00
  1 SDCARD: reading SD status $D680 result is $04
  1 SDCARD: writing command register $D680 with $00
  1 SDCARD: writing command register $D680 with $01
  1 SDCARD: writing command register $D680 with $42
  1 SDCARD: writing command register $D680 with $81
  1 SDCARD: writing sector number register $D681 with $00
  1 SDCARD: writing sector number register $D682 with $00
  1 SDCARD: writing sector number register $D683 with $00
  1 SDCARD: writing sector number register $D684 with $00
 36 SDCARD: reading sector 0
 36 SDCARD: writing command register $D680 with $02
 73 SDCARD: reading SD status $D680 result is $08

Still, Xemu prints some more important information to stderr though.

NOTES

Mega65 target is basically similar (was forked from) my Commodore 65 emulator, however:

  • $D02F keying support for Mega65 mode
  • Some Mega65 specific I/O support
  • Hypervisor MAP mode, load/save machine state, hypervisor trapping
  • Custom built-in font for initial kickstart, taken from M65's VHDL
  • M65's kickstart can:
    • "boot" into C65 mode (including the loading of C65 ROMs, it's done by kickstart!)
    • upgrade itself from SD-card
    • hypervisor traps should work, but there are problems with disk chooser now
  • Internal 28 bit address bus implementation, with M65 specific extra MAP support (DMAgic should also work)
  • Loading KICKUP.M65 by the emulator (if it does not work, "simple C65 mode" will be used, without any Mega65 feature)
  • Super-ugly 16 bit text mode support to be able to see "something", currently only with incrementing video/colour pointers by two, but no extra data is interpreted at all.
  • Mega65 SD-card support (read only access is implemented) only with the absolute needed features
  • F011 FDC is still the same as C65 target's. It will try to access the D81 disk image file, if one is specified, and it has no connection with the SD-card stuff.
  • CPU speed is still C65's, there is no "Mega65-fast" mode and it would be also quite impossible with current Xemu because of performance problem (maybe with JIT-capable CPU emulation it would be?).

HIGH PRIORITY TODO

  • debug UART monitor interface support with more commands (still a valid issue, until it reaches the real Mega65)
  • debug UART monitor support should be tested with m65dbg better
  • There is no write support for SD-card at all
  • More VIC-IV features, starting with acceptable 16 bit text support
  • 28 bit JMP/etc support? ie "far jmp" stuff
  • Backtrace/CPU history support in case of hypervisor out-of-bound (of hypervisor memory) code execution?
  • F011 FDC implementation should use "emulated" stuff using the SD-card instead of the old C65's implementation for a discrete D81 image
  • Try to push speed up, I am not sure if 48MHz is possible at all without a brutal PC running the emulator on. Probably many parts of the emulation can be made much faster, but it's questionable if it's enough ... We will see.

Github issues page

Using the emulator

Before the first run, you may need some files, namely:

  • The mentioned KICKUP.M65 and mega65.img files in rom/ directory.
  • Commodore 65 ROM image is not needed, since kickstart will load it from the - emulated - SD-card as with a real Mega65! It also proves that emulation and card image is OK, that kickstart is able to provide you a working C65-like machine after a while.
  • You may want to place kickstart.list file into rom/ as well, so Xemu can use it for hypervisor debugging (note: if you do this, and kickstart.list does not match with KICKUP.M65, it will likely cause Xemu to "panic" as the hypervisor check feature may found misaligned code execution)
  • You can review and/or modify settings in mega65.h before compiling
  • Building the emulator in general, you need Linux or UNIX like (including OSX) machine for this. The emulator itself runs on Windows, but needs cross compiling done on Linux first to get your exe file! Please visit this page: Source to learn more about the compilation.
  • You may try to download build version already, to learn more: Download
  • Another limitation of using Windows: UART monitor feature won't work (see later).

Please read the section of "Important: logging" above! However on stderr you will get important information, you should watch while using a monitor connection! There are some hot-keys:

  • F9 to exit emulator
  • F10 initiates CPU reset, however this can be buggy, as no full Mega65 reset is done, merely the CPU stuff more
  • F11 toggles between full-screen/windowed mode

Title of the emulator window shows a value in percent. That is the used "real-time" for emulation. Ideally it should be a small value. Value of greater than 100% means that real-time emulation is not possible. The text "running" shows the emulator state, the other one is "TRACE/PAUSE" if Xemu/Mega65 is in tracing mode.

If you plan to hack the source, you should change directory into targets/mega65, you can say make there, after some modification. The Makefile also supports building and running emulator in a single step for easier work, you can say make run, which will build the Mega65 target (if needed) then it also runs it, with debug messages enabled to file debug.log (however, note, that the file itself will be at the top directory of the project, not in the mega65 target's directory!).

Using Xemu/Mega65's UART-monitor

This feature tries to emulate the "UART monitor" capability of a real Mega65 system.

Still, it's in development phase, but you can try it. First, it needs Xemu compiled for UNIX, as Windows does not have standard socket interface, so it won't work. Xemu Mega65 target by default tries to open a named (UNIX domain) socket in the current directory with the name of uart.sock. Please note the chapter on stdout and stderr and redirection as well!

Then you need to connect to the mentioned socket. You can try that with minicom for example:

  • minicom -D unix#/directory/to/the/socket/uart.sock

Not only minicom is usable, in theory everything can be used which supports named sockets to connect to, for example with the quite common socat or netcat UNIX utilities:

  • socat - unix-client:/directory/to/the/socket/uart.sock
  • netcat -U /directory/to/the/socket/uart.sock

I've have a commit for m65dbg which supports the same, it also needs UNIX, and before the compilation you need to enable the UNIX domain socket support with editing serial.c near the beginning of the file (the #define may be commented out by default, thus wouldn't work with this modification). If you have this, you can try then (watch out the difference, minicom uses -D, while m65dbg uses -d for the same option ...):

  • m65dbg -d unix#/directory/to/the/socket/uart.sock.

Please note, that only a ONE client can be connected to the socket, so it won't work, if a process is already connected!

Supported commands and notes:

  • I am not sure if my implementation is compatible with Mega65 ...
  • There are no line editing functions (maybe backspace works, but re-issuing the previous command surely not), the solution can be using m65dbg, which has its own history mechanism and line editing with libreadline
  • r command shows registers, the title is from the VHDL, though not all information is displayed, or some of them are incorrect (ie MAPL/MAPH is handled as a trick in Xemu for hypervisor, and you can't see for real, etc)
  • d (dump of memory) command displays 16 bytes from a given hex (parameter) CPU address, that's all
  • t (trace) with parameter 0 or 1 disables/enables trace mode. In trace mode, the Xemu window title says "TRACE/PAUSE" instead of "running" (note: for performance reasons the title change may take max of 1 sec to be updated). In trace mode, you can issue t (without parameters) for a step, registers are displayed after the step (I am not sure if it's the same behaviour as with the real thing). An empty command (just hit enter) is the same as t but only, if you are in trace mode already.
  • b (breakpoint) command sets a breakpoint to a given PC value (in hex). When this PC hit, Xemu switches into trace/pause mode by its own, and this fact is also told on the stderr of the emulator. Note: even if you set a breakpoint, if you are already in trace mode, you need to exit (t0) so the execution can continue.
  • In case of execution code outside of $8000...$BFFF area in hypervisor mode, Xemu switches to TRACE mode by its own, and this fact is also told on stderr of the emulator. So you can examine the situation with the monitor. However, it would badly need the backtrace/CPU history feature implemented, to be really useful ... (also, since kickstart is not able to "boot" within Xemu yet, it's not so much useful feature)
  • Xemu is a single thread application. UART monitor is implemented with non-blocking I/O called from the main update loop, so sometimes it can be a bit slow. Please note, that SDL2 error/info dialog boxes stops the execution of the main program, so monitor won't respond either till you clicked on the window to acknowledge and close.
  • Hypervisor serial messages can be read on the stderr as well, they're displayed after \n or \r character received. In this case, Xemu's buffer is printed onto the stderr and flushed.
  • Every commands uses only "PC values" ie 16 bit. This can be a problem.

It seems even with only the r command, you can use m65dbg to learn where the execution is inside the kickstart with its dis command (if it can load its map files at least, if not, it can be a problem as it then uses the d command to get memory dump and disassemble, which is not well tested with Xemu yet).

INDEX PAGE

Build Status Gitter Download

Clone this wiki locally