--- trunk/doc/intro.html	2007/10/08 16:18:00	4
+++ trunk/doc/intro.html	2007/10/08 16:18:11	6
@@ -13,7 +13,7 @@
 
 <!--
 
-$Id: intro.html,v 1.40 2005/04/27 15:22:17 debug Exp $
+$Id: intro.html,v 1.46 2005/06/04 12:02:17 debug Exp $
 
 Copyright (C) 2003-2005  Anders Gavare.  All rights reserved.
 
@@ -52,6 +52,7 @@
   <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>
@@ -73,10 +74,10 @@
 systems run as if they were running on a real machine.
 
 <p>
-It is important to keep in mind that devices and CPUs are not simulated 
-with 100% accuracy. They are only "faked" well enough to make operating 
-systems (eg NetBSD) run. Still, the emulator could be of interest for
-academic research and experiments, such as when learning how to write 
+Devices and CPUs are not simulated with 100% accuracy. They are only
+"faked" well enough to make operating systems (eg 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>
@@ -85,10 +86,7 @@
 systems. If it doesn't, then that is a bug.
 (You do not need any MIPS compiler toolchain to build or use GXemul.
 If you need to compile MIPS binaries from sources, then of course you need 
-such a toolchain, but that is completely separate from GXemul. There
-is a <a href="technical.html#regtest">regression testing</a> framework,
-which requires that a GNU CC for mips64-unknown-elf or similar is available.
-For simply building and using the emulator, it is not required.) 
+such a toolchain, but that is completely separate from GXemul.)
 
 <p>
 The emulator contains code which tries to emulate the workings of CPUs and
@@ -101,7 +99,14 @@
 You can use pre-compiled kernels (for example NetBSD kernels, or Linux),
 or other programs that are in binary format, and in some cases even actual
 ROM images. A couple of different file formats are supported (ELF, a.out,
-ECOFF, SREC, raw binaries).
+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.)
+
 
 
 
@@ -111,14 +116,11 @@
 <a name="free"></a>
 <h3>Is GXemul Free software?</h3>
 
-Yes. I have released GXemul under a Free license.
-(For a definitions of the four freedoms associated with Free software,
-please read <a href="http://www.gnu.org/philosophy/free-sw.html">
-http://www.gnu.org/philosophy/free-sw.html</a>.)
-
-<p>
-The code in GXemul is Copyrighted software, it is <i>not</i> public
-domain or anything like that.
+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
@@ -171,29 +173,50 @@
 </pre>
 
 <p>
-Run <b>./configure --help</b> to get a list of configure options. (The 
+Run <b><tt>./configure --help</tt></b> to get a list of configure options. (The 
 possible options differ between different releases and snapshots.)
 
-<p>
+
+
+
+
+
+<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 <b>quit</b>.
+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 <b>-x</b> option, then all 
+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>
-(This is an ugly hack; there is no way to send an actual CTRL-B to the
-emulated program, when typing in the main controlling terminal window.
-The solution is to either use configuration files, or use <b>-x</b>. Both 
-these solutions cause new xterms to be opened for each emulated serial 
-port. CTRL-B and CTRL-C both have their original meaning in those 
-xterm windows.)
-
+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.
 
 
 
@@ -205,10 +228,10 @@
 
 <h4>MIPS:</h4>
 
-Emulation of R4000, which is a 64-bit CPU, was my initial goal. Right
-now, R2000/R3000-like CPUs are also emulated (32-bit), and emulation of
-R1x000 (at least the parts that are similar to R4000) is beginning to work
-as expected. Code targeted for MIPS32 and MIPS64 also often work.
+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.
@@ -217,7 +240,6 @@
 the command line, but keep in mind that it is still experimental.)
 
 
-
 <h4>URISC:</h4>
 
 I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
@@ -228,13 +250,17 @@
 performance.)
 
 
+<h4>POWER/PowerPC</h4>
+
+There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation, enough
+to run "Hello World", but not enough to run complete operating systems.  
+This mode isn't really working yet.
 
 
 <h4>Other CPU types:</h4>
 
-There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation too,
-but it only works for "Hello World" and similarly trivial programs. (There
-are some other CPU modes too, but they are working even less.)
+Some other CPU architectures (such as x86) can also be partially emulated.
+These are not enabled by default though, because of their unstable-ness.
 
 
 
@@ -244,12 +270,27 @@
 <a name="accuracy"></a>
 <h3>Emulation accuracy:</h3>
 
-GXemul is an instruction-level simulator; things that would happen in
+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
-stages or out-of-order execution). Still, instruction-level accuracy seems 
-to be enough to be able to run complete guest operating systems inside the 
+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.)
+
 
 
 
@@ -322,7 +363,7 @@
 <center><table border="0">
 	<tr>
 	  <td width="10"></td>
-	  <td align="center"><a href="netbsd-pmax-20040630.png"><img src="netbsd-pmax-20040630_small.png"></a></td>
+	  <td 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>