0.3.5/doc/intro.html

<html><head><title>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;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>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;</b></font>
<font color="#000000" size="6"><b>Introduction</b>
</font></td></tr></table></td></tr></table><p>

<!--

$Id: intro.html,v 1.61 2005/08/16 05:15:24 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 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>(Non-MIPS emulation modes are also under development, but so far none
of those modes has reached the completeness required to run unmodified
operating systems.)

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

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

<p>If you plan to redistribute GXemul <i>without</i> 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.

<p>(If a stable release of GXemul is packaged into binary form, and it is
obvious which version of GXemul was used to build the package, then it can
be argued that the source code is available, just not in that specific
package. Common sense should be used in this case, and not pedanticism.)


<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>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><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 disable bintrans, add <b>-B</b> to
the command line.)


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