# GXemul: Introduction

Back to the index.

- Overview
- New vs Old framework
- Is GXemul Free software?
- How to compile/build the emulator
- How to run the emulator
- Which processor architectures does GXemul emulate?
- Which host architectures/platforms are supported?
- Emulation accuracy
- Which machines does GXemul emulate?

NetBSD/pmax 1.6.2 with X11
running in GXemul

### Overview:

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++ (although most parts are still legacy C-style code), which means that the emulator will run on practically any 64-bit or 32-bit Unix-like systems, with few or no modifications.

Devices and processors are not simulated with 100% accuracy. They are only "faked" well enough to allow guest operating systems to run without complaining too much. Still, the emulator could be of interest for academic research and experiments, such as when learning how to write operating system code.

The emulator contains code which tries to emulate the workings of CPUs and surrounding hardware found in real machines, but it does not contain any ROM code. You will need some form of program (in binary form) to run in the emulator. For some emulation modes, PROM calls are handled by the emulator itself, so you do not need to use any ROM image at all.

You can use pre-compiled kernels (for example NetBSD kernels, or Linux), or other programs that are in binary format, and in some cases even actual ROM images. A couple of different file formats are supported: ELF, a.out, COFF/ECOFF, SREC, and raw binaries.

If you do not have a kernel as a separate file, but you have a bootable disk image, then it is sometimes possible to boot directly from that image. This works for example with DECstation emulation, Dreamcast emulation, or when booting from generic ISO9660 CDROM images if the kernel is included in the image as a plain file.

Thanks to (in no specific order) Joachim Buss, Olivier Houchard, Juli Mallett, Juan Romero Pardines, Carl van Schaik, Miod Vallat, Alec Voropay, Göran Weinholt, Alexander Yurchenko, and everyone else who has provided feedback on previous releases.

### New vs Old framework:

Starting with GXemul 0.6.0, a new emulation framework designed from scratch is included. So far, only very few emulation modes have been rewritten to use this new framework; almost all emulation modes use the old (legacy) framework, which was developed in a more ad-hoc manner. The long-term goal is to rewrite everything to use the new framework.

(The documentation still largely refers to how things worked in the old framework.)

The new framework is described here.

### Is GXemul Free software?

Yes. the GXemul source code is released under a Free license. The code in GXemul is Copyrighted software, it is not public domain. (If this is confusing to you, you might want to read up on the definitions of the four freedoms associated with Free software, http://www.gnu.org/philosophy/free-sw.html.)

The main part of the code is released under a 3-clause BSD-style license (or "revised BSD-style" if one wants to use GNU jargon). Apart from the main code, some files are copied from other sources such as NetBSD, for example header files containing symbolic names of bitfields in device registers. They are also covered by similar licenses, but with some additional clauses. The main point, however, is that the licenses require that the original Copyright and license terms are included when you distribute a copy, modified or not, even if it is in binary form.

If you plan to redistribute GXemul without supplying the source code, then you need to comply with each individual source file some other way, for example by writing additional documentation containing Copyright notes. This has not been done in the official GXemul distribution, since it is in source code form and already includes the Copyright messages. You need to check all individual files for details. The "easiest way out" if you plan to redistribute code from GXemul is, of course, to let it remain Free Software and simply include the source code.

### How to compile/build the emulator:

Uncompress the .tar.gz distribution file, and run

    	$ ./configure
    	$ make

This should work on most Unix-like systems, with few or no modifications to the source code. Requirements are:

- A reasonably modern C++ compiler environment, including STL.

(Hopefully there are no GNU-specific parts in the source code. Still, the GNU C++ compiler is still the compiler most likely to be useful for building GXemul. There is a page on the GXemul homepage, http://gxemul.sourceforge.net/build.html, which lists various platforms, compilers, and which versions of GXemul that was built on those platforms.)

GXemul does not require any additional third-party libraries to build, however, the following optional libraries or third-party software give additional functionality:

- X11 libraries: for legacy mode framebuffer emulation.
- Doxygen: if installed, source code documentation will be generated when documentation is built.

The emulator's performance is dependent on both runtime settings and on compiler settings, so you might want to experiment with using different `CXX`, `CXXFLAGS`, and `LDFLAGS` environment variable values when running the `configure` script.

During development of the emulator: `configure --debug` may be used to enable some debugging aids and turn off optimizations. `make test` can be used to run unit tests. If you often recompile the whole tree (`make clean_all`, followed by `configure` and `make` again), then using ccache is recommended.

Running `make install` will install GXemul into `/usr/local`, or wherever the configure script detects that user software is installed on your system (may be overridden by setting the `PREFIX` environment variable before running `configure`).

### How to run the emulator:

Once you have built GXemul, running it should be rather straight-forward. Running `gxemul` without arguments (or with the `-h` or `-H` command line options) will display a help message.

Running `gxemul -V` will start GXemul in an "empty state" in the interactive debugger. You may then type `help` to see a list of available commands.

To get some ideas about what is possible to run in the emulator, please read the section about installing "guest" operating systems. The most straight forward guest operating system to install is NetBSD/pmax; the instructions provided here should let you install NetBSD/pmax in a way very similar to how it is done on a real DECstation.

If you are interested in using the emulator to develop code on your own, then you should also read the section about Hello World.

To exit the emulator, type CTRL-C to show the single-step debugger prompt (if it is not already displayed), and then type `quit`.

If you are starting an emulation by entering settings directly on the command line, and you are not using the `-x` option, then all terminal input and output will go to the main controlling terminal. CTRL-C is used to break into the debugger, so in order to send CTRL-C to the running (emulated) program, you may use CTRL-B. (This should be a reasonable compromise to allow the emulator to be usable even on systems without X Windows.)

There is no way to send an actual CTRL-B to the emulated program, when typing in the main controlling terminal window. The solution is to either use configuration files, or use `-x`. Both these solutions cause new xterms to be opened for each emulated serial port that is written to. CTRL-B and CTRL-C both have their original meaning in those xterm windows.

### Which processor architectures does GXemul emulate?

The architectures that are emulated well enough to let at least one guest operating system run (per architecture) are ARM, MIPS, Motorola 88K, PowerPC, and SuperH.

Please read the sections about emulation modes and guest operating systems for more information about the machines and operating systems, respectively, that can be considered "working" in the emulator.

(There is some code in GXemul for emulation of other architectures, but they are not stable or complete enough to be listed among the "working" architectures.)

### Which host architectures/platforms are supported?

GXemul should hopefully compile and run on most modern host architectures (64-bit or 32-bit word-length) on most Unix-like operating systems, as long as there is a modern C++ compiler available.

If it does not build or run, then it can be considered a bug. Please report it to the development mailing list.

It is generally tested on FreeBSD/amd64, FreeBSD/alpha, Linux, and also NetBSD and OpenBSD inside GXemul itself.

Note 1: The dynamic translation engine does not require backends for native code generation to be written for each individual host architecture; the intermediate representation that the dyntrans system uses can be executed on any host architecture.

Note 2: Although GXemul may build and run on non-Unix-like platforms, such as Cygwin, Unix-like systems are the primary platform. Some functionality may be lost when running on Cygwin.

### Emulation accuracy:

GXemul is an instruction-level emulator; things that would happen in several steps within a real CPU are not taken into account (e.g. pipe-line stalls or out-of-order execution). Still, instruction-level accuracy seems to be enough to be able to run complete guest operating systems inside the emulator.

The existance of instruction and data caches is "faked" to let operating systems think that they are there, but for all practical purposes, these caches are non-working.

The emulator is in general not timing-accurate, neither at the instruction level nor on any higher level. An attempt is made to let emulated clocks run at the same speed as the host (i.e. an emulated timer running at 100 Hz will interrupt around 100 times per real second), but since the host speed may vary, e.g. because of other running processes, there is no guarantee as to how many instructions will be executed in each of these 100 Hz cycles.

If the host is very slow, the emulated clocks might even lag behind the real-world clock.

### Which machines does GXemul emulate?

A few different machine types are emulated. The criteria used to include a machine in these lists is:

- For real machines: That the machine emulation is complete enough to run at least one unmodified "guest OS".
- For GXemul's `test*` machines: That the experimental devices for test machines work according to the documentation.

Machines emulated using the new framework: <ul

- MIPS
  - testmips (partial support for experimental devices)

- Motorola 88K
  - testm88k (partial support for experimental devices)

  Machines emulated using the legacy framework:

  - ARM
    - CATS (NetBSD/cats, OpenBSD/cats)
    - IQ80321 (NetBSD/evbarm)
    - NetWinder (NetBSD/netwinder)
    - testarm (experimental, HelenOS/arm)

  - MIPS
    - DECstation 5000/200 (NetBSD/pmax, OpenBSD/pmax, Ultrix, Linux/DECstation, Sprite)
    - Acer Pica-61 (NetBSD/arc)
    - NEC MobilePro 770, 780, 800, 880 (NetBSD/hpcmips)
    - Cobalt (NetBSD/cobalt)
    - Malta (NetBSD/evbmips, Linux/Malta (<super>*1</super>))
    - Algorithmics P5064 (NetBSD/algor)
    - SGI O2 (aka IP32) (<super>*2</super>) (NetBSD/sgi)
    - oldtestmips (experimental, HelenOS/mips)

  - Motorola 88K
    - Motorola MVME187 (OpenBSD/mvme88k)
    - oldtestm88k (experimental)

  - PowerPC
    - IBM 6050/6070 (PReP, PowerPC Reference Platform) (NetBSD/prep)
    - MacPPC (generic "G4" Macintosh) (NetBSD/macppc)
    - Artesyn PM/PPC (<super>*2</super>) (NetBSD/pmppc)
    - testppc (experimental)

  - SuperH
    - Sega Dreamcast (NetBSD/dreamcast, Linux/dreamcast)
    - Landisk I-O DATA USL-5P (OpenBSD/landisk)
    - testsh (experimental)

  (<super>*1</super>) = Linux/Malta sometimes works as a guest OS, but running Linux/Malta in GXemul is much more experimental/unknown than NetBSD, so it is still on the "unsupported" page.
  (<super>*2</super>) = The emulation is enough for root-on-nfs, but no disk controller (SCSI nor IDE) is emulated yet for this machine type.

  Note that of all of the machines above, none of them is emulated to 100%. The most complete emulation mode is probably the DECstation 5000/200. Things that will most likely not work include running raw PROM images for most machines, SGI IRIX, MacOS X or Darwin, Windows NT, or Dreamcast games.

  There may be code in GXemul for emulation of some other machine types; the degree to which these work range from almost being able to run a complete OS, to almost completely unsupported, perhaps just enough support to output a few boot messages via serial console. (See the end of this section on the Guest OSes page for some examples, but remember that these do not necessarily work.)

  In addition to emulating real machines, there are also the test machines. A test machine consists of one or more CPUs and a few experimental devices such as:

  - a console I/O device (putchar() and getchar()...)
  - an inter-processor communication device, for SMP experiments
  - a very simple linear framebuffer device (for graphics output)
  - a simple disk controller
  - a simple ethernet controller
  - a simple interrupt controller
  - a real-time clock device

  This mode is useful if you wish to run experimental code, but do not wish to target any specific real-world machine type, for example for educational purposes.

  You can read more about these experimental devices here.