trunk/doc/intro.html

<html>
<head><title>GXemul documentation: Introduction</title>
</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>
<!-- The first 10 lines are cut away by the homepage updating script.  -->


<!--

$Id: intro.html,v 1.46 2005/06/04 12:02:17 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?</a>
</ul>


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

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

<p>
Devices and CPUs are not simulated with 100% accuracy. They are only
"faked" well enough to make operating systems (eg 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>POWER/PowerPC</h4>

There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation, enough
to run "Hello World", but not enough to run complete operating systems.  
This mode isn't really working yet.


<h4>Other CPU types:</h4>

Some other CPU architectures (such as x86) can also be partially emulated.
These are not enabled by default though, because of their unstable-ness.


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

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