mips64emul documentation: Introduction

Back to the index

## Introduction

- Overview
- Is mips64emul free software?
- How to compile/build the emulator
- Which CPU types does mips64emul emulate?
- Which machines does mips64emul emulate?
- Which guest OSes are possible to run?

### Overview:

mips64emul is a MIPS machine emulator, which can be used in experiments involving MIPS binary code. 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 really emulated correctly, they are only "faked" well enough to make eg. NetBSD run. Still, the emulator could be of interest for academic research and experiments, such as when learning how to write an OS for a MIPS-like machine, or profiling SMP, memory, or system call usage.

The emulator is written in C, does not depend on external libraries (except X11, but that is optional), and should compile and run on any Unix-like system. If it doesn't, then that is a bug.

The emulator contains code which tries to emulate the workings of MIPS-like CPUs and surrounding hardware found in real machines, but it does not contain any actual MIPS ROM code or other form of MIPS program 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 PROM image at all.

You can use pre-compiled kernels (for example NetBSD kernels, or Linux), or other programs that are in MIPS 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).

You do not need any MIPS compiler toolchain to build or use mips64emul. If you need to compile MIPS binaries from sources, then of course you need such a toolchain, but that is completely separate from mips64emul. (There is also a regression testing framework, which requires that a GNU CC for mips64-unknown-elf or similar is available, but it is not required to build the emulator.)

### Is mips64emul free software?

Yes. mips64emul is distributed 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 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 mips64emul (for example as a binary package), or reuse code from mips64emul, 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 mips64emul 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 any Unix-like system. If it doesn't, then please mail me a bug report.

(Note for Windows users: there is a small possibility that this will also work with Cygwin.)

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 mips64emul, running it should be rather straight-forward. To exit the emulator, type CTRL-C to enter the single-step debugger, and then type quit. By typing CTRL-B instead, a CTRL-C is sent to the emulated program.

### Which CPU types does mips64emul emulate?

While other emulators aim to emulate only one specific CPU type, eg R3000, mips64emul does not. The ideal goal would be to emulate "all" MIPS-like CPUs. Both 64-bit and 32-bit MIPS-like CPUs can be emulated.

mips64emul is basically an instruction-level simulator; things that would happen in several steps within a physical CPU are not necessarily simulated correctly or at all (eg. pipe-line stages or out-of-order execution).

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

### Which machines does mips64emul emulate?

A few different machine types are emulated. The machine types that are emulated best at the moment are:

- DECstation/DECsystem machines
  Model 5000/200: Serial controller (including keyboard and mouse), ethernet, SCSI, and graphical framebuffers are emulated.
  Other models: these differ slightly from the 5000/200 model, and mips64emul doesn't emulate them well enough to run a complete OS yet.

- Acer Pica-61 (an ARC machine)
  Serial controller, "VGA" text console, and SCSI are emulated well enough to let NetBSD/arc and OpenBSD/arc be installed and run.

There is code in mips64emul 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 specific machine types, a "bare" machine can be emulated. A bare 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)

This mode is useful if you wish to experiment with software for MIPS-like systems, but do not wish to target any specific real-world machine type, for example for educational purposes or generic MIPS related experiments.

You can read more about these experimental devices here.

### Which guest OSes are possible to run?

This table sums up 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:

Guest OS: |  | Emulation mode: |  | Guest OS: |  | Emulation mode:
NetBSD/pmax |  | DECstation |  | NetBSD/arc |  | ARC (Acer Pica)
OpenBSD/pmax |  | DECstation |  | OpenBSD/arc |  | ARC (Acer Pica)
Ultrix/RISC |  | DECstation |  | Sprite |  | DECstation
Redhat Linux* |  | DECstation |  | Debian GNU/Linux* |  | DECstation
NetBSD/pmax 1.6.2 | OpenBSD/pmax 2.8 | Ultrix 4.5 | Redhat Linux*
NetBSD/arc 1.6.2 | OpenBSD/arc 2.3 | Sprite | Debian GNU/Linux*

* Although Linux runs under DECstation emulation, at the time of writing this, Linux has no support for keyboards on the 5000/200 (the specific DECstation model being emulated), so when the login prompt is reached you cannot interact with the system. Some people are working on improving the situation. Running in text-mode (emulated serial console) works fine, though, but then you don't get to see the penguin in the corner.

[ UPDATE 2005-01-19: Kaj-Michael Lang noticed that the current CVS-version of linux-mips has support for keyboards now, on DECstation 5000/200, so it is possible to run Linux in mips64emul with framebuffer/keyboard. He has made a kernel available here: http://home.tal.org/~milang/o2/patches/vmlinux-2.4.29-rc2-r3k-mipsel-decstation ]

It is non-trivial to get a specific operating system or OS kernel to run in the emulator, so don't expect the list above to grow too quickly.

There is no guarantee that anything specific will run in the emulator, but NetBSD is a good starting point for someone who wants to experiment.