--- trunk/doc/intro.html	2007/10/08 16:19:37	22
+++ trunk/doc/intro.html	2007/10/08 16:21:53	38
@@ -10,9 +10,9 @@
 
 <!--
 
-$Id: intro.html,v 1.73 2006/02/18 14:02:19 debug Exp $
+$Id: intro.html,v 1.108 2007/04/12 16:57:22 debug Exp $
 
-Copyright (C) 2003-2006  Anders Gavare.  All rights reserved.
+Copyright (C) 2003-2007  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:
@@ -52,6 +52,7 @@
   <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="#accuracy">Emulation accuracy</a>
   <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
 </ul>
@@ -71,13 +72,10 @@
 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
+<p>Devices and processors are not simulated with 100% accuracy. They are 
+only ``faked'' well enough to allow guest operating systems to 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,
@@ -96,9 +94,13 @@
 
 <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.)
-
+image. (This works for example with DECstation emulation, Dreamcast 
+emulation, or when booting from generic ISO9660 CDROM images if the 
+kernel is included in the image as a plain file.)
+
+<p>Thanks to (in no specific order) Joachim Buss, Olivier Houchard, Juli 
+Mallett, Juan Romero Pardines, Alec Voropay, Göran Weinholt, Alexander 
+Yurchenko, and everyone else who has provided me with feedback.
 
 
 
@@ -159,8 +161,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 +215,30 @@
 <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, PowerPC,
+and SuperH.
+
+<p>Please read the page about <a href="guestoses.html">guest operating
+systems</a> for more information about the machines and operating systems 
+that can be considered "working" in the emulator.
 
-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.)
 
-<h4>ARM:</h4>
 
-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.
 
-<h4>PowerPC:</h4>
 
-PowerPC emulation is still in its beginning stages, but good enough
-to run NetBSD/prep 2.1.
+<p><br>
+<a name="hosts"></a>
+<h3>Which host architectures are supported?</h3>
+
+GXemul should compile and run on any modern host architecture (64-bit or 
+32-bit word-length).
 
-<p>Non-MIPS emulation modes use dynamic translation, but not recompilation 
-into native code. This makes it possible to run on any host platform.
+<p>Note: The <a href="translation.html">dynamic translation</a> engine 
+does <i>not</i> require backends for native code generation to be written 
+for each individual host architecture; the intermediate representation 
+that the dyntrans system uses can be executed on any host architecture.
 
 
 
@@ -249,28 +249,25 @@
 <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 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><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>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 in general <i>not</i> timing-accurate, neither at the
+instruction level nor on any higher level. An attempt is made to let
+emulated clocks run at the same speed as the host (i.e. an emulated timer
+running at 100 Hz will interrupt around 100 times per real second), but
+since the host speed may vary, e.g. because of other running processes,
+there is no guarantee as to how many instructions will be executed in
+each of these 100 Hz cycles.
+
+<p>If the host is very slow, the emulated clocks might even lag behind
+the real-world clock.
 
 
 
@@ -286,30 +283,52 @@
 
 <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> (<a href="guestoses.html#netbsdcatsinstall">NetBSD/cats</a>,
+	<a href="guestoses.html#openbsdcatsinstall">OpenBSD/cats</a>)
+    <li><b>IQ80321</b> (<a href="guestoses.html#netbsdevbarminstall">NetBSD/evbarm</a>)
+    <li><b>NetWinder</b> (<a href="guestoses.html#netbsdnetwinderinstall">NetBSD/netwinder</a>)
   </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> (<a href="guestoses.html#netbsdpmaxinstall">NetBSD/pmax</a>,
+	<a href="guestoses.html#openbsdpmaxinstall">OpenBSD/pmax</a>,
+	<a href="guestoses.html#ultrixinstall">Ultrix</a>,
+	<a href="guestoses.html#declinux">Linux/DECstation</a>,
+	<a href="guestoses.html#sprite">Sprite</a>)
+    <li><b>Acer Pica-61</b> (<a href="guestoses.html#netbsdarcinstall">NetBSD/arc</a>)
+    <li><b>NEC MobilePro 770, 780, 800, 880</b> (<a href="guestoses.html#netbsdhpcmipsinstall">NetBSD/hpcmips</a>)
+    <li><b>Cobalt</b> (<a href="guestoses.html#netbsdcobaltinstall">NetBSD/cobalt</a>)
+    <li><b>Malta</b> (<a href="guestoses.html#netbsdevbmipsinstall">NetBSD/evbmips</a>, Linux/Malta <font color="#0000e0">(<super>*1</super>)</font>)
+    <li><b>Algorithmics P5064</b> (<a href="guestoses.html#netbsdalgorinstall">NetBSD/algor</a>)
+    <li><b>SGI O2 (aka IP32)</b> <font color="#0000e0">(<super>*2</super>)</font>
+	(<a href="guestoses.html#netbsdsgimips">NetBSD/sgi</a>)
   </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> (<a href="guestoses.html#netbsdprepinstall">NetBSD/prep</a>)
+    <li><b>MacPPC (generic "G4" Macintosh)</b> (<a href="guestoses.html#netbsdmacppcinstall">NetBSD/macppc</a>)
+  </ul>
+  <p>
+  <li><b><u>SuperH</u></b>
+  <ul>
+    <li><b>Sega Dreamcast</b> (<a href="dreamcast.html#netbsd_generic_md">NetBSD/dreamcast</a>, <a href="dreamcast.html#linux_live_cd">Linux/dreamcast</a>)
   </ul>
 </ul>
 
-<p><small><font color="#0000e0">(<super>*</super>)</font> =
-Enough for root-on-nfs, but not for disk boot.)</small>
+<p>
+<small><font color="#0000e0">(<super>*1</super>)</font> =
+Linux/Malta may be run as a guest OS, however I have not yet found any stable
+URL to pre-compiled Linux/Malta kernels. Thus, Linux/Malta emulation is not
+tested for every release of the emulator; sometimes it works, sometimes
+it doesn't.</small>
+
+<br><small><font color="#0000e0">(<super>*2</super>)</font> =
+SGI O2 emulation is 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
@@ -325,8 +344,9 @@
   <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 disk controller
   <li>a simple ethernet controller
+  <li>a real-time clock device
 </ul>
 
 <p>This mode is useful if you wish to run experimental code, but do not