trunk/doc/intro.html

<html>
<head><title>GXemul documentation: Introduction</title>
<meta name="robots" content="noarchive,nofollow,noindex">
</head>
<body bgcolor="#f8f8f8" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
<table border=0 width=100% bgcolor="#d0d0d0"><tr>
<td width=100% align=center valign=center><table border=0 width=100%><tr>
<td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
<b>GXemul documentation:</b></font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<font color="#000000" size="6"><b>Introduction</b>
</font></td></tr></table></td></tr></table><p>

<!--

$Id: intro.html,v 1.53 2005/06/26 08:42:26 debug Exp $

Copyright (C) 2003-2005  Anders Gavare.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

-->

<a href="./">Back to the index</a>

<p><br>
<h2>Introduction</h2>

<p>
<ul>
  <li><a href="#overview">Overview</a>
  <li><a href="#free">Is GXemul Free software?</a>
  <li><a href="#build">How to compile/build the emulator</a>
  <li><a href="#run">How to run the emulator</a>
  <li><a href="#cpus">Which CPU types does GXemul emulate?</a>
  <li><a href="#accuracy">Emulation accuracy</a>
  <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
  <li><a href="#guestos">Which guest OSes are possible to run in GXemul?</a>
</ul>


<p><br>
<a name="overview"></a>
<h3>Overview:</h3>

GXemul is an experimental instruction-level machine emulator. It can be
used to run binary code for (among others) MIPS-based machines, regardless
of host platform. Several emulation modes are available. For some 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.

<p>Devices and CPUs are not simulated with 100% accuracy. They are only
``faked'' well enough to make operating systems (e.g. NetBSD) 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.

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

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

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

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


<p><br>
<a name="free"></a>
<h3>Is GXemul Free software?</h3>

Yes. I have released GXemul under a Free license. The code in GXemul is
Copyrighted software, it is <i>not</i> 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, <a
href="http://www.gnu.org/philosophy/free-sw.html">http://www.gnu.org/philosophy/free-sw.html</a>.)

<p>
The code I have written is released under a 3-clause BSD-style license
(or "revised BSD-style" if one wants to use
<a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
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.

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


<p><br>
<a name="build"></a>
<h3>How to compile/build the emulator:</h3>

Uncompress the .tar.gz distribution file, and run
<pre>
        $ <b>./configure</b>
        $ <b>make</b>
</pre>

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

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

<p>
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:
<p>
<pre>
        $ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
        $ <b>make</b>
</pre>

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


<p><br>
<a name="run"></a>
<h3>How to run the emulator:</h3>

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

<p>
To get some ideas about what is possible to run in the emulator, please 
read the section about <a href="guestoses.html">installing "guest" 
operating systems</a>. If you are interested in using the emulator to 
develop code on your own, then you should also read the section about
<a href="experiments.html#hello">Hello World</a>.

<p>
To exit the emulator, type CTRL-C to enter the 
single-step debugger, and then type <tt><b>quit</b></tt>.

<p>
If you are starting an emulation by entering settings directly on the 
command line, and you are not using the <tt><b>-x</b></tt> 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.)

<p>
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 <a href="configfiles.html">configuration files</a>, or use
<tt><b>-x</b></tt>. 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.


<p><br>
<a name="cpus"></a>
<h3>Which CPU types does GXemul emulate?</h3>

<h4>MIPS:</h4>

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.

<p>
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>-b</b> to
the command line, but keep in mind that it is still experimental.)


<h4>URISC:</h4>

I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
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.)


<h4>Other CPU types:</h4>

Some other CPU architectures can also be partially emulated. These are not
working well enough yet to run guest operating systems.


<p><br>
<a name="accuracy"></a>
<h3>Emulation accuracy:</h3>

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.

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

<p>
The emulator is <i>not</i> timing-accurate. It can be run in a 
"deterministic" mode, <tt><b>-D</b></tt>. 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 <tt><b>-I</b></tt> 
option. (Deterministic in this case does <i>not</i> mean that the emulation
will be identical to some actual real-world machine.)


<p><br>
<a name="emulmodes"></a>
<h3>Which machines does GXemul emulate?</h3>

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

<p>
<ul>
  <li><b>DECstation 5000/200</b>&nbsp;&nbsp;("3max")
        <br>Serial controller (including keyboard and mouse), ethernet,
        SCSI, and graphical framebuffers.
  <p>
  <li><b>Acer Pica-61</b>&nbsp;&nbsp;(an ARC machine)
        <br>Serial controller, "VGA" text console, and SCSI.
  <p>
  <li><b>NEC MobilePro 770, 780, 800, and 880</b>&nbsp;&nbsp;(HPCmips machines)
        <br>Framebuffer, keyboard, and a PCMCIA IDE controller.
  <p>
  <li><b>Cobalt</b>
        <br>Serial controller and PCI IDE.
  <p>
  <li><b>Malta (evbmips)</b>
        <br>Serial controller and PCI IDE.
  <p>
  <li><b>SGI O2 ("IP32")</b>
        <br>Serial controller and ethernet.&nbsp;&nbsp;<small>(Enough for
        root-on-nfs, but not for disk boot.)</small>
</ul>

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

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

<p>
<ul>
  <li>a console I/O device (putchar() and getchar()...)
  <li>an inter-processor communication device, for SMP experiments
  <li>a very simple linear framebuffer device (for graphics output)
</ul>

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

<p>You can read more about these experimental devices <a
href="experiments.html#expdevices">here</a>.


<p><br>
<a name="guestos"></a>
<h3>Which guest OSes are possible to run in GXemul?</h3>

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.

<p>
<center><table border="0">
        <tr>
          <td width="10"></td>
          <td align="center"><a href="20050317-example.png"><img src="20050317-example_small.png"></a></td>
          <td width="15"></td>
          <td><a href="http://www.netbsd.org/Ports/pmax/">NetBSD/pmax</a>
                <br>DECstation 5000/200</td>
          <td width="30"></td>
          <td align="center"><a href="20041024-netbsd-arc-installed.gif"><img src="20041024-netbsd-arc-installed_small.gif"></a></td>
          <td width="15"></td>
          <td><a href="http://www.netbsd.org/Ports/arc/">NetBSD/arc</a>
                <br>Acer Pica-61</td>

        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="openbsd-pmax-20040710.png"><img src="openbsd-pmax-20040710_small.png"></a></td>
          <td></td>
          <td><a href="http://www.openbsd.org/pmax.html">OpenBSD/pmax</a>
                <br>DECstation 5000/200</td>
          <td></td>
          <td align="center"><a href="20041024-openbsd-arc-installed.gif"><img src="20041024-openbsd-arc-installed_small.gif"></a></td>
          <td></td>
          <td><a href="http://www.openbsd.org/arc.html">OpenBSD/arc</a>
                <br>Acer Pica-61</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="ultrix4.5-20040706.png"><img src="ultrix4.5-20040706_small.gif"></a></td>
          <td></td>
          <td>Ultrix/RISC<br>DECstation 5000/200</td>
          <td></td>
          <td align="center"><a href="20041213-debian_4.png"><img src="20041213-debian_4_small.gif"></a></td>
          <td></td>
          <td><a href="http://www.debian.org/">Debian&nbsp;GNU/Linux</a>&nbsp;<super>*</super>
                <br>DECstation 5000/200</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="sprite-20040711.png"><img src="sprite-20040711_small.png"></a></td>
          <td></td>
          <td><a href="http://www.cs.berkeley.edu/projects/sprite/retrospective.html">Sprite</a>
                <br>DECstation 5000/200</td>
          <td></td>
          <td align="center"><a href="20041129-redhat_mips.png"><img src="20041129-redhat_mips_small.png"></a></td>
          <td></td>
          <td>Redhat&nbsp;Linux&nbsp;<super>*</super>
                <br>DECstation 5000/200</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="20050427-netbsd-hpcmips-2.png"><img src="20050427-netbsd-hpcmips-2_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/hpcmips/">NetBSD/hpcmips</a>
                <br>NEC MobilePro 770, 780, 800, 880</td>
          <td></td>
          <td align="center"><a href="20050413-netbsd-cobalt.png"><img src="20050413-netbsd-cobalt_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/cobalt/">NetBSD/cobalt</a>
                <br>Cobalt</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="20050626-netbsd-sgimips-netboot.png"><img src="20050626-netbsd-sgimips-netboot_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/sgimips/">NetBSD/sgimips</a>
                <br>SGI O2 ("IP32")</td>
          <td></td>
          <td align="center"><a href="20050622-netbsd-evbmips-malta.png"><img src="20050622-netbsd-evbmips-malta_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/evbmips/">NetBSD/evbmips</a>
                <br>5Kc (and 4Kc) Malta<br>evaluation boards</td>
          <td></td>
        </tr>

</table></center>


<p><br>

<super>*</super> 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: <a
href="http://home.tal.org/~milang/o2/kernels/">http://home.tal.org/~milang/o2/kernels</a>/<a
href="http://home.tal.org/~milang/o2/kernels/vmlinux-2.4.29-rc2-r3k-mipsel-decstation">vmlinux-2.4.29-rc2-r3k-mipsel-decstation</a>
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
<i>and</i> networking at the same time.


</body>
</html>
1	dpavlin	2	<html>
2			<head><title>GXemul documentation: Introduction</title>
3	dpavlin	8	<meta name="robots" content="noarchive,nofollow,noindex">
4	dpavlin	2	</head>
5	dpavlin	4	<body bgcolor="#f8f8f8" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
6			<table border=0 width=100% bgcolor="#d0d0d0"><tr>
7			<td width=100% align=center valign=center><table border=0 width=100%><tr>
8			<td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
9			<b>GXemul documentation:</b></font>
10			<font color="#000000" size="6"><b>Introduction</b>
11			</font></td></tr></table></td></tr></table><p>
12	dpavlin	2
13			<!--
14
15	dpavlin	10	$Id: intro.html,v 1.53 2005/06/26 08:42:26 debug Exp $
16	dpavlin	2
17			Copyright (C) 2003-2005 Anders Gavare. All rights reserved.
18
19			Redistribution and use in source and binary forms, with or without
20			modification, are permitted provided that the following conditions are met:
21
22			1. Redistributions of source code must retain the above copyright
23			notice, this list of conditions and the following disclaimer.
24			2. Redistributions in binary form must reproduce the above copyright
25			notice, this list of conditions and the following disclaimer in the
26			documentation and/or other materials provided with the distribution.
27			3. The name of the author may not be used to endorse or promote products
28			derived from this software without specific prior written permission.
29
30			THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
31			ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
32			IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33			ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
34			FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
35			DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
36			OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
37			HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
38			LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
39			OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
40			SUCH DAMAGE.
41
42			-->
43
44			<a href="./">Back to the index</a>
45
46			<p><br>
47			<h2>Introduction</h2>
48
49			<p>
50			<ul>
51			<li><a href="#overview">Overview</a>
52	dpavlin	4	<li><a href="#free">Is GXemul Free software?</a>
53	dpavlin	2	<li><a href="#build">How to compile/build the emulator</a>
54	dpavlin	6	<li><a href="#run">How to run the emulator</a>
55	dpavlin	2	<li><a href="#cpus">Which CPU types does GXemul emulate?</a>
56			<li><a href="#accuracy">Emulation accuracy</a>
57			<li><a href="#emulmodes">Which machines does GXemul emulate?</a>
58	dpavlin	10	<li><a href="#guestos">Which guest OSes are possible to run in GXemul?</a>
59	dpavlin	2	</ul>
60
61
62
63
64
65			<p><br>
66			<a name="overview"></a>
67			<h3>Overview:</h3>
68
69	dpavlin	10	GXemul is an experimental instruction-level machine emulator. It can be
70			used to run binary code for (among others) MIPS-based machines, regardless
71			of host platform. Several emulation modes are available. For some modes,
72			processors and surrounding hardware components are emulated well enough to
73			let unmodified operating systems run as if they were running on a real
74			machine.
75	dpavlin	2
76	dpavlin	10	<p>Devices and CPUs are not simulated with 100% accuracy. They are only
77			``faked'' well enough to make operating systems (e.g. NetBSD) run without
78	dpavlin	6	complaining too much. Still, the emulator could be of interest for
79			academic research and experiments, such as when learning how to write
80	dpavlin	4	operating system code.
81	dpavlin	2
82	dpavlin	10	<p>The emulator is written in C, does not depend on external libraries
83			(except X11, but that is optional), and should compile and run on most
84			Unix-like systems. If it doesn't, then that is a bug. (You do not need any
85			MIPS compiler toolchain to build or use GXemul. If you need to compile
86			MIPS binaries from sources, then of course you need such a toolchain, but
87			that is completely separate from GXemul.)
88	dpavlin	2
89	dpavlin	10	<p>The emulator contains code which tries to emulate the workings of CPUs
90			and surrounding hardware found in real machines, but it does not contain
91			any ROM code. You will need some form of program (in binary form) to run
92			in the emulator. For many emulation modes, PROM calls are handled by the
93	dpavlin	2	emulator itself, so you do not need to use any ROM image at all.
94
95	dpavlin	10	<p>You can use pre-compiled kernels (for example NetBSD kernels, or
96			Linux), or other programs that are in binary format, and in some cases
97			even actual ROM images. A couple of different file formats are supported
98			(ELF, a.out, ECOFF, SREC, and raw binaries).
99	dpavlin	2
100	dpavlin	10	<p>If you do not have a kernel as a separate file, but you have a bootable
101	dpavlin	6	disk image, then it is sometimes possible to boot directly from that
102			image. (This works for example with DECstation emulation, or when booting
103			from ISO9660 CDROM images.)
104	dpavlin	2
105
106
107
108	dpavlin	6
109
110	dpavlin	10
111
112	dpavlin	2	<p><br>
113			<a name="free"></a>
114	dpavlin	4	<h3>Is GXemul Free software?</h3>
115	dpavlin	2
116	dpavlin	6	Yes. I have released GXemul under a Free license. The code in GXemul is
117			Copyrighted software, it is <i>not</i> public domain. (If this is
118			confusing to you, you might want to read up on the definitions of the
119			four freedoms associated with Free software, <a
120			href="http://www.gnu.org/philosophy/free-sw.html">http://www.gnu.org/philosophy/free-sw.html</a>.)
121	dpavlin	2
122			<p>
123			The code I have written is released under a 3-clause BSD-style license
124			(or "revised BSD-style" if one wants to use
125	dpavlin	4	<a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
126	dpavlin	2	Apart from the code I have written, some files are copied from other sources
127			such as NetBSD, for example header files containing symbolic names of
128			bitfields in device registers. They are also covered by similar licenses,
129			but with some additional clauses. If you plan to redistribute GXemul
130			(for example as a binary package), or reuse code from GXemul,
131			then you should check those files for their license terms.
132
133			<p>
134			(The licenses usually require that the original Copyright and license
135			terms are included when you make a copy or modification. The "easiest way
136			out" if you plan to redistribute code from GXemul is to simply supply
137			the source code. You should however check individual files for details.)
138
139
140
141
142
143			<p><br>
144			<a name="build"></a>
145			<h3>How to compile/build the emulator:</h3>
146
147			Uncompress the .tar.gz distribution file, and run
148			<pre>
149			$ <b>./configure</b>
150			$ <b>make</b>
151			</pre>
152
153			<p>
154	dpavlin	4	This should work on most Unix-like systems. If it doesn't, then
155	dpavlin	2	mail me a bug report.
156
157			<p>
158			(Note for Windows users: there is a possibility that some releases
159			and/or snapshots will also work with Cygwin, but I can't promise that.)
160
161			<p>
162			The emulator's performance is highly dependent on both runtime settings
163			and on compiler settings, so you might want to experiment with different
164			CC and CFLAGS environment variable values. For example, on a modern PC,
165			you could try the following:
166			<p>
167			<pre>
168			$ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
169			$ <b>make</b>
170			</pre>
171
172			<p>
173	dpavlin	6	Run <b><tt>./configure --help</tt></b> to get a list of configure options. (The
174	dpavlin	2	possible options differ between different releases and snapshots.)
175
176	dpavlin	6
177
178
179
180
181			<p><br>
182			<a name="run"></a>
183			<h3>How to run the emulator:</h3>
184
185			Once you have built GXemul, running it should be rather straight-forward.
186			Running <tt><b>gxemul</b></tt> without arguments (or with the
187			<b><tt>-h</tt></b> or <b><tt>-H</tt></b> command line options) will
188			display a help message.
189
190	dpavlin	2	<p>
191	dpavlin	6	To get some ideas about what is possible to run in the emulator, please
192			read the section about <a href="guestoses.html">installing "guest"
193			operating systems</a>. If you are interested in using the emulator to
194			develop code on your own, then you should also read the section about
195			<a href="experiments.html#hello">Hello World</a>.
196
197			<p>
198	dpavlin	2	To exit the emulator, type CTRL-C to enter the
199	dpavlin	6	single-step debugger, and then type <tt><b>quit</b></tt>.
200	dpavlin	2
201	dpavlin	4	<p>
202			If you are starting an emulation by entering settings directly on the
203	dpavlin	6	command line, and you are not using the <tt><b>-x</b></tt> option, then all
204	dpavlin	4	terminal input and output will go to the main controlling terminal.
205			CTRL-C is used to break into the debugger, so in order to send CTRL-C to
206			the running (emulated) program, you may use CTRL-B.
207	dpavlin	6	(This should be a reasonable compromise to allow the emulator to be usable
208			even on systems without X Windows.)
209	dpavlin	2
210	dpavlin	4	<p>
211	dpavlin	6	There is no way to send an actual CTRL-B to the emulated program, when
212			typing in the main controlling terminal window. The solution is to either
213			use <a href="configfiles.html">configuration files</a>, or use
214			<tt><b>-x</b></tt>. Both these solutions cause new xterms to be opened for
215			each emulated serial port that is written to. CTRL-B and CTRL-C both have
216			their original meaning in those xterm windows.
217	dpavlin	2
218
219
220
221	dpavlin	4
222	dpavlin	2	<p><br>
223			<a name="cpus"></a>
224			<h3>Which CPU types does GXemul emulate?</h3>
225
226			<h4>MIPS:</h4>
227
228	dpavlin	6	Emulation of R4000, which is a 64-bit CPU, was my initial goal.
229			R2000/R3000-like CPUs (32-bit), R1x000, and generic MIPS32/MIPS64-style
230			CPUs are also emulated, and are hopefully almost as stable as the R4000
231			emulation.
232	dpavlin	2
233			<p>
234			I have written an experimental dynamic binary translation subsystem.
235			This gives higher total performance than interpreting one instruction at a
236			time and executing it. (If you wish to enable bintrans, add <b>-b</b> to
237			the command line, but keep in mind that it is still experimental.)
238
239
240			<h4>URISC:</h4>
241
242			I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
243			emulation mode, just for fun. The only instruction available in an URISC
244			machine is "reverse subtract and skip on borrow". (It is probably not
245			worth trying to do bintrans with URISC, because any reasonable URISC
246			program relies on self-modifying code, which is bad for bintrans
247			performance.)
248
249
250	dpavlin	10	<h4>Other CPU types:</h4>
251	dpavlin	2
252	dpavlin	10	Some other CPU architectures can also be partially emulated. These are not
253			working well enough yet to run guest operating systems.
254	dpavlin	2
255	dpavlin	6
256	dpavlin	2
257
258
259
260			<p><br>
261			<a name="accuracy"></a>
262			<h3>Emulation accuracy:</h3>
263
264	dpavlin	6	GXemul is an instruction-level emulator; things that would happen in
265	dpavlin	2	several steps within a real CPU are not taken into account (eg. pipe-line
266	dpavlin	6	stalls or out-of-order execution). Still, instruction-level accuracy seems
267			to be enough to be able to run complete guest operating systems inside the
268	dpavlin	2	emulator.
269
270	dpavlin	6	<p>
271			Caches are by default not emulated. In some cases, the existance of caches
272			is "faked" to let operating systems think that they are there. (There is
273			some old code for R2000/R3000 caches, but it has probably suffered from
274			bitrot by now.)
275	dpavlin	2
276	dpavlin	6	<p>
277			The emulator is <i>not</i> timing-accurate. It can be run in a
278			"deterministic" mode, <tt><b>-D</b></tt>. The meaning of deterministic is
279			simply that running two emulations with the same settings will result in
280			identical runs. Obviously, this requires that no user interaction is
281			taking place, and that clock speeds are fixed with the <tt><b>-I</b></tt>
282			option. (Deterministic in this case does <i>not</i> mean that the emulation
283			will be identical to some actual real-world machine.)
284	dpavlin	2
285
286
287	dpavlin	6
288
289	dpavlin	2	<p><br>
290			<a name="emulmodes"></a>
291			<h3>Which machines does GXemul emulate?</h3>
292
293	dpavlin	4	A few different machine types are emulated. The following machine types
294			are emulated well enough to run at least one "guest OS":
295	dpavlin	2
296			<p>
297			<ul>
298	dpavlin	4	<li><b>DECstation 5000/200</b>  ("3max")
299			<br>Serial controller (including keyboard and mouse), ethernet,
300			SCSI, and graphical framebuffers.
301	dpavlin	2	<p>
302			<li><b>Acer Pica-61</b>  (an ARC machine)
303	dpavlin	4	<br>Serial controller, "VGA" text console, and SCSI.
304	dpavlin	2	<p>
305			<li><b>NEC MobilePro 770, 780, 800, and 880</b>  (HPCmips machines)
306	dpavlin	4	<br>Framebuffer, keyboard, and a PCMCIA IDE controller.
307			<p>
308			<li><b>Cobalt</b>
309			<br>Serial controller and PCI IDE.
310	dpavlin	10	<p>
311			<li><b>Malta (evbmips)</b>
312			<br>Serial controller and PCI IDE.
313			<p>
314			<li><b>SGI O2 ("IP32")</b>
315			<br>Serial controller and ethernet.  <small>(Enough for
316			root-on-nfs, but not for disk boot.)</small>
317	dpavlin	2	</ul>
318
319	dpavlin	10	<p>There is code in GXemul for emulation of many other machine types; the
320			degree to which these work range from almost being able to run a complete
321			OS, to almost completely unsupported (perhaps just enough support to
322			output a few boot messages via serial console).
323	dpavlin	2
324	dpavlin	10	<p>In addition to emulating real machines, there is also a "test-machine".
325			A test-machine consists of one or more CPUs and a few experimental devices
326			such as:
327	dpavlin	2
328			<p>
329			<ul>
330			<li>a console I/O device (putchar() and getchar()...)
331			<li>an inter-processor communication device, for SMP experiments
332			<li>a very simple linear framebuffer device (for graphics output)
333			</ul>
334
335	dpavlin	10	<p>This mode is useful if you wish to run experimental code, but do not
336	dpavlin	2	wish to target any specific real-world machine type, for example for
337			educational purposes.
338
339	dpavlin	10	<p>You can read more about these experimental devices <a
340			href="experiments.html#expdevices">here</a>.
341	dpavlin	2
342
343
344
345
346
347
348			<p><br>
349			<a name="guestos"></a>
350	dpavlin	10	<h3>Which guest OSes are possible to run in GXemul?</h3>
351	dpavlin	2
352	dpavlin	4	This table lists the guest OSes that run well enough to be considered
353	dpavlin	2	working in the emulator. They can boot from a harddisk image and be
354	dpavlin	4	interacted with similar to a real machine.
355	dpavlin	2
356	dpavlin	4	<p>
357			<center><table border="0">
358			<tr>
359			<td width="10"></td>
360	dpavlin	6	<td align="center"><a href="20050317-example.png"><img src="20050317-example_small.png"></a></td>
361	dpavlin	4	<td width="15"></td>
362			<td><a href="http://www.netbsd.org/Ports/pmax/">NetBSD/pmax</a>
363			<br>DECstation 5000/200</td>
364			<td width="30"></td>
365			<td align="center"><a href="20041024-netbsd-arc-installed.gif"><img src="20041024-netbsd-arc-installed_small.gif"></a></td>
366			<td width="15"></td>
367			<td><a href="http://www.netbsd.org/Ports/arc/">NetBSD/arc</a>
368			<br>Acer Pica-61</td>
369	dpavlin	2
370	dpavlin	4	</tr>
371	dpavlin	2
372	dpavlin	4	<tr><td height="10"></td></tr>
373	dpavlin	2
374	dpavlin	4	<tr>
375			<td></td>
376			<td align="center"><a href="openbsd-pmax-20040710.png"><img src="openbsd-pmax-20040710_small.png"></a></td>
377			<td></td>
378			<td><a href="http://www.openbsd.org/pmax.html">OpenBSD/pmax</a>
379			<br>DECstation 5000/200</td>
380			<td></td>
381			<td align="center"><a href="20041024-openbsd-arc-installed.gif"><img src="20041024-openbsd-arc-installed_small.gif"></a></td>
382			<td></td>
383			<td><a href="http://www.openbsd.org/arc.html">OpenBSD/arc</a>
384			<br>Acer Pica-61</td>
385			</tr>
386	dpavlin	2
387	dpavlin	4	<tr><td height="10"></td></tr>
388	dpavlin	2
389	dpavlin	4	<tr>
390			<td></td>
391			<td align="center"><a href="ultrix4.5-20040706.png"><img src="ultrix4.5-20040706_small.gif"></a></td>
392			<td></td>
393			<td>Ultrix/RISC<br>DECstation 5000/200</td>
394			<td></td>
395			<td align="center"><a href="20041213-debian_4.png"><img src="20041213-debian_4_small.gif"></a></td>
396			<td></td>
397			<td><a href="http://www.debian.org/">Debian GNU/Linux</a> <super>*</super>
398			<br>DECstation 5000/200</td>
399			</tr>
400	dpavlin	2
401	dpavlin	4	<tr><td height="10"></td></tr>
402	dpavlin	2
403	dpavlin	4	<tr>
404			<td></td>
405			<td align="center"><a href="sprite-20040711.png"><img src="sprite-20040711_small.png"></a></td>
406			<td></td>
407			<td><a href="http://www.cs.berkeley.edu/projects/sprite/retrospective.html">Sprite</a>
408			<br>DECstation 5000/200</td>
409			<td></td>
410			<td align="center"><a href="20041129-redhat_mips.png"><img src="20041129-redhat_mips_small.png"></a></td>
411			<td></td>
412			<td>Redhat Linux <super>*</super>
413			<br>DECstation 5000/200</td>
414			</tr>
415	dpavlin	2
416	dpavlin	4	<tr><td height="10"></td></tr>
417	dpavlin	2
418	dpavlin	4	<tr>
419			<td></td>
420			<td align="center"><a href="20050427-netbsd-hpcmips-2.png"><img src="20050427-netbsd-hpcmips-2_small.png"></a></td>
421			<td></td>
422			<td><a href="http://www.netbsd.org/Ports/hpcmips/">NetBSD/hpcmips</a>
423			<br>NEC MobilePro 770, 780, 800, 880</td>
424			<td></td>
425			<td align="center"><a href="20050413-netbsd-cobalt.png"><img src="20050413-netbsd-cobalt_small.png"></a></td>
426			<td></td>
427			<td><a href="http://www.netbsd.org/Ports/cobalt/">NetBSD/cobalt</a>
428			<br>Cobalt</td>
429			</tr>
430	dpavlin	2
431	dpavlin	10	<tr><td height="10"></td></tr>
432
433			<tr>
434			<td></td>
435			<td align="center"><a href="20050626-netbsd-sgimips-netboot.png"><img src="20050626-netbsd-sgimips-netboot_small.png"></a></td>
436			<td></td>
437			<td><a href="http://www.netbsd.org/Ports/sgimips/">NetBSD/sgimips</a>
438			<br>SGI O2 ("IP32")</td>
439			<td></td>
440			<td align="center"><a href="20050622-netbsd-evbmips-malta.png"><img src="20050622-netbsd-evbmips-malta_small.png"></a></td>
441			<td></td>
442			<td><a href="http://www.netbsd.org/Ports/evbmips/">NetBSD/evbmips</a>
443			<br>5Kc (and 4Kc) Malta<br>evaluation boards</td>
444			<td></td>
445			</tr>
446
447	dpavlin	4	</table></center>
448	dpavlin	2
449
450	dpavlin	4	<p><br>
451	dpavlin	2
452	dpavlin	4	<super>*</super> Although Linux runs under DECstation emulation, the
453			default 2.4.27 kernel in Debian GNU/Linux does not support keyboards on
454			the 5000/200 (the specific DECstation model being emulated), so when the
455			login prompt is reached you cannot interact with the system. Kaj-Michael
456			Lang has compiled and made available a newer kernel from the current
457			mips-linux development tree. You can find it here: <a
458			href="http://home.tal.org/~milang/o2/kernels/">http://home.tal.org/~milang/o2/kernels</a>/<a
459			href="http://home.tal.org/~milang/o2/kernels/vmlinux-2.4.29-rc2-r3k-mipsel-decstation">vmlinux-2.4.29-rc2-r3k-mipsel-decstation</a>
460			This newer kernel supports keyboard input, but it does not have Debian's
461			ethernet patches, so you will not be able to use keyboard/framebuffer
462			<i>and</i> networking at the same time.
463	dpavlin	2
464
465			</body>
466			</html>