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