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	<html>
2	<head><title>GXemul documentation: Introduction</title>
3	<meta name="robots" content="noarchive,nofollow,noindex">
4	</head>
5	<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
13	<!--
14
15	$Id: intro.html,v 1.53 2005/06/26 08:42:26 debug Exp $
16
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	<li><a href="#free">Is GXemul Free software?</a>
53	<li><a href="#build">How to compile/build the emulator</a>
54	<li><a href="#run">How to run the emulator</a>
55	<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	<li><a href="#guestos">Which guest OSes are possible to run in GXemul?</a>
59	</ul>
60
61
62
63
64
65	<p><br>
66	<a name="overview"></a>
67	<h3>Overview:</h3>
68
69	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
76	<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	complaining too much. Still, the emulator could be of interest for
79	academic research and experiments, such as when learning how to write
80	operating system code.
81
82	<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
89	<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	emulator itself, so you do not need to use any ROM image at all.
94
95	<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
100	<p>If you do not have a kernel as a separate file, but you have a bootable
101	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
105
106
107
108
109
110
111
112	<p><br>
113	<a name="free"></a>
114	<h3>Is GXemul Free software?</h3>
115
116	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
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	<a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
126	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	This should work on most Unix-like systems. If it doesn't, then
155	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	Run <b><tt>./configure --help</tt></b> to get a list of configure options. (The
174	possible options differ between different releases and snapshots.)
175
176
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	<p>
191	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	To exit the emulator, type CTRL-C to enter the
199	single-step debugger, and then type <tt><b>quit</b></tt>.
200
201	<p>
202	If you are starting an emulation by entering settings directly on the
203	command line, and you are not using the <tt><b>-x</b></tt> option, then all
204	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	(This should be a reasonable compromise to allow the emulator to be usable
208	even on systems without X Windows.)
209
210	<p>
211	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
218
219
220
221
222	<p><br>
223	<a name="cpus"></a>
224	<h3>Which CPU types does GXemul emulate?</h3>
225
226	<h4>MIPS:</h4>
227
228	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
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	<h4>Other CPU types:</h4>
251
252	Some other CPU architectures can also be partially emulated. These are not
253	working well enough yet to run guest operating systems.
254
255
256
257
258
259
260	<p><br>
261	<a name="accuracy"></a>
262	<h3>Emulation accuracy:</h3>
263
264	GXemul is an instruction-level emulator; things that would happen in
265	several steps within a real CPU are not taken into account (eg. pipe-line
266	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	emulator.
269
270	<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
276	<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
285
286
287
288
289	<p><br>
290	<a name="emulmodes"></a>
291	<h3>Which machines does GXemul emulate?</h3>
292
293	A few different machine types are emulated. The following machine types
294	are emulated well enough to run at least one "guest OS":
295
296	<p>
297	<ul>
298	<li><b>DECstation 5000/200</b>  ("3max")
299	<br>Serial controller (including keyboard and mouse), ethernet,
300	SCSI, and graphical framebuffers.
301	<p>
302	<li><b>Acer Pica-61</b>  (an ARC machine)
303	<br>Serial controller, "VGA" text console, and SCSI.
304	<p>
305	<li><b>NEC MobilePro 770, 780, 800, and 880</b>  (HPCmips machines)
306	<br>Framebuffer, keyboard, and a PCMCIA IDE controller.
307	<p>
308	<li><b>Cobalt</b>
309	<br>Serial controller and PCI IDE.
310	<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	</ul>
318
319	<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
324	<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
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	<p>This mode is useful if you wish to run experimental code, but do not
336	wish to target any specific real-world machine type, for example for
337	educational purposes.
338
339	<p>You can read more about these experimental devices <a
340	href="experiments.html#expdevices">here</a>.
341
342
343
344
345
346
347
348	<p><br>
349	<a name="guestos"></a>
350	<h3>Which guest OSes are possible to run in GXemul?</h3>
351
352	This table lists the guest OSes that run well enough to be considered
353	working in the emulator. They can boot from a harddisk image and be
354	interacted with similar to a real machine.
355
356	<p>
357	<center><table border="0">
358	<tr>
359	<td width="10"></td>
360	<td align="center"><a href="20050317-example.png"><img src="20050317-example_small.png"></a></td>
361	<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
370	</tr>
371
372	<tr><td height="10"></td></tr>
373
374	<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
387	<tr><td height="10"></td></tr>
388
389	<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
401	<tr><td height="10"></td></tr>
402
403	<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
416	<tr><td height="10"></td></tr>
417
418	<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
431	<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	</table></center>
448
449
450	<p><br>
451
452	<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
464
465	</body>
466	</html>