--- trunk/doc/intro.html	2007/10/08 16:22:11	40
+++ trunk/doc/intro.html	2007/10/08 16:22:32	42
@@ -10,7 +10,7 @@
 
 <!--
 
-$Id: intro.html,v 1.110 2007/04/28 00:12:03 debug Exp $
+$Id: intro.html,v 1.118 2007/06/15 21:43:09 debug Exp $
 
 Copyright (C) 2003-2007  Anders Gavare.  All rights reserved.
 
@@ -52,7 +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="#hosts">Which host architectures/platforms are supported?</a>
   <li><a href="#accuracy">Emulation accuracy</a>
   <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
 </ul>
@@ -67,10 +67,15 @@
 <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.
+GXemul is an experimental <a href="#accuracy">instruction-level</a> 
+machine emulator. Several emulation modes are available. In some modes, 
+processors and surrounding hardware components are emulated well enough to 
+let <a href="#emulmodes">unmodified operating systems (e.g. NetBSD)
+run</a> as if they were running on a real machine.
+
+<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, 
+with few or no modifications.
 
 <p>Devices and processors are not simulated with 100% accuracy. They are 
 only ``faked'' well enough to allow guest operating systems to run without 
@@ -78,30 +83,30 @@
 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
+in the emulator. For some 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>You can use pre-compiled kernels (for example <a href="http://www.netbsd.org/">NetBSD</a>
+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:
+<a href="http://en.wikipedia.org/wiki/Executable_and_Linkable_Format">ELF</a>,
+<a href="http://en.wikipedia.org/wiki/A.out">a.out</a>,
+<a href="http://en.wikipedia.org/wiki/COFF">COFF</a>/<a href="http://en.wikipedia.org/wiki/ECOFF">ECOFF</a>,
+<a href="http://en.wikipedia.org/wiki/SREC_%28file_format%29">SREC</a>, 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, Dreamcast 
-emulation, or when booting from generic ISO9660 CDROM images if the 
-kernel is included in the image as a plain file.)
+image. This works for example with DECstation emulation, <a href="dreamcast.html">Dreamcast 
+emulation</a>, or when booting from generic <a href="http://en.wikipedia.org/wiki/ISO9660">ISO9660</a>
+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, Carl van Schaik, Alec Voropay, Göran
-Weinholt, Alexander Yurchenko, and everyone else who has provided me with
-feedback.
+Mallett, Juan Romero Pardines, Carl van Schaik, Miod Vallat, Alec Voropay,
+Göran Weinholt, Alexander Yurchenko, and everyone else who has provided me
+with feedback.
 
 
 
@@ -160,10 +165,13 @@
 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>.
+and on compiler settings, so you might want to experiment with 
+using different CC and CFLAGS environment variable values when running the 
+<tt>configure</tt> script.
+
+<p>Note that there is no <tt>make install</tt> functionality; package
+maintainers for individual operating systems solve this for their 
+corresponding OSes.
 
 
 
@@ -180,30 +188,31 @@
 <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 
+<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>.
+operating systems</a>. The most straight forward guest operating to 
+install is NetBSD/pmax; the instructions provided <a 
+href="guestoses.html#netbsdpmaxinstall">here</a> should let you install 
+NetBSD/pmax in a way very similar to how it is done on a real DECstation.
+
+<p>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 
+<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.
+<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
+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.
@@ -222,7 +231,9 @@
 
 <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.
+that can be considered "working" in the emulator. (There is some code in 
+GXemul for emulation of other architectures, but they are not stable or
+complete enough to be listed among the "working" architectures.)
 
 
 
@@ -231,16 +242,25 @@
 
 <p><br>
 <a name="hosts"></a>
-<h3>Which host architectures are supported?</h3>
+<h3>Which host architectures/platforms are supported?</h3>
 
 GXemul should compile and run on any modern host architecture (64-bit or 
-32-bit word-length).
+32-bit word-length). I generally test it on FreeBSD/amd64 6.x, 
+FreeBSD/alpha 4.x, sometimes also on Linux (various platforms), and every
+now and then also on NetBSD inside the emulator itself (various platforms).
 
-<p>Note: The <a href="translation.html">dynamic translation</a> engine 
+<p>Note 1: 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.
 
+<p>Note 2: Although GXemul may build and run on non-Unix-like platforms,
+such as Cygwin, Unix-like systems are the primary platform. Some 
+functionality may be lost when running on Cygwin.
+
+
+
+
 
 
 
@@ -312,12 +332,13 @@
   <ul>
     <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>)
+    <li><b>Artesyn PM/PPC</b> (<a href="guestoses.html#netbsdpmppc">NetBSD/pmppc</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>)
-    <li><b>Landisk</b> (<a href="guestoses.html#openbsdlandiskinstall">OpenBSD/landisk</a>)
+    <li><b>Landisk I-O DATA USL-5P</b> (<a href="guestoses.html#openbsdlandiskinstall">OpenBSD/landisk</a>)
   </ul>
 </ul>
 
@@ -331,11 +352,18 @@
 <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>Note that of all of the machines above, none of them is emulated to 
+100%. The most complete emulation mode is probably the DECstation 
+5000/200. Things that will most likely <b>not</b> work include running 
+raw PROM images for most machines, SGI IRIX, MacOS X or Darwin, Windows 
+NT, or Dreamcast games.
 
-<p>There is code in GXemul for emulation of many other machine types; the
+<p>There is code in GXemul for emulation of several 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).
+OS, to almost completely unsupported, perhaps just enough support to
+output a few boot messages via serial console. (See the end of
+<a href="guestoses.html#generalnotes">this section</a> on the Guest OSes 
+page for some examples, but remember that these do not necessarily work.)
 
 <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