Gavare's eXperimental Emulator: Introduction

Back to the index

## Introduction

- Overview
- Is GXemul Free software?
- How to compile/build the emulator
- How to run the emulator
- Which processor architectures does GXemul emulate?
- Emulation accuracy
- Which machines does GXemul emulate?

NetBSD/pmax 1.6.2 with X11
running in GXemul

### Overview:

GXemul is an experimental instruction-level machine emulator. Several emulation modes are available. In some modes, processors and surrounding hardware components are emulated well enough to let unmodified operating systems (e.g. NetBSD) run as if they were running on a real machine.

The processor architecture best emulated by GXemul is MIPS, but other architectures such as ARM and PowerPC are also partially emulated.

Devices and CPUs are not simulated with 100% accuracy. They are only ``faked'' well enough to allow guest operating systems 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 is written in C, does not depend on third-party libraries, and should compile and run on most 64-bit and 32-bit Unix-like systems.

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 many 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, 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, or when booting from ISO9660 CDROM images.)

### Is GXemul Free software?

Yes. I have released GXemul 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 code I have written is released under a 3-clause BSD-style license (or "revised BSD-style" if one wants to use GNU jargon). Apart from the code I have written, 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 make a copy or modification.

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. I have not done this, since I do not plan on making distributions without source code. 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 open source and simply supply the source code.

In case you want to reuse parts of GXemul, but you need to do that under a different license (e.g. the GPL), then contact me and I might re-license/dual-license files on a case-by-case basis.

### How to compile/build the emulator:

Uncompress the .tar.gz distribution file, and run

    	$ ./configure
    	$ make

This should work on most Unix-like systems. GXemul does not require any specific libraries to build, however, if you build on a system which does not have X11 libraries installed, some functionality will be lost.

The emulator's performance is highly dependent on both runtime settings and on compiler settings, so you might want to experiment with different CC and CFLAGS environment variable values. For example, on an AMD Athlon host, you might want to try setting `CFLAGS` to `-march=athlon -O3` 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.

To get some ideas about what is possible to run in the emulator, please read the section about installing "guest" operating systems. 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 enter the single-step debugger, 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?

#### MIPS:

Emulation of R4000, which is a 64-bit CPU, was my initial goal. R2000/R3000-like CPUs (32-bit), R1x000, and generic MIPS32/MIPS64-style CPUs are also emulated, and are hopefully almost as stable as the R4000 emulation. Several guest operating systems for MIPS can run inside the emulator.

(For MIPS emulation, I have written an experimental dynamic binary translation subsystem, for Alpha and i386 hosts. This gives higher total performance than interpreting one instruction at a time and executing it. If you wish to disable bintrans, add -B to the command line.)

#### ARM:

ARM emulation is good enough to run NetBSD/cats, OpenBSD/cats, and NetBSD/evbarm, but it is not as tested or fine-tuned as the MIPS emulation mode.

#### PowerPC:

PowerPC emulation is still in its beginning stages, but good enough to run NetBSD/prep 2.1.

Non-MIPS emulation modes use dynamic translation, but not recompilation into native code. This makes it possible to run on any host platform.

### Emulation accuracy:

GXemul is an instruction-level emulator; things that would happen in several steps within a real CPU are not taken into account (eg. 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.

Caches are by default not emulated. In some cases, the existance of caches is "faked" to let operating systems think that they are there. (There is some old code for R2000/R3000 caches, but it has probably suffered from bitrot by now.)

The emulator is not timing-accurate. It can be run in a "deterministic" mode, `-D`. The meaning of deterministic is simply that running two emulations with the same settings will result in identical runs. Obviously, this requires that no user interaction is taking place, and that clock speeds are fixed with the `-I` option. (Deterministic in this case does not mean that the emulation will be identical to some actual real-world machine.)

(Oops/TODO: User interaction means both input to the emulated program/OS, and interacting with the emulator itself. Breaking into the debugger and then continuing execution may affect when/how interrupts occur.)

### Which machines does GXemul emulate?

A few different machine types are emulated. The following machine types are emulated well enough to run at least one "guest OS":

- MIPS
  - DECstation 5000/200 ("3max")
  - Acer Pica-61 (an ARC machine)
  - NEC MobilePro 770, 780, 800, and 880 (HPCmips machines)
  - Cobalt
  - Malta (evbmips)
  - SGI O2 ("IP32") (<super>*</super>)

- ARM
  - CATS
  - IQ80321 (evbarm)

- PowerPC
  - PReP (PowerPC Reference Platform)

(<super>*</super>) = Enough for root-on-nfs, but not for disk boot.)

There is code in GXemul for emulation of many 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).

In addition to emulating real machines, there is also a "test-machine". 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 SCSI disk controller
- a simple ethernet controller

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.