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.40 2005/04/27 15:22: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="#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>
It is important to keep in mind that devices and CPUs are not simulated 
with 100% accuracy. They are only "faked" well enough to make operating 
systems (eg NetBSD) run. 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. There
is a <a href="technical.html#regtest">regression testing</a> framework,
which requires that a GNU CC for mips64-unknown-elf or similar is available.
For simply building and using the emulator, it is not required.) 

<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, raw binaries).


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

Yes. I have released GXemul under a Free license.
(For a definitions of the four freedoms associated with Free software,
please read <a href="http://www.gnu.org/philosophy/free-sw.html">
http://www.gnu.org/philosophy/free-sw.html</a>.)

<p>
The code in GXemul is Copyrighted software, it is <i>not</i> public
domain or anything like that.

<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>./configure --help</b> to get a list of configure options. (The 
possible options differ between different releases and snapshots.)

<p>
Once you have built GXemul, running it should be rather straight-forward.
To exit the emulator, type CTRL-C to enter the 
single-step debugger, and then type <b>quit</b>.

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

<p>
(This is an ugly hack; 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 configuration files, or use <b>-x</b>. Both 
these solutions cause new xterms to be opened for each emulated serial 
port. 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. Right
now, R2000/R3000-like CPUs are also emulated (32-bit), and emulation of
R1x000 (at least the parts that are similar to R4000) is beginning to work
as expected. Code targeted for MIPS32 and MIPS64 also often work.

<p>
I have written an experimental dynamic binary translation subsystem.
This gives higher total performance than interpreting one instruction at a
time and executing it. (If you wish to enable bintrans, add <b>-b</b> to
the command line, but keep in mind that it is still experimental.)


<h4>URISC:</h4>

I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
emulation mode, just for fun. The only instruction available in an URISC
machine is "reverse subtract and skip on borrow". (It is probably not
worth trying to do bintrans with URISC, because any reasonable URISC
program relies on self-modifying code, which is bad for bintrans
performance.)


<h4>Other CPU types:</h4>

There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation too,
but it only works for "Hello World" and similarly trivial programs. (There
are some other CPU modes too, but they are working even less.)


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

GXemul is an instruction-level simulator; things that would happen in
several steps within a real CPU are not taken into account (eg. pipe-line
stages 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><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="netbsd-pmax-20040630.png"><img src="netbsd-pmax-20040630_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			</head>
4	dpavlin	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	dpavlin	2	<!-- The first 10 lines are cut away by the homepage updating script. -->
12
13
14			<!--
15
16	dpavlin	4	$Id: intro.html,v 1.40 2005/04/27 15:22:17 debug Exp $
17	dpavlin	2
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	dpavlin	4	<li><a href="#free">Is GXemul Free software?</a>
54	dpavlin	2	<li><a href="#build">How to compile/build the emulator</a>
55			<li><a href="#cpus">Which CPU types does GXemul emulate?</a>
56			<li><a href="#accuracy">Emulation accuracy</a>
57			<li><a href="#emulmodes">Which machines does GXemul emulate?</a>
58			<li><a href="#guestos">Which guest OSes are possible to run?</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	4	It is important to keep in mind that devices and CPUs are not simulated
77			with 100% accuracy. They are only "faked" well enough to make operating
78			systems (eg NetBSD) run. Still, the emulator could be of interest for
79			academic research and experiments, such as when learning how to write
80			operating system code.
81	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			such a toolchain, but that is completely separate from GXemul. There
89			is a <a href="technical.html#regtest">regression testing</a> framework,
90			which requires that a GNU CC for mips64-unknown-elf or similar is available.
91			For simply building and using the emulator, it is not required.)
92	dpavlin	2
93			<p>
94			The emulator contains code which tries to emulate the workings of CPUs and
95			surrounding hardware found in real machines, but it does not contain any
96			ROM code. You will need some form of program (in binary form) to run in
97			the emulator. For many emulation modes, PROM calls are handled by the
98			emulator itself, so you do not need to use any ROM image at all.
99
100			<p>
101			You can use pre-compiled kernels (for example NetBSD kernels, or Linux),
102			or other programs that are in binary format, and in some cases even actual
103			ROM images. A couple of different file formats are supported (ELF, a.out,
104			ECOFF, SREC, raw binaries).
105
106
107
108
109
110			<p><br>
111			<a name="free"></a>
112	dpavlin	4	<h3>Is GXemul Free software?</h3>
113	dpavlin	2
114	dpavlin	4	Yes. I have released GXemul under a Free license.
115			(For a definitions of the four freedoms associated with Free software,
116	dpavlin	2	please read <a href="http://www.gnu.org/philosophy/free-sw.html">
117			http://www.gnu.org/philosophy/free-sw.html</a>.)
118
119			<p>
120	dpavlin	4	The code in GXemul is Copyrighted software, it is <i>not</i> public
121			domain or anything like that.
122
123			<p>
124	dpavlin	2	The code I have written is released under a 3-clause BSD-style license
125			(or "revised BSD-style" if one wants to use
126	dpavlin	4	<a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
127	dpavlin	2	Apart from the code I have written, some files are copied from other sources
128			such as NetBSD, for example header files containing symbolic names of
129			bitfields in device registers. They are also covered by similar licenses,
130			but with some additional clauses. If you plan to redistribute GXemul
131			(for example as a binary package), or reuse code from GXemul,
132			then you should check those files for their license terms.
133
134			<p>
135			(The licenses usually require that the original Copyright and license
136			terms are included when you make a copy or modification. The "easiest way
137			out" if you plan to redistribute code from GXemul is to simply supply
138			the source code. You should however check individual files for details.)
139
140
141
142
143
144			<p><br>
145			<a name="build"></a>
146			<h3>How to compile/build the emulator:</h3>
147
148			Uncompress the .tar.gz distribution file, and run
149			<pre>
150			$ <b>./configure</b>
151			$ <b>make</b>
152			</pre>
153
154			<p>
155	dpavlin	4	This should work on most Unix-like systems. If it doesn't, then
156	dpavlin	2	mail me a bug report.
157
158			<p>
159			(Note for Windows users: there is a possibility that some releases
160			and/or snapshots will also work with Cygwin, but I can't promise that.)
161
162			<p>
163			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>
168			<pre>
169			$ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
170			$ <b>make</b>
171			</pre>
172
173			<p>
174			Run <b>./configure --help</b> to get a list of configure options. (The
175			possible options differ between different releases and snapshots.)
176
177			<p>
178			Once you have built GXemul, running it should be rather straight-forward.
179			To exit the emulator, type CTRL-C to enter the
180	dpavlin	4	single-step debugger, and then type <b>quit</b>.
181	dpavlin	2
182	dpavlin	4	<p>
183			If you are starting an emulation by entering settings directly on the
184			command line, and you are not using the <b>-x</b> option, then all
185			terminal input and output will go to the main controlling terminal.
186			CTRL-C is used to break into the debugger, so in order to send CTRL-C to
187			the running (emulated) program, you may use CTRL-B.
188	dpavlin	2
189	dpavlin	4	<p>
190			(This is an ugly hack; there is no way to send an actual CTRL-B to the
191			emulated program, when typing in the main controlling terminal window.
192			The solution is to either use configuration files, or use <b>-x</b>. Both
193			these solutions cause new xterms to be opened for each emulated serial
194			port. CTRL-B and CTRL-C both have their original meaning in those
195			xterm windows.)
196	dpavlin	2
197
198
199
200	dpavlin	4
201
202	dpavlin	2	<p><br>
203			<a name="cpus"></a>
204			<h3>Which CPU types does GXemul emulate?</h3>
205
206			<h4>MIPS:</h4>
207
208			Emulation of R4000, which is a 64-bit CPU, was my initial goal. Right
209			now, R2000/R3000-like CPUs are also emulated (32-bit), and emulation of
210			R1x000 (at least the parts that are similar to R4000) is beginning to work
211			as expected. Code targeted for MIPS32 and MIPS64 also often work.
212
213			<p>
214			I have written an experimental dynamic binary translation subsystem.
215			This gives higher total performance than interpreting one instruction at a
216			time and executing it. (If you wish to enable bintrans, add <b>-b</b> to
217			the command line, but keep in mind that it is still experimental.)
218
219
220
221			<h4>URISC:</h4>
222
223			I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
224			emulation mode, just for fun. The only instruction available in an URISC
225			machine is "reverse subtract and skip on borrow". (It is probably not
226			worth trying to do bintrans with URISC, because any reasonable URISC
227			program relies on self-modifying code, which is bad for bintrans
228			performance.)
229
230
231
232
233			<h4>Other CPU types:</h4>
234
235			There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation too,
236			but it only works for "Hello World" and similarly trivial programs. (There
237			are some other CPU modes too, but they are working even less.)
238
239
240
241
242
243			<p><br>
244			<a name="accuracy"></a>
245			<h3>Emulation accuracy:</h3>
246
247			GXemul is an instruction-level simulator; things that would happen in
248			several steps within a real CPU are not taken into account (eg. pipe-line
249			stages or out-of-order execution). Still, instruction-level accuracy seems
250			to be enough to be able to run complete guest operating systems inside the
251			emulator.
252
253
254
255
256
257			<p><br>
258			<a name="emulmodes"></a>
259			<h3>Which machines does GXemul emulate?</h3>
260
261	dpavlin	4	A few different machine types are emulated. The following machine types
262			are emulated well enough to run at least one "guest OS":
263	dpavlin	2
264			<p>
265			<ul>
266	dpavlin	4	<li><b>DECstation 5000/200</b>  ("3max")
267			<br>Serial controller (including keyboard and mouse), ethernet,
268			SCSI, and graphical framebuffers.
269	dpavlin	2	<p>
270			<li><b>Acer Pica-61</b>  (an ARC machine)
271	dpavlin	4	<br>Serial controller, "VGA" text console, and SCSI.
272	dpavlin	2	<p>
273			<li><b>NEC MobilePro 770, 780, 800, and 880</b>  (HPCmips machines)
274	dpavlin	4	<br>Framebuffer, keyboard, and a PCMCIA IDE controller.
275			<p>
276			<li><b>Cobalt</b>
277			<br>Serial controller and PCI IDE.
278	dpavlin	2	</ul>
279
280			<p>
281			There is code in GXemul for emulation of many other machine types;
282			the degree to which these work range from "almost" being able to run
283			a complete OS, to almost completely unsupported (perhaps just enough
284			support to output a few boot messages via serial console).
285
286			<p>
287	dpavlin	4	In addition to emulating real machines, there is also a "test-machine".
288	dpavlin	2	A test-machine consists of one or more CPUs and a few experimental
289			devices such as:
290
291			<p>
292			<ul>
293			<li>a console I/O device (putchar() and getchar()...)
294			<li>an inter-processor communication device, for SMP experiments
295			<li>a very simple linear framebuffer device (for graphics output)
296			</ul>
297
298			<p>
299			This mode is useful if you wish to run experimental code, but do not
300			wish to target any specific real-world machine type, for example for
301			educational purposes.
302
303			<p>
304			You can read more about these experimental devices
305			<a href="experiments.html#expdevices">here</a>.
306
307
308
309
310
311
312
313			<p><br>
314			<a name="guestos"></a>
315			<h3>Which guest OSes are possible to run?</h3>
316
317	dpavlin	4	This table lists the guest OSes that run well enough to be considered
318	dpavlin	2	working in the emulator. They can boot from a harddisk image and be
319	dpavlin	4	interacted with similar to a real machine.
320	dpavlin	2
321	dpavlin	4	<p>
322			<center><table border="0">
323			<tr>
324			<td width="10"></td>
325			<td align="center"><a href="netbsd-pmax-20040630.png"><img src="netbsd-pmax-20040630_small.png"></a></td>
326			<td width="15"></td>
327			<td><a href="http://www.netbsd.org/Ports/pmax/">NetBSD/pmax</a>
328			<br>DECstation 5000/200</td>
329			<td width="30"></td>
330			<td align="center"><a href="20041024-netbsd-arc-installed.gif"><img src="20041024-netbsd-arc-installed_small.gif"></a></td>
331			<td width="15"></td>
332			<td><a href="http://www.netbsd.org/Ports/arc/">NetBSD/arc</a>
333			<br>Acer Pica-61</td>
334	dpavlin	2
335	dpavlin	4	</tr>
336	dpavlin	2
337	dpavlin	4	<tr><td height="10"></td></tr>
338	dpavlin	2
339	dpavlin	4	<tr>
340			<td></td>
341			<td align="center"><a href="openbsd-pmax-20040710.png"><img src="openbsd-pmax-20040710_small.png"></a></td>
342			<td></td>
343			<td><a href="http://www.openbsd.org/pmax.html">OpenBSD/pmax</a>
344			<br>DECstation 5000/200</td>
345			<td></td>
346			<td align="center"><a href="20041024-openbsd-arc-installed.gif"><img src="20041024-openbsd-arc-installed_small.gif"></a></td>
347			<td></td>
348			<td><a href="http://www.openbsd.org/arc.html">OpenBSD/arc</a>
349			<br>Acer Pica-61</td>
350			</tr>
351	dpavlin	2
352	dpavlin	4	<tr><td height="10"></td></tr>
353	dpavlin	2
354	dpavlin	4	<tr>
355			<td></td>
356			<td align="center"><a href="ultrix4.5-20040706.png"><img src="ultrix4.5-20040706_small.gif"></a></td>
357			<td></td>
358			<td>Ultrix/RISC<br>DECstation 5000/200</td>
359			<td></td>
360			<td align="center"><a href="20041213-debian_4.png"><img src="20041213-debian_4_small.gif"></a></td>
361			<td></td>
362			<td><a href="http://www.debian.org/">Debian GNU/Linux</a> <super>*</super>
363			<br>DECstation 5000/200</td>
364			</tr>
365	dpavlin	2
366	dpavlin	4	<tr><td height="10"></td></tr>
367	dpavlin	2
368	dpavlin	4	<tr>
369			<td></td>
370			<td align="center"><a href="sprite-20040711.png"><img src="sprite-20040711_small.png"></a></td>
371			<td></td>
372			<td><a href="http://www.cs.berkeley.edu/projects/sprite/retrospective.html">Sprite</a>
373			<br>DECstation 5000/200</td>
374			<td></td>
375			<td align="center"><a href="20041129-redhat_mips.png"><img src="20041129-redhat_mips_small.png"></a></td>
376			<td></td>
377			<td>Redhat Linux <super>*</super>
378			<br>DECstation 5000/200</td>
379			</tr>
380	dpavlin	2
381	dpavlin	4	<tr><td height="10"></td></tr>
382	dpavlin	2
383	dpavlin	4	<tr>
384			<td></td>
385			<td align="center"><a href="20050427-netbsd-hpcmips-2.png"><img src="20050427-netbsd-hpcmips-2_small.png"></a></td>
386			<td></td>
387			<td><a href="http://www.netbsd.org/Ports/hpcmips/">NetBSD/hpcmips</a>
388			<br>NEC MobilePro 770, 780, 800, 880</td>
389			<td></td>
390			<td align="center"><a href="20050413-netbsd-cobalt.png"><img src="20050413-netbsd-cobalt_small.png"></a></td>
391			<td></td>
392			<td><a href="http://www.netbsd.org/Ports/cobalt/">NetBSD/cobalt</a>
393			<br>Cobalt</td>
394			</tr>
395	dpavlin	2
396	dpavlin	4	</table></center>
397	dpavlin	2
398
399	dpavlin	4	<p><br>
400	dpavlin	2
401	dpavlin	4	<super>*</super> Although Linux runs under DECstation emulation, the
402			default 2.4.27 kernel in Debian GNU/Linux does not support keyboards on
403			the 5000/200 (the specific DECstation model being emulated), so when the
404			login prompt is reached you cannot interact with the system. Kaj-Michael
405			Lang has compiled and made available a newer kernel from the current
406			mips-linux development tree. You can find it here: <a
407			href="http://home.tal.org/~milang/o2/kernels/">http://home.tal.org/~milang/o2/kernels</a>/<a
408			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>
409			This newer kernel supports keyboard input, but it does not have Debian's
410			ethernet patches, so you will not be able to use keyboard/framebuffer
411			<i>and</i> networking at the same time.
412	dpavlin	2
413
414			</body>
415			</html>