# GXemul: Introduction

Back to the index.

- Overview
- How to compile/build the emulator
- How to run the emulator
- Which CPUs and machines does GXemul emulate?
- Is GXemul Free software?

### 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 tries to emulate 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.

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.

### How to compile/build the emulator:

For a standard build, 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.

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

- X11 headers and libraries: for graphical 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 (only needed if you want to experiment with the new experimental framework that is under development). `make documentation` generates machine and component descriptions in HTML for the new framework. 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`).

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.

Most of the development is done on FreeBSD/amd64 using clang and/or GNU C++, but every now and then the code is built on Linux, or NetBSD/OpenBSD inside GXemul itself. Although it is possible that GXemul may build and run on non-Unix-like platforms, such as Cygwin inside Windows, Unix-like systems are the primary platform. Some functionality may be lost or not work as expected when running on Cygwin.

### How to run the emulator:

Running `gxemul` without arguments, or with the `-h` command line option, will display a short or long help message, respectively.

The most straight forward complete 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 and the section about debugging.

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 CTRL-B to the emulated program, when typing in the main controlling terminal window. You either need to 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 CPUs and machines does GXemul emulate?

This list contains some of the emulation modes in GXemul, and the guest operating systems that have been verified to work in those modes. Some operating systems or other pieces of software or firmware that are not really working yet are also included, listed with a small RED font.

- ARM
  - CATS (NetBSD/cats, OpenBSD/cats, Debian GNU/Linux)
  - IQ80321 (NetBSD/evbarm)
  - NetWinder (NetBSD/netwinder)
  - Raspberry Pi (NetBSD/raspberrypi, FreeBSD, HelenOS/rpi)
  - testarm (HelenOS/arm)

- MIPS
  - Acer Pica-61 (NetBSD/arc, OpenBSD/arc, Windows NT)
  - Algorithmics P5064 (NetBSD/algor)
  - Cobalt Cube (NetBSD/cobalt)
  - DECstation 5000/200 (NetBSD/pmax, OpenBSD/pmax, Ultrix, Linux/DECstation, Sprite, Mach), DECstation 5000/1xx (raw PROM)
  - Malta (NetBSD/evbmips, Linux/Malta, HelenOS/malta)
  - NEC MobilePro 770, 780, 800, 880 (NetBSD/hpcmips)
  - PlayStation 2 (NetBSD/playstation2)
  - SGI O2 (NetBSD/sgimips, OpenBSD/sgi, Linux, IRIX, raw PROM)
  - VoCore (FreeBSD/vocore, Linux/vocore)
  - testmips (HelenOS/mips, Glatt MU/MK, YCX5/testmips)

- Motorola 88K
  - Luna 88K (OpenBSD/luna88k)
  - Motorola MVME187 (OpenBSD/mvme88k)
  - oldtestm88k

- PowerPC
  - Artesyn PM/PPC (NetBSD/pmppc)
  - IBM 6050/6070 PReP, PowerPC Reference Platform (NetBSD/prep)
  - MacPPC (NetBSD/macppc, HelenOS/ppc)
  - testppc

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

There is code in GXemul for emulation of some other machine types too, but most of those are just dummy skeletons that do not really do anything, apart from being a starting point for testing and development.

### 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.