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	<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.40 2005/04/27 15:22: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="#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	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
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	(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
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	<h3>Is GXemul Free software?</h3>
113
114	Yes. I have released GXemul under a Free license.
115	(For a definitions of the four freedoms associated with Free software,
116	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	The code in GXemul is Copyrighted software, it is <i>not</i> public
121	domain or anything like that.
122
123	<p>
124	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	<a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
127	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	This should work on most Unix-like systems. If it doesn't, then
156	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	single-step debugger, and then type <b>quit</b>.
181
182	<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
189	<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
197
198
199
200
201
202	<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	A few different machine types are emulated. The following machine types
262	are emulated well enough to run at least one "guest OS":
263
264	<p>
265	<ul>
266	<li><b>DECstation 5000/200</b>  ("3max")
267	<br>Serial controller (including keyboard and mouse), ethernet,
268	SCSI, and graphical framebuffers.
269	<p>
270	<li><b>Acer Pica-61</b>  (an ARC machine)
271	<br>Serial controller, "VGA" text console, and SCSI.
272	<p>
273	<li><b>NEC MobilePro 770, 780, 800, and 880</b>  (HPCmips machines)
274	<br>Framebuffer, keyboard, and a PCMCIA IDE controller.
275	<p>
276	<li><b>Cobalt</b>
277	<br>Serial controller and PCI IDE.
278	</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	In addition to emulating real machines, there is also a "test-machine".
288	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	This table lists the guest OSes that run well enough to be considered
318	working in the emulator. They can boot from a harddisk image and be
319	interacted with similar to a real machine.
320
321	<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
335	</tr>
336
337	<tr><td height="10"></td></tr>
338
339	<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
352	<tr><td height="10"></td></tr>
353
354	<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
366	<tr><td height="10"></td></tr>
367
368	<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
381	<tr><td height="10"></td></tr>
382
383	<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
396	</table></center>
397
398
399	<p><br>
400
401	<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
413
414	</body>
415	</html>