emulators.tex

\chapter{Emulators}

At the time of writing, there is only one emulator for the MEGA65, \stw{xmega65}, from
LGB's Xemu emulator suite. The developers of this emulator are working hard to keep up
with the development of the MEGA65. Thus some aspects of the MEGA65 may not be perfectly
emulated. However, it is typically sufficient for developing software for the MEGA65.
To be safest, you should always test software regularly on real hardware, whether that
be on a MEGA65 computer, or on an FPGA board which is capable of running a MEGA65 core.

The source code for the MEGA65 emulator can be
downloaded from \url{https://github.com/lgblgblgb/xemu}.
Pre-compiled version can be downloaded from \url{https://github.lgb.hu/xemu/}.
There is also a live ISO image containing the emulator, documentation and
other tools.  The link to this ISO image can be found in on \url{Forum64.de}
at \url{https://www.forum64.de/index.php?thread/104698-xemu-live-system-iso-file/\&postID=1549927\#post1549936}.

\section{Using The Xmega65 Emulator}

\section{Using the Live ISO image}

The Live ISO image is the product of volunteers in the community. The MEGA65
team are not responsible for it, but we document it here for your convenience.

\subsection{Creating a Bootable USB stick or DVD}

The first step is to create the live ISO image.  The method for doing
this will depend on your operating system, and whether you wish to install
it on a USB stick, or burn it to a DVD.  Burning to a DVD is straightforward,
assuming you own a computer that has a DVD writer.  If you don't, or if you
wish to in any case make a bootable USB stick, e.g., because it will boot
faster than a DVD, you will need to use an appropriate tool to make a bootable
USB stick from an ISO image.  If you are using Windows, you might consider
a tool like \url{http://www.isotousb.com/}.  On Linux, you can use the instructions
at \url{https://fossbytes.com/create-bootable-usb-media-from-iso-ubuntu/}.
For Apple Macs, you might consider the information at
\url{https://ubuntu.com/tutorials/create-a-usb-stick-on-macos#1-overview}.
Similar instructions are available for other popular computers, such as Amigas (\url{https://forum.hyperion-entertainment.com/viewtopic.php?t=3857}), or Sun UltraSPARC workstations (\url{https://forums.servethehome.com/index.php?threads/how-to-create-a-bootable-solaris-11-usb.1998/}).

\subsection{Getting Started}

To avoid any potential problems with copyright, the bootable ISO image does not
include any proprietary ROMs for the MEGA65, such as the legacy C65 ROMs.
It does include an open-source replacement ROM from our OpenROMs project.\index{OpenROMs}
This is sufficient to boot into a BASIC 2 like environment, that can be used
to load and execute many C64 programmes.  It will result in a display like the following:

\screenshotwrap{images/liveiso-openrom.png}

However, if you wish to use a C65
ROM and its included BASIC 10, you will need to download the appropriate ROM file,
and place it on another USB stick, and named \stw{MEGA65.ROM}. The Live ISO
will prompt you on start-up to ask if you have such a file already downloaded:

\screenshotwrap{images/liveiso-rom-usb-prompt.png}

If the Live ISO cannot find this file, it will ask you if you would like
for it to automatically download such a ROM for you, as can be seen below:

\screenshotwrap{images/liveiso-rom-download-prompt.png}

Naturally you will need to have an internet connection available for this to work.

\subsection{Other Features of the Live ISO}

As the previous screen-shots show, the Live ISO provides various desktop shortcuts
for your convenience.  On the left-hand side, we see shortcuts for launching the
MEGA65 emulator, and also the C65 emulator, if you wish to check if your programmes
can run on a standard C65 computer.  As previously mentioned, both emulators are
works in progress, and thus may not be 100\% faithful in all aspects of their emulation.

Next we have a link to the MEGA65 Book, which is the all-in-one volume containing the
almost 800 pages of all official MEGA65 documentation.
The majority of this developer's guide is also present in the MEGA65 Book.

Below this, there is documentation for the C65 Notepad, a programme for the C65 and MEGA65
written by Snoopy, who also prepared the Live ISO image.  A ``read me'' file is also provided,
that contains further information about the Live ISO.

Finally, there is a link to access the contents of the Live ISO image via the file
explorer, should you wish to do so.

Then on the right-hand side, there are links to download a C65 ROM, and to update the
MEGA65 Book to the latest version, so that you don't need to create a new bootable image
each time the MEGA65 Book is updated.  This is very helpful, as the MEGA65 Book continues
to grow and evolve.