GXemul documentation:        Introduction

Back to the index


Introduction


Overview:

GXemul is a machine emulator, which can be used to experiment with binary code for (among others) MIPS-based machines. Several emulation modes are available. For some emulation modes, processors and surrounding hardware components are emulated well enough to let unmodified operating systems run as if they were running on a real machine.

It is important to keep in mind that devices and CPUs are not simulated with 100% accuracy. They are only "faked" well enough to make operating systems (eg NetBSD) run. 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 external libraries (except X11, but that is optional), and should compile and run on most Unix-like systems. If it doesn't, then that is a bug. (You do not need any MIPS compiler toolchain to build or use GXemul. If you need to compile MIPS binaries from sources, then of course you need such a toolchain, but that is completely separate from GXemul. There is a regression testing framework, which requires that a GNU CC for mips64-unknown-elf or similar is available. For simply building and using the emulator, it is not required.)

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, raw binaries).


Is GXemul Free software?

Yes. I have released GXemul under a Free license. (For a definitions of the four freedoms associated with Free software, please read http://www.gnu.org/philosophy/free-sw.html.)

The code in GXemul is Copyrighted software, it is not public domain or anything like that.

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. If you plan to redistribute GXemul (for example as a binary package), or reuse code from GXemul, then you should check those files for their license terms.

(The licenses usually require that the original Copyright and license terms are included when you make a copy or modification. The "easiest way out" if you plan to redistribute code from GXemul is to simply supply the source code. You should however check individual files for details.)


How to compile/build the emulator:

Uncompress the .tar.gz distribution file, and run
	$ ./configure
	$ make

This should work on most Unix-like systems. If it doesn't, then mail me a bug report.

(Note for Windows users: there is a possibility that some releases and/or snapshots will also work with Cygwin, but I can't promise that.)

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 a modern PC, you could try the following:

        $ CFLAGS="-mcpu=pentium4 -O3" ./configure
        $ make

Run ./configure --help to get a list of configure options. (The possible options differ between different releases and snapshots.)

Once you have built GXemul, running it should be rather straight-forward. 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 is an ugly hack; 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. CTRL-B and CTRL-C both have their original meaning in those xterm windows.)


Which CPU types does GXemul emulate?

MIPS:

Emulation of R4000, which is a 64-bit CPU, was my initial goal. Right now, R2000/R3000-like CPUs are also emulated (32-bit), and emulation of R1x000 (at least the parts that are similar to R4000) is beginning to work as expected. Code targeted for MIPS32 and MIPS64 also often work.

I have written an experimental dynamic binary translation subsystem. This gives higher total performance than interpreting one instruction at a time and executing it. (If you wish to enable bintrans, add -b to the command line, but keep in mind that it is still experimental.)

URISC:

I have implemented an URISC emulation mode, just for fun. The only instruction available in an URISC machine is "reverse subtract and skip on borrow". (It is probably not worth trying to do bintrans with URISC, because any reasonable URISC program relies on self-modifying code, which is bad for bintrans performance.)

Other CPU types:

There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation too, but it only works for "Hello World" and similarly trivial programs. (There are some other CPU modes too, but they are working even less.)


Emulation accuracy:

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


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":

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:

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.


Which guest OSes are possible to run?

This table lists the guest OSes that run well enough to be considered working in the emulator. They can boot from a harddisk image and be interacted with similar to a real machine.

NetBSD/pmax
DECstation 5000/200
NetBSD/arc
Acer Pica-61
OpenBSD/pmax
DECstation 5000/200
OpenBSD/arc
Acer Pica-61
Ultrix/RISC
DECstation 5000/200
Debian GNU/Linux *
DECstation 5000/200
Sprite
DECstation 5000/200
Redhat Linux *
DECstation 5000/200
NetBSD/hpcmips
NEC MobilePro 770, 780, 800, 880
NetBSD/cobalt
Cobalt


* Although Linux runs under DECstation emulation, the default 2.4.27 kernel in Debian GNU/Linux does not support keyboards on the 5000/200 (the specific DECstation model being emulated), so when the login prompt is reached you cannot interact with the system. Kaj-Michael Lang has compiled and made available a newer kernel from the current mips-linux development tree. You can find it here: http://home.tal.org/~milang/o2/kernels/vmlinux-2.4.29-rc2-r3k-mipsel-decstation This newer kernel supports keyboard input, but it does not have Debian's ethernet patches, so you will not be able to use keyboard/framebuffer and networking at the same time.