trunk/doc/intro.html

<html><head><title>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;Introduction</title>
<meta name="robots" content="noarchive,nofollow,noindex"></head>
<body bgcolor="#f8f8f8" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
<table border=0 width=100% bgcolor="#d0d0d0"><tr>
<td width=100% align=center valign=center><table border=0 width=100%><tr>
<td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
<b>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;</b></font>
<font color="#000000" size="6"><b>Introduction</b>
</font></td></tr></table></td></tr></table><p>

<!--

$Id: intro.html,v 1.64 2005/10/07 22:45:33 debug Exp $

Copyright (C) 2003-2005  Anders Gavare.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

-->

<a href="./">Back to the index</a>

<p><br>
<h2>Introduction</h2>

<p>
<ul>
  <li><a href="#overview">Overview</a>
  <li><a href="#free">Is GXemul Free software?</a>
  <li><a href="#build">How to compile/build the emulator</a>
  <li><a href="#run">How to run the emulator</a>
  <li><a href="#cpus">Which CPU types does GXemul emulate?</a>
  <li><a href="#accuracy">Emulation accuracy</a>
  <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
  <li><a href="#guestos">Which guest OSes are possible to run in GXemul?</a>
</ul>


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

GXemul is an experimental instruction-level machine emulator. Several
emulation modes are available. In some modes, processors and surrounding
hardware components are emulated well enough to let unmodified operating
systems (e.g. NetBSD) run as if they were running on a real machine.

<p>The processor architecture best emulated by GXemul is MIPS, but other
architectures are also partially emulated.

<p>Devices and CPUs are not simulated with 100% accuracy. They are only
``faked'' well enough to make operating systems (e.g. NetBSD) run without
complaining too much. Still, the emulator could be of interest for
academic research and experiments, such as when learning how to write
operating system code.

<p>The emulator is written in C, does not depend on external libraries
(except X11, but that is optional), and should compile and run on most
Unix-like systems. If it doesn't, then that is a bug.

<p>The emulator contains code which tries to emulate the workings of CPUs
and surrounding hardware found in real machines, but it does not contain
any ROM code. You will need some form of program (in binary form) to run
in the emulator. For many emulation modes, PROM calls are handled by the
emulator itself, so you do not need to use any ROM image at all.

<p>You can use pre-compiled kernels (for example NetBSD kernels, or
Linux), or other programs that are in binary format, and in some cases
even actual ROM images. A couple of different file formats are supported
(ELF, a.out, ECOFF, SREC, and raw binaries).

<p>If you do not have a kernel as a separate file, but you have a bootable
disk image, then it is sometimes possible to boot directly from that
image. (This works for example with DECstation emulation, or when booting
from ISO9660 CDROM images.)


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

Yes. I have released GXemul under a Free license. The code in GXemul is
Copyrighted software, it is <i>not</i> public domain. (If this is
confusing to you, you might want to read up on the definitions of the
four freedoms associated with Free software, <a
href="http://www.gnu.org/philosophy/free-sw.html">http://www.gnu.org/philosophy/free-sw.html</a>.)

<p>The code I have written is released under a 3-clause BSD-style license
(or "revised BSD-style" if one wants to use <a
href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>). Apart from
the code I have written, some files are copied from other sources such as
NetBSD, for example header files containing symbolic names of bitfields in
device registers. They are also covered by similar licenses, but with some
additional clauses. The main point, however, is that the licenses require
that the original Copyright and license terms are included when you make a
copy or modification.

<p>If you plan to redistribute GXemul <i>without</i> supplying the source
code, then you need to comply with each individual source file some other
way, for example by writing additional documentation containing copyright
notes. I have not done this, since I do not plan on making distributions
without source code. You need to check all individual files for details.
The "easiest way out" if you plan to redistribute code from GXemul is, of
course, to let it remain open source and simply supply the source code.

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


<p><br>
<a name="build"></a>
<h3>How to compile/build the emulator:</h3>

Uncompress the .tar.gz distribution file, and run
<pre>
        $ <b>./configure</b>
        $ <b>make</b>
</pre>

<p>This should work on most Unix-like systems. If it doesn't, then
mail me a bug report.

<p>The emulator's performance is highly dependent on both runtime settings
and on compiler settings, so you might want to experiment with different
CC and CFLAGS environment variable values. For example, on a modern PC,
you could try the following:
<p><pre>
        $ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
        $ <b>make</b>
</pre>


<p><br>
<a name="run"></a>
<h3>How to run the emulator:</h3>

Once you have built GXemul, running it should be rather straight-forward.
Running <tt><b>gxemul</b></tt> without arguments (or with the
<b><tt>-h</tt></b> or <b><tt>-H</tt></b> command line options) will
display a help message.

<p>
To get some ideas about what is possible to run in the emulator, please 
read the section about <a href="guestoses.html">installing "guest" 
operating systems</a>. If you are interested in using the emulator to 
develop code on your own, then you should also read the section about
<a href="experiments.html#hello">Hello World</a>.

<p>
To exit the emulator, type CTRL-C to enter the 
single-step debugger, and then type <tt><b>quit</b></tt>.

<p>
If you are starting an emulation by entering settings directly on the 
command line, and you are not using the <tt><b>-x</b></tt> option, then all 
terminal input and output will go to the main controlling terminal.
CTRL-C is used to break into the debugger, so in order to send CTRL-C to 
the running (emulated) program, you may use CTRL-B.
(This should be a reasonable compromise to allow the emulator to be usable
even on systems without X Windows.)

<p>
There is no way to send an actual CTRL-B to the emulated program, when
typing in the main controlling terminal window. The solution is to either
use <a href="configfiles.html">configuration files</a>, or use
<tt><b>-x</b></tt>. Both these solutions cause new xterms to be opened for 
each emulated serial port that is written to. CTRL-B and CTRL-C both have 
their original meaning in those xterm windows.


<p><br>
<a name="cpus"></a>
<h3>Which CPU types does GXemul emulate?</h3>

<h4>MIPS:</h4>

Emulation of R4000, which is a 64-bit CPU, was my initial goal.
R2000/R3000-like CPUs (32-bit), R1x000, and generic MIPS32/MIPS64-style
CPUs are also emulated, and are hopefully almost as stable as the R4000 
emulation.

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

<h4>ARM:</h4>

The ARM CPU emulation is good enough to run NetBSD/cats and OpenBSD/cats
(almost bugfree :-), but it is not as tested or fine-tuned as the MIPS
emulation.

<h4>Other CPU types:</h4>

Some other CPU architectures can also be partially emulated. These are not
working well enough yet to run guest operating systems.


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

GXemul is an instruction-level emulator; things that would happen in
several steps within a real CPU are not taken into account (eg. pipe-line
stalls or out-of-order execution). Still, instruction-level accuracy seems
to be enough to be able to run complete guest operating systems inside the
emulator.

<p>Caches are by default not emulated. In some cases, the existance of
caches is "faked" to let operating systems think that they are there.
(There is some old code for R2000/R3000 caches, but it has probably
suffered from bitrot by now.)

<p>The emulator is <i>not</i> timing-accurate. It can be run in a
"deterministic" mode, <tt><b>-D</b></tt>. The meaning of deterministic is
simply that running two emulations with the same settings will result in
identical runs. Obviously, this requires that no user interaction is
taking place, and that clock speeds are fixed with the <tt><b>-I</b></tt>
option. (Deterministic in this case does <i>not</i> mean that the
emulation will be identical to some actual real-world machine.)


<p><br>
<a name="emulmodes"></a>
<h3>Which machines does GXemul emulate?</h3>

A few different machine types are emulated. The following machine types 
are emulated well enough to run at least one "guest OS":

<p>
<ul>
  <li><b><u>MIPS</u></b>
  <ul>
    <li><b>DECstation 5000/200</b>&nbsp;&nbsp;("3max")
        <br>Serial controller (including keyboard and mouse), ethernet,
        SCSI, and graphical framebuffers.
    <p>
    <li><b>Acer Pica-61</b>&nbsp;&nbsp;(an ARC machine)
        <br>Serial controller, "VGA" text console, and SCSI.
    <p>
    <li><b>NEC MobilePro 770, 780, 800, and 880</b>&nbsp;&nbsp;(HPCmips machines)
        <br>Framebuffer, keyboard, and a PCMCIA IDE controller.
    <p>
    <li><b>Cobalt</b>
        <br>Serial controller and PCI IDE.
    <p>
    <li><b>Malta (evbmips)</b>
        <br>Serial controller and PCI IDE.
    <p>
    <li><b>SGI O2 ("IP32")</b>
        <br>Serial controller and ethernet.&nbsp;&nbsp;<small>(Enough for
        root-on-nfs, but not for disk boot.)</small>
  </ul>
  <p>
  <li><b><u>ARM</u></b>
  <ul>
    <li><b>CATS</b>
        <br>VGA and PCI IDE.
  </ul>
</ul>

<p>There is code in GXemul for emulation of many other machine types; the
degree to which these work range from almost being able to run a complete
OS, to almost completely unsupported (perhaps just enough support to
output a few boot messages via serial console).

<p>In addition to emulating real machines, there is also a "test-machine".
A test-machine consists of one or more CPUs and a few experimental devices
such as:

<p>
<ul>
  <li>a console I/O device (putchar() and getchar()...)
  <li>an inter-processor communication device, for SMP experiments
  <li>a very simple linear framebuffer device (for graphics output)
  <li>a simple SCSI disk controller
  <li>a simple ethernet controller
</ul>

<p>This mode is useful if you wish to run experimental code, but do not
wish to target any specific real-world machine type, for example for
educational purposes.

<p>You can read more about these experimental devices <a
href="experiments.html#expdevices">here</a>.


<p><br>
<a name="guestos"></a>
<h3>Which guest OSes are possible to run in GXemul?</h3>

This table lists the guest OSes that run well enough to be considered
working in the emulator. They can boot from a harddisk image and be
interacted with similar to a real machine.

<p>
<center><table border="0">
        <tr>
          <td width="10"></td>
          <td align="center"><a href="20050317-example.png"><img src="20050317-example_small.png"></a></td>
          <td width="15"></td>
          <td><a href="http://www.netbsd.org/Ports/pmax/">NetBSD/pmax</a>
                <br>DECstation 5000/200</td>
          <td width="30"></td>
          <td align="center"><a href="20041024-netbsd-arc-installed.gif"><img src="20041024-netbsd-arc-installed_small.gif"></a></td>
          <td width="15"></td>
          <td><a href="http://www.netbsd.org/Ports/arc/">NetBSD/arc</a>
                <br>Acer Pica-61</td>

        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="openbsd-pmax-20040710.png"><img src="openbsd-pmax-20040710_small.png"></a></td>
          <td></td>
          <td><a href="http://www.openbsd.org/pmax.html">OpenBSD/pmax</a>
                <br>DECstation 5000/200</td>
          <td></td>
          <td align="center"><a href="20041024-openbsd-arc-installed.gif"><img src="20041024-openbsd-arc-installed_small.gif"></a></td>
          <td></td>
          <td><a href="http://www.openbsd.org/arc.html">OpenBSD/arc</a>
                <br>Acer Pica-61</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="ultrix4.5-20040706.png"><img src="ultrix4.5-20040706_small.gif"></a></td>
          <td></td>
          <td>Ultrix/RISC<br>DECstation 5000/200</td>
          <td></td>
          <td align="center"><a href="20041213-debian_4.png"><img src="20041213-debian_4_small.gif"></a></td>
          <td></td>
          <td><a href="http://www.debian.org/">Debian&nbsp;GNU/Linux</a>&nbsp;<super>*</super>
                <br>DECstation 5000/200</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="sprite-20040711.png"><img src="sprite-20040711_small.png"></a></td>
          <td></td>
          <td><a href="http://www.cs.berkeley.edu/projects/sprite/retrospective.html">Sprite</a>
                <br>DECstation 5000/200</td>
          <td></td>
          <td align="center"><a href="20041129-redhat_mips.png"><img src="20041129-redhat_mips_small.png"></a></td>
          <td></td>
          <td>Redhat&nbsp;Linux&nbsp;<super>*</super>
                <br>DECstation 5000/200</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="20050427-netbsd-hpcmips-2.png"><img src="20050427-netbsd-hpcmips-2_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/hpcmips/">NetBSD/hpcmips</a>
                <br>NEC MobilePro 770, 780, 800, 880</td>
          <td></td>
          <td align="center"><a href="20050413-netbsd-cobalt.png"><img src="20050413-netbsd-cobalt_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/cobalt/">NetBSD/cobalt</a>
                <br>Cobalt</td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="20050626-netbsd-sgimips-netboot.png"><img src="20050626-netbsd-sgimips-netboot_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/sgimips/">NetBSD/sgimips</a>
                <br>SGI O2 ("IP32")</td>
          <td></td>
          <td align="center"><a href="20050622-netbsd-evbmips-malta.png"><img src="20050622-netbsd-evbmips-malta_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/evbmips/">NetBSD/evbmips</a>
                <br>5Kc (and 4Kc) Malta<br>evaluation boards</td>
          <td></td>
        </tr>

        <tr><td height="10"></td></tr>

        <tr>
          <td></td>
          <td align="center"><a href="20051007-netbsd-cats-installed.png"><img src="20051007-netbsd-cats-installed_small.png"></a></td>
          <td></td>
          <td><a href="http://www.netbsd.org/Ports/cats/">NetBSD/cats</a>
                <br>CATS</td>
          <td></td>
          <td align="center"><a href="20051007-openbsd-cats-installed.png"><img src="20051007-openbsd-cats-installed_small.png"></a></td>
          <td></td>
          <td><a href="http://www.openbsd.org/cats.html">OpenBSD/cats</a>
                <br>CATS</td>
          <td></td>
        </tr>

</table></center>


<p><br>

<super>*</super> Although Linux runs under DECstation emulation, the
default 2.4.27 kernel in Debian GNU/Linux does not support keyboards on
the 5000/200 (the specific DECstation model being emulated), so when the
login prompt is reached you cannot interact with the system. Kaj-Michael
Lang has compiled and made available a newer kernel from the current
mips-linux development tree. You can find it here: <a
href="http://home.tal.org/~milang/o2/kernels/">http://home.tal.org/~milang/o2/kernels</a>/<a
href="http://home.tal.org/~milang/o2/kernels/vmlinux-2.4.29-rc2-r3k-mipsel-decstation">vmlinux-2.4.29-rc2-r3k-mipsel-decstation</a>
This newer kernel supports keyboard input, but it does not have Debian's
ethernet patches, so you will not be able to use keyboard/framebuffer
<i>and</i> networking at the same time.


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