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:</b></font><br>
<font color="#000000" size="6"><b>Introduction</b>
</font></td></tr></table></td></tr></table><p>

<!--

$Id: intro.html,v 1.87 2006/06/23 10:00:41 debug Exp $

Copyright (C) 2003-2006  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>
<table border="0" width="99%"><tr><td valign="top" align="left">
<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 processor architectures does GXemul emulate?</a>
  <li><a href="#hosts">Which host architectures are supported?</a>
  <li><a href="#translation">What kind of translation does GXemul use?</a>
  <li><a href="#accuracy">Emulation accuracy</a>
  <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
</ul>
</td><td valign="center" align="center">
<a href="20050317-example.png"><img src="20050317-example_small.png"></a>
<p>NetBSD/pmax 1.6.2 with X11<br>running in GXemul</td></tr></table>


<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>Devices and processors (ARM, MIPS, PowerPC) are not simulated with 100% 
accuracy. They are only ``faked'' well enough to allow guest operating 
systems 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 third-party libraries,
and should compile and run on most 64-bit and 32-bit Unix-like systems.

<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>In case you want to reuse parts of GXemul, but you need to do that 
under a different license (e.g. the GPL), then contact me and I might 
re-license/dual-license files on a case-by-case basis.


<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. GXemul does not require any 
specific libraries to build, however, if you build on a system which does 
not have X11 libraries installed, some functionality will be lost.

<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 an AMD Athlon
host, you might want to try setting <tt>CFLAGS</tt> to <tt>-march=athlon</tt>
before running <tt>configure</tt>.


<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 processor architectures does GXemul emulate?</h3>

The architectures that are emulated well enough to let at least one 
guest operating system run (per architecture) are ARM, MIPS, and 
PowerPC.


<p><br>
<a name="hosts"></a>
<h3>Which host architectures are supported?</h3>

As of release 0.4.0 of GXemul, the old binary translation subsystem, which 
was used for emulation of MIPS processors on Alpha and i386 hosts, has 
been removed. The current dynamic translation subsystem should work on any 
host.


<p><br>
<a name="translation"></a>
<h3>What kind of translation does GXemul use?</h3>

<b>Static vs. dynamic:</b>

<p>In order to support guest operating systems, which can overwrite old 
code pages in memory with new code, it is necessary to translate code 
dynamically. It is not possible to do a "one-pass" (static) translation.
Self-modifying code and Just-in-Time compilers running inside 
the emulator are other things that would not work with a static 
translator. GXemul is a dynamic translator. However, it does not 
necessarily translate into native code, like many other emulators.

<p><b>"Runnable" Intermediate Representation:</b>

<p>Dynamic translators usually translate from the emulated architecture
(e.g. MIPS) into a kind of <i>intermediate representation</i> (IR), and then
to native code (e.g. AMD64 or x86 code). Since one of my main goals for
GXemul is to keep everything as portable as possible, I have tried to make
sure that the IR is something which can be executed regardless of whether 
the final step (translation from IR to native code) has been implemented
or not.

<p>The IR in GXemul consists of arrays of pointers to functions, and a few 
arguments which are passed along to those functions. The functions are 
implemented in either manually hand-coded C, or automatically generated C.
In any case, this is all statically linked into the GXemul binary at link 
time.

<p>Here is a simplified diagram of how these arrays work.

<p><center><img src="simplified_dyntrans.png"></center>

<p>There is one instruction call slot for every possible program counter
location. In the MIPS case, instruction words are 32 bits in length,
and pages are (usually) 4 KB large, resulting in 1024 instruction call
slots. After the last of these instruction calls, there is an additional
call to a special "end of page" function (which doesn't count as an executed
instruction). This function switches to the first instruction
on the next virtual page (which might cause exceptions, etc).

<p>The complexity of individual instructions vary. A simple example of
what an instruction can look like is the MIPS <tt>addiu</tt> instruction:
<pre>
        X(addiu)
        {
                reg(ic->arg[1]) = (int32_t)
                    ((int32_t)reg(ic->arg[0]) + (int32_t)ic->arg[2]);
        }
</pre>

<p>It stores the result of a 32-bit addition of the register at arg[0]
with the immediate value arg[2] (treating both as signed 32-bit
integers) into register arg[1]. If the emulated CPU is a 64-bit CPU,
then this will store a correctly sign-extended value into arg[1].
If it is a 32-bit CPU, then only the lowest 32 bits will be stored,
and the high part ignored. <tt>X(addiu)</tt> is expanded to
<tt>mips_instr_addiu</tt> in the 64-bit case, and <tt>mips32_instr_addiu</tt>
in the 32-bit case. Both are compiled into the GXemul executable; no code 
is created during run-time.

<p>Here are examples of what the <tt>addiu</tt> instruction actually
looks like when it is compiled, on various host architectures:

<p><center><table border="0">
    <tr><td><b>GCC 4.0.1 on Alpha:</b></td>
        <td width="35"></td><td></td>
    <tr>
        <td valign="top">
<pre>mips_instr_addiu:
     ldq     t1,8(a1)
     ldq     t2,24(a1)
     ldq     t3,16(a1)
     ldq     t0,0(t1)
     addl    t0,t2,t0
     stq     t0,0(t3)
     ret</pre>
        </td>
        <td></td>
        <td valign="top">
<pre>mips32_instr_addiu:
     ldq     t2,8(a1)
     ldq     t0,24(a1)
     ldq     t3,16(a1)
     ldl     t1,0(t2)
     addq    t0,t1,t0
     stl     t0,0(t3)
     ret</pre>
        </td>
    </tr>

    <tr><td><b><br>GCC 3.4.4 on AMD64:</b></td>
    <tr>
        <td valign="top">
<pre>mips_instr_addiu:
     mov    0x8(%rsi),%rdx
     mov    0x18(%rsi),%rax
     mov    0x10(%rsi),%rcx
     add    (%rdx),%eax
     cltq
     mov    %rax,(%rcx)
     retq</pre>
        </td>
        <td></td>
        <td valign="top">
<pre>mips32_instr_addiu:
     mov    0x8(%rsi),%rcx
     mov    0x10(%rsi),%rdx
     mov    (%rcx),%eax
     add    0x18(%rsi),%eax
     mov    %eax,(%rdx)
     retq</pre>
        </td>
    </tr>

    <tr><td><b><br>GCC 4.0.1 on i386:</b></td>
    <tr>
        <td valign="top">
<pre>mips_instr_addiu:
     mov    0x8(%esp),%eax
     mov    0x8(%eax),%ecx
     mov    0x4(%eax),%edx
     mov    0xc(%eax),%eax
     add    (%edx),%eax
     mov    %eax,(%ecx)
     cltd
     mov    %edx,0x4(%ecx)
     ret</pre>
        </td>
        <td></td>
        <td valign="top">
<pre>mips32_instr_addiu:
     mov    0x8(%esp),%eax
     mov    0x8(%eax),%ecx
     mov    0x4(%eax),%edx
     mov    0xc(%eax),%eax
     add    (%edx),%eax
     mov    %eax,(%ecx)
     ret</pre>
        </td>
    </tr>
</table></center>

<p>On 64-bit hosts, there is not much difference, but on 32-bit hosts (and
to some extent on AMD64), the difference is enough to make it worthwhile.


<p><b>Performance:</b>

<p>The performance of using this kind of runnable IR is obviously lower
than what can be achieved by emulators using native code generation, but
can be significantly higher than using a naive fetch-decode-execute
interpretation loop. In my opinion, using a runnable IR is an interesting
compromise.

<p>The overhead per emulated instruction is usually around or below
approximately 10 host instructions. This is very much dependent on your
host architecture and what compiler and compiler switches you are using.
Added to this instruction count is (of course) also the C code used to
implement each specific instruction.

<p><b>Instruction Combinations:</b>

<p>Short, common instruction sequences can sometimes be replaced by a 
"compound" instruction. An example could be a compare instruction followed 
by a conditional branch instruction. The advantages of instruction 
combinations are that
<ul>
  <li>the amortized overhead per instruction is slightly reduced, and
  <p>
  <li>the host's compiler can make a good job at optimizing the common
        instruction sequence.
</ul>

<p>The special cases where instruction combinations give the most gain
are in the cores of string/memory manipulation functions such as 
<tt>memset()</tt> or <tt>strlen()</tt>. The core loop can then (at least
to some extent) be replaced by a native call to the equivalent function.

<p>The implementations of compound instructions still keep track of the
number of executed instructions, etc. When single-stepping, these
translations are invalidated, and replaced by normal instruction calls
(one per emulated instruction).

<p><b>Native Code Back-ends: (not in this release)</b>

<p>In theory, it will be possible to implement native code generation
(similar to what is used in high-performance emulators such as QEMU),
as long as that generated code abides to the C ABI on the host, but
for now I wanted to make sure that GXemul works without such native
code back-ends. For this reason, as of release 0.4.0, GXemul is
completely free of native code back-ends.


<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 (e.g. 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>The existance of instruction and data caches is "faked" to let
operating systems think that they are there, but for all practical
purposes, these caches are non-working.

<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>(Note that user interaction means <i>both</i> input to the emulated
program/OS, and interaction with the emulator's debugger. Breaking into the
debugger and then continuing execution may affect when/how interrupts
occur.)


<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>ARM</u></b>
  <ul>
    <li><b>CATS</b> (NetBSD/cats, OpenBSD/cats)
    <li><b>IQ80321</b> (NetBSD/evbarm)
  </ul>
  <p>
  <li><b><u>MIPS</u></b>
  <ul>
    <li><b>DECstation 5000/200</b> (NetBSD/pmax, OpenBSD/pmax, Ultrix,
        Linux/DECstation, Sprite)
    <li><b>Acer Pica-61</b> (NetBSD/arc)
    <li><b>NEC MobilePro 770, 780, 800, and 880</b> (NetBSD/hpcmips)
    <li><b>Cobalt</b> (NetBSD/cobalt)
    <li><b>Malta</b> (NetBSD/evbmips)
    <li><b>SGI O2 (aka IP32)</b> <font color="#0000e0">(<super>*</super>)</font>
        (NetBSD/sgi)
  </ul>
  <p>
  <li><b><u>PowerPC</u></b>
  <ul>
    <li><b>IBM 6050/6070 (PReP, PowerPC Reference Platform)</b> (NetBSD/prep)
  </ul>
</ul>

<p><small><font color="#0000e0">(<super>*</super>)</font> =
Enough for root-on-nfs, but not for disk boot.)</small>

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


</body>
</html>
1	<html><head><title>Gavare's eXperimental Emulator:   Introduction</title>
2	<meta name="robots" content="noarchive,nofollow,noindex"></head>
3	<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	<b>Gavare's eXperimental Emulator:</b></font><br>
8	<font color="#000000" size="6"><b>Introduction</b>
9	</font></td></tr></table></td></tr></table><p>
10
11	<!--
12
13	$Id: intro.html,v 1.87 2006/06/23 10:00:41 debug Exp $
14
15	Copyright (C) 2003-2006 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	<table border="0" width="99%"><tr><td valign="top" align="left">
49	<ul>
50	<li><a href="#overview">Overview</a>
51	<li><a href="#free">Is GXemul Free software?</a>
52	<li><a href="#build">How to compile/build the emulator</a>
53	<li><a href="#run">How to run the emulator</a>
54	<li><a href="#cpus">Which processor architectures does GXemul emulate?</a>
55	<li><a href="#hosts">Which host architectures are supported?</a>
56	<li><a href="#translation">What kind of translation does GXemul use?</a>
57	<li><a href="#accuracy">Emulation accuracy</a>
58	<li><a href="#emulmodes">Which machines does GXemul emulate?</a>
59	</ul>
60	</td><td valign="center" align="center">
61	<a href="20050317-example.png"><img src="20050317-example_small.png"></a>
62	<p>NetBSD/pmax 1.6.2 with X11<br>running in GXemul</td></tr></table>
63
64
65
66
67	<p><br>
68	<a name="overview"></a>
69	<h3>Overview:</h3>
70
71	GXemul is an experimental instruction-level machine emulator. Several
72	emulation modes are available. In some modes, processors and surrounding
73	hardware components are emulated well enough to let unmodified operating
74	systems (e.g. NetBSD) run as if they were running on a real machine.
75
76	<p>Devices and processors (ARM, MIPS, PowerPC) are not simulated with 100%
77	accuracy. They are only ``faked'' well enough to allow guest operating
78	systems run without complaining too much. Still, the emulator could be of
79	interest for academic research and experiments, such as when learning how
80	to write operating system code.
81
82	<p>The emulator is written in C, does not depend on third-party libraries,
83	and should compile and run on most 64-bit and 32-bit Unix-like systems.
84
85	<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	emulator itself, so you do not need to use any ROM image at all.
90
91	<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
96	<p>If you do not have a kernel as a separate file, but you have a bootable
97	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
101
102
103
104
105
106
107
108	<p><br>
109	<a name="free"></a>
110	<h3>Is GXemul Free software?</h3>
111
112	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
118	<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
128	<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
136	<p>In case you want to reuse parts of GXemul, but you need to do that
137	under a different license (e.g. the GPL), then contact me and I might
138	re-license/dual-license files on a case-by-case basis.
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>This should work on most Unix-like systems. GXemul does not require any
155	specific libraries to build, however, if you build on a system which does
156	not have X11 libraries installed, some functionality will be lost.
157
158	<p>The emulator's performance is highly dependent on both runtime settings
159	and on compiler settings, so you might want to experiment with different
160	CC and CFLAGS environment variable values. For example, on an AMD Athlon
161	host, you might want to try setting <tt>CFLAGS</tt> to <tt>-march=athlon</tt>
162	before running <tt>configure</tt>.
163
164
165
166
167
168
169
170	<p><br>
171	<a name="run"></a>
172	<h3>How to run the emulator:</h3>
173
174	Once you have built GXemul, running it should be rather straight-forward.
175	Running <tt><b>gxemul</b></tt> without arguments (or with the
176	<b><tt>-h</tt></b> or <b><tt>-H</tt></b> command line options) will
177	display a help message.
178
179	<p>
180	To get some ideas about what is possible to run in the emulator, please
181	read the section about <a href="guestoses.html">installing "guest"
182	operating systems</a>. If you are interested in using the emulator to
183	develop code on your own, then you should also read the section about
184	<a href="experiments.html#hello">Hello World</a>.
185
186	<p>
187	To exit the emulator, type CTRL-C to enter the
188	single-step debugger, and then type <tt><b>quit</b></tt>.
189
190	<p>
191	If you are starting an emulation by entering settings directly on the
192	command line, and you are not using the <tt><b>-x</b></tt> option, then all
193	terminal input and output will go to the main controlling terminal.
194	CTRL-C is used to break into the debugger, so in order to send CTRL-C to
195	the running (emulated) program, you may use CTRL-B.
196	(This should be a reasonable compromise to allow the emulator to be usable
197	even on systems without X Windows.)
198
199	<p>
200	There is no way to send an actual CTRL-B to the emulated program, when
201	typing in the main controlling terminal window. The solution is to either
202	use <a href="configfiles.html">configuration files</a>, or use
203	<tt><b>-x</b></tt>. Both these solutions cause new xterms to be opened for
204	each emulated serial port that is written to. CTRL-B and CTRL-C both have
205	their original meaning in those xterm windows.
206
207
208
209
210
211	<p><br>
212	<a name="cpus"></a>
213	<h3>Which processor architectures does GXemul emulate?</h3>
214
215	The architectures that are emulated well enough to let at least one
216	guest operating system run (per architecture) are ARM, MIPS, and
217	PowerPC.
218
219
220
221
222
223	<p><br>
224	<a name="hosts"></a>
225	<h3>Which host architectures are supported?</h3>
226
227	As of release 0.4.0 of GXemul, the old binary translation subsystem, which
228	was used for emulation of MIPS processors on Alpha and i386 hosts, has
229	been removed. The current dynamic translation subsystem should work on any
230	host.
231
232
233
234
235
236	<p><br>
237	<a name="translation"></a>
238	<h3>What kind of translation does GXemul use?</h3>
239
240	<b>Static vs. dynamic:</b>
241
242	<p>In order to support guest operating systems, which can overwrite old
243	code pages in memory with new code, it is necessary to translate code
244	dynamically. It is not possible to do a "one-pass" (static) translation.
245	Self-modifying code and Just-in-Time compilers running inside
246	the emulator are other things that would not work with a static
247	translator. GXemul is a dynamic translator. However, it does not
248	necessarily translate into native code, like many other emulators.
249
250	<p><b>"Runnable" Intermediate Representation:</b>
251
252	<p>Dynamic translators usually translate from the emulated architecture
253	(e.g. MIPS) into a kind of <i>intermediate representation</i> (IR), and then
254	to native code (e.g. AMD64 or x86 code). Since one of my main goals for
255	GXemul is to keep everything as portable as possible, I have tried to make
256	sure that the IR is something which can be executed regardless of whether
257	the final step (translation from IR to native code) has been implemented
258	or not.
259
260	<p>The IR in GXemul consists of arrays of pointers to functions, and a few
261	arguments which are passed along to those functions. The functions are
262	implemented in either manually hand-coded C, or automatically generated C.
263	In any case, this is all statically linked into the GXemul binary at link
264	time.
265
266	<p>Here is a simplified diagram of how these arrays work.
267
268	<p><center><img src="simplified_dyntrans.png"></center>
269
270	<p>There is one instruction call slot for every possible program counter
271	location. In the MIPS case, instruction words are 32 bits in length,
272	and pages are (usually) 4 KB large, resulting in 1024 instruction call
273	slots. After the last of these instruction calls, there is an additional
274	call to a special "end of page" function (which doesn't count as an executed
275	instruction). This function switches to the first instruction
276	on the next virtual page (which might cause exceptions, etc).
277
278	<p>The complexity of individual instructions vary. A simple example of
279	what an instruction can look like is the MIPS <tt>addiu</tt> instruction:
280	<pre>
281	X(addiu)
282	{
283	reg(ic->arg[1]) = (int32_t)
284	((int32_t)reg(ic->arg[0]) + (int32_t)ic->arg[2]);
285	}
286	</pre>
287
288	<p>It stores the result of a 32-bit addition of the register at arg[0]
289	with the immediate value arg[2] (treating both as signed 32-bit
290	integers) into register arg[1]. If the emulated CPU is a 64-bit CPU,
291	then this will store a correctly sign-extended value into arg[1].
292	If it is a 32-bit CPU, then only the lowest 32 bits will be stored,
293	and the high part ignored. <tt>X(addiu)</tt> is expanded to
294	<tt>mips_instr_addiu</tt> in the 64-bit case, and <tt>mips32_instr_addiu</tt>
295	in the 32-bit case. Both are compiled into the GXemul executable; no code
296	is created during run-time.
297
298	<p>Here are examples of what the <tt>addiu</tt> instruction actually
299	looks like when it is compiled, on various host architectures:
300
301	<p><center><table border="0">
302	<tr><td><b>GCC 4.0.1 on Alpha:</b></td>
303	<td width="35"></td><td></td>
304	<tr>
305	<td valign="top">
306	<pre>mips_instr_addiu:
307	ldq t1,8(a1)
308	ldq t2,24(a1)
309	ldq t3,16(a1)
310	ldq t0,0(t1)
311	addl t0,t2,t0
312	stq t0,0(t3)
313	ret</pre>
314	</td>
315	<td></td>
316	<td valign="top">
317	<pre>mips32_instr_addiu:
318	ldq t2,8(a1)
319	ldq t0,24(a1)
320	ldq t3,16(a1)
321	ldl t1,0(t2)
322	addq t0,t1,t0
323	stl t0,0(t3)
324	ret</pre>
325	</td>
326	</tr>
327
328	<tr><td><b><br>GCC 3.4.4 on AMD64:</b></td>
329	<tr>
330	<td valign="top">
331	<pre>mips_instr_addiu:
332	mov 0x8(%rsi),%rdx
333	mov 0x18(%rsi),%rax
334	mov 0x10(%rsi),%rcx
335	add (%rdx),%eax
336	cltq
337	mov %rax,(%rcx)
338	retq</pre>
339	</td>
340	<td></td>
341	<td valign="top">
342	<pre>mips32_instr_addiu:
343	mov 0x8(%rsi),%rcx
344	mov 0x10(%rsi),%rdx
345	mov (%rcx),%eax
346	add 0x18(%rsi),%eax
347	mov %eax,(%rdx)
348	retq</pre>
349	</td>
350	</tr>
351
352	<tr><td><b><br>GCC 4.0.1 on i386:</b></td>
353	<tr>
354	<td valign="top">
355	<pre>mips_instr_addiu:
356	mov 0x8(%esp),%eax
357	mov 0x8(%eax),%ecx
358	mov 0x4(%eax),%edx
359	mov 0xc(%eax),%eax
360	add (%edx),%eax
361	mov %eax,(%ecx)
362	cltd
363	mov %edx,0x4(%ecx)
364	ret</pre>
365	</td>
366	<td></td>
367	<td valign="top">
368	<pre>mips32_instr_addiu:
369	mov 0x8(%esp),%eax
370	mov 0x8(%eax),%ecx
371	mov 0x4(%eax),%edx
372	mov 0xc(%eax),%eax
373	add (%edx),%eax
374	mov %eax,(%ecx)
375	ret</pre>
376	</td>
377	</tr>
378	</table></center>
379
380	<p>On 64-bit hosts, there is not much difference, but on 32-bit hosts (and
381	to some extent on AMD64), the difference is enough to make it worthwhile.
382
383
384	<p><b>Performance:</b>
385
386	<p>The performance of using this kind of runnable IR is obviously lower
387	than what can be achieved by emulators using native code generation, but
388	can be significantly higher than using a naive fetch-decode-execute
389	interpretation loop. In my opinion, using a runnable IR is an interesting
390	compromise.
391
392	<p>The overhead per emulated instruction is usually around or below
393	approximately 10 host instructions. This is very much dependent on your
394	host architecture and what compiler and compiler switches you are using.
395	Added to this instruction count is (of course) also the C code used to
396	implement each specific instruction.
397
398	<p><b>Instruction Combinations:</b>
399
400	<p>Short, common instruction sequences can sometimes be replaced by a
401	"compound" instruction. An example could be a compare instruction followed
402	by a conditional branch instruction. The advantages of instruction
403	combinations are that
404	<ul>
405	<li>the amortized overhead per instruction is slightly reduced, and
406	<p>
407	<li>the host's compiler can make a good job at optimizing the common
408	instruction sequence.
409	</ul>
410
411	<p>The special cases where instruction combinations give the most gain
412	are in the cores of string/memory manipulation functions such as
413	<tt>memset()</tt> or <tt>strlen()</tt>. The core loop can then (at least
414	to some extent) be replaced by a native call to the equivalent function.
415
416	<p>The implementations of compound instructions still keep track of the
417	number of executed instructions, etc. When single-stepping, these
418	translations are invalidated, and replaced by normal instruction calls
419	(one per emulated instruction).
420
421	<p><b>Native Code Back-ends: (not in this release)</b>
422
423	<p>In theory, it will be possible to implement native code generation
424	(similar to what is used in high-performance emulators such as QEMU),
425	as long as that generated code abides to the C ABI on the host, but
426	for now I wanted to make sure that GXemul works without such native
427	code back-ends. For this reason, as of release 0.4.0, GXemul is
428	completely free of native code back-ends.
429
430
431
432
433
434
435	<p><br>
436	<a name="accuracy"></a>
437	<h3>Emulation accuracy:</h3>
438
439	GXemul is an instruction-level emulator; things that would happen in
440	several steps within a real CPU are not taken into account (e.g. pipe-line
441	stalls or out-of-order execution). Still, instruction-level accuracy seems
442	to be enough to be able to run complete guest operating systems inside the
443	emulator.
444
445	<p>The existance of instruction and data caches is "faked" to let
446	operating systems think that they are there, but for all practical
447	purposes, these caches are non-working.
448
449	<p>The emulator is <i>not</i> timing-accurate. It can be run in a
450	"deterministic" mode, <tt><b>-D</b></tt>. The meaning of deterministic is
451	simply that running two emulations with the same settings will result in
452	identical runs. Obviously, this requires that no user interaction is
453	taking place, and that clock speeds are fixed with the <tt><b>-I</b></tt>
454	option. (Deterministic in this case does <i>not</i> mean that the
455	emulation will be identical to some actual real-world machine.)
456
457	<p>(Note that user interaction means <i>both</i> input to the emulated
458	program/OS, and interaction with the emulator's debugger. Breaking into the
459	debugger and then continuing execution may affect when/how interrupts
460	occur.)
461
462
463
464
465
466
467	<p><br>
468	<a name="emulmodes"></a>
469	<h3>Which machines does GXemul emulate?</h3>
470
471	A few different machine types are emulated. The following machine types
472	are emulated well enough to run at least one "guest OS":
473
474	<p>
475	<ul>
476	<li><b><u>ARM</u></b>
477	<ul>
478	<li><b>CATS</b> (NetBSD/cats, OpenBSD/cats)
479	<li><b>IQ80321</b> (NetBSD/evbarm)
480	</ul>
481	<p>
482	<li><b><u>MIPS</u></b>
483	<ul>
484	<li><b>DECstation 5000/200</b> (NetBSD/pmax, OpenBSD/pmax, Ultrix,
485	Linux/DECstation, Sprite)
486	<li><b>Acer Pica-61</b> (NetBSD/arc)
487	<li><b>NEC MobilePro 770, 780, 800, and 880</b> (NetBSD/hpcmips)
488	<li><b>Cobalt</b> (NetBSD/cobalt)
489	<li><b>Malta</b> (NetBSD/evbmips)
490	<li><b>SGI O2 (aka IP32)</b> <font color="#0000e0">(<super>*</super>)</font>
491	(NetBSD/sgi)
492	</ul>
493	<p>
494	<li><b><u>PowerPC</u></b>
495	<ul>
496	<li><b>IBM 6050/6070 (PReP, PowerPC Reference Platform)</b> (NetBSD/prep)
497	</ul>
498	</ul>
499
500	<p><small><font color="#0000e0">(<super>*</super>)</font> =
501	Enough for root-on-nfs, but not for disk boot.)</small>
502
503	<p>There is code in GXemul for emulation of many other machine types; the
504	degree to which these work range from almost being able to run a complete
505	OS, to almost completely unsupported (perhaps just enough support to
506	output a few boot messages via serial console).
507
508	<p>In addition to emulating real machines, there is also a "test-machine".
509	A test-machine consists of one or more CPUs and a few experimental devices
510	such as:
511
512	<p>
513	<ul>
514	<li>a console I/O device (putchar() and getchar()...)
515	<li>an inter-processor communication device, for SMP experiments
516	<li>a very simple linear framebuffer device (for graphics output)
517	<li>a simple SCSI disk controller
518	<li>a simple ethernet controller
519	</ul>
520
521	<p>This mode is useful if you wish to run experimental code, but do not
522	wish to target any specific real-world machine type, for example for
523	educational purposes.
524
525	<p>You can read more about these experimental devices <a
526	href="experiments.html#expdevices">here</a>.
527
528
529
530
531
532
533	</body>
534	</html>