--- trunk/doc/intro.html	2007/10/08 16:19:37	22
+++ trunk/doc/intro.html	2007/10/08 16:19:56	24
@@ -10,7 +10,7 @@
 
 <!--
 
-$Id: intro.html,v 1.73 2006/02/18 14:02:19 debug Exp $
+$Id: intro.html,v 1.87 2006/06/23 10:00:41 debug Exp $
 
 Copyright (C) 2003-2006  Anders Gavare.  All rights reserved.
 
@@ -52,6 +52,8 @@
   <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>
@@ -71,14 +73,11 @@
 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 such as ARM and PowerPC are also partially emulated.
-
-<p>Devices and CPUs 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>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.
@@ -159,8 +158,8 @@
 <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 
--O3</tt> before running <tt>configure</tt>.
+host, you might want to try setting <tt>CFLAGS</tt> to <tt>-march=athlon</tt>
+before running <tt>configure</tt>.
 
 
 
@@ -213,32 +212,221 @@
 <a name="cpus"></a>
 <h3>Which processor architectures does GXemul emulate?</h3>
 
-<h4>MIPS:</h4>
+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.
+
+
+
 
-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. Several guest operating systems for MIPS can run inside
-the emulator.
 
-<p>(For MIPS emulation, I have written an experimental dynamic binary
-translation subsystem, for Alpha and i386 hosts. 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.)
+<p><br>
+<a name="translation"></a>
+<h3>What kind of translation does GXemul use?</h3>
 
-<h4>ARM:</h4>
+<b>Static vs. dynamic:</b>
 
-ARM emulation is good enough to run NetBSD/cats, OpenBSD/cats, and 
-NetBSD/evbarm, but it is not as tested or fine-tuned as the MIPS emulation 
-mode.
+<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).
 
-<h4>PowerPC:</h4>
+<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>
 
-PowerPC emulation is still in its beginning stages, but good enough
-to run NetBSD/prep 2.1.
+<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>Non-MIPS emulation modes use dynamic translation, but not recompilation 
-into native code. This makes it possible to run on any host platform.
 
 
 
@@ -249,15 +437,14 @@
 <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
+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>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 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
@@ -267,10 +454,10 @@
 option. (Deterministic in this case does <i>not</i> mean that the
 emulation will be identical to some actual real-world machine.)
 
-<p><font color="#ff0000">(Oops/TODO: User interaction means <i>both</i>
-input to the emulated program/OS, and interacting with the emulator
-itself. Breaking into the debugger and then continuing execution may
-affect when/how interrupts occur.)</font>
+<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.)
 
 
 
@@ -286,25 +473,27 @@
 
 <p>
 <ul>
-  <li><b><u>MIPS</u></b>
+  <li><b><u>ARM</u></b>
   <ul>
-    <li><b>DECstation 5000/200</b>&nbsp;&nbsp;("3max")
-    <li><b>Acer Pica-61</b>&nbsp;&nbsp;(an ARC machine)
-    <li><b>NEC MobilePro 770, 780, 800, and 880</b>&nbsp;&nbsp;(HPCmips machines)
-    <li><b>Cobalt</b>
-    <li><b>Malta</b> (evbmips)
-    <li><b>SGI O2 ("IP32")</b> <font color="#0000e0">(<super>*</super>)</font>
+    <li><b>CATS</b> (NetBSD/cats, OpenBSD/cats)
+    <li><b>IQ80321</b> (NetBSD/evbarm)
   </ul>
   <p>
-  <li><b><u>ARM</u></b>
+  <li><b><u>MIPS</u></b>
   <ul>
-    <li><b>CATS</b>
-    <li><b>IQ80321</b> (evbarm)
+    <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>PReP (PowerPC Reference Platform)</b>
+    <li><b>IBM 6050/6070 (PReP, PowerPC Reference Platform)</b> (NetBSD/prep)
   </ul>
 </ul>