--------------------------------------------------------
             Gavare's eXperimental Emulator   --   GXemul 0.6.2
          --------------------------------------------------------


                   Copyright (C) 2003-2019  Anders Gavare


Overview  --  What is GXemul?
-----------------------------

GXemul is a framework for full-system computer architecture emulation.
Several processor architectures and machine types have been implemented.
It is working well enough to allow unmodified "guest" operating systems to
run inside the emulator, as if they were running on real hardware.

The emulator emulates (networks of) real machines. The machines may consist
of ARM, MIPS, Motorola 88K, PowerPC, and SuperH processors, and various
surrounding hardware components such as framebuffers, busses, interrupt
controllers, ethernet controllers, disk controllers, and serial port
controllers.

GXemul, including the dynamic translation system, is implemented in portable
C++, which means that the emulator will (at least in theory) run on
practically any modern host architecture and unix-like operating system, for
which a C++ compiler is available.

The documentation lists the machines and specific guest operating systems
that can be regarded as "working" in GXemul. The guest operating system
that works best in GXemul is NetBSD/pmax on an emulated DECstation 5000/200.


Possible uses of GXemul include:

 o)  running guest operating systems in a "sandboxed" environment

 o)  compiling your source code inside a guest operating system which you
     otherwise would not have access to (e.g. various exotic ports of
     NetBSD or OpenBSD), to make sure that your source code is portable to
     those platforms

 o)  educational purposes, e.g. to learn how to write code for MIPS

 o)  hobby operating system development; the emulator can be used as a
     complement to testing your code on real hardware

 o)  preservation of computer history, by simulating old/obsolete hardware

 o)  simulating (ethernet) networks of computers running various
     operating systems, to study their interaction with each other

 o)  debugging code in general


GXemul's limitations
--------------------

 o)  GXemul does not simulate micro-architectural things such as pipe-line
     stalls, instruction latency effects, out-of-order execution etc.

 o)  CPUs and other hardware devices have been implemented in an ad-hoc and
     as-needed manner, usually only enough to fool guest operating systems
     such as NetBSD into believing that the hardware devices exist and
     function well enough for the guest operating systems to use them.

     (A consequence of this is that a machine mode may be implemented well
     enough to run NetBSD for that machine mode, but other guest operating
     systems may not run at all, or behave strangely.)


Quick start
-----------

To compile, type './configure' and then 'make'. This should work on most
Unix-like systems. If it does not, then please mail me a bug report.

If you are impatient, and want to try out running a guest operating system 
inside GXemul, read this:  doc/machine_decstation.html#netbsdpmaxinstall

If you want to use GXemul for experimenting with code of your own,
then I suggest you compile a Hello World program according to the tips
listed here:  doc/experiments.html#hello

Please read the rest of the documentation in the doc/ sub-directory for
more detailed information on how to use the emulator.


Feedback
--------

If you have found GXemul useful in some way, or feel like sending me
comments or feedback in general, then mail me at gavare@gmail.com.