--- trunk/README	2007/10/08 16:17:48	2
+++ trunk/README	2007/10/08 16:20:10	26
@@ -1,27 +1,81 @@
-GXemul 0.3.1
-============
+Gavare's eXperimental Emulator   --   GXemul 0.4.0.1
+====================================================
 
-Copyright (C) 2003-2005  Anders Gavare.
+Copyright (C) 2003-2006  Anders Gavare.
 
 
-Overview
---------
+Overview  --  What is GXemul?
+-----------------------------
 
-GXemul is an experimental instruction-level machine emulator. It can be
-used to run binary code for (among others) MIPS-based machines. Several
-emulation modes are available. For some emulation modes, processors and
-surrounding hardware components are emulated well enough to let unmodified
-operating systems (eg. NetBSD) run as if they were running on a real machine.
+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.
+
+Processors (ARM, MIPS, PowerPC) are emulated using a kind of dynamic 
+translation system. Performance is somewhere between traditional 
+interpretation and recompilation into native code. However, the dynamic 
+translation system used in GXemul does not (currently) generate native 
+code, and thus does not require platform-specific back-ends. In plain 
+English, this means that the dyntrans system works on any host platform.
+
+Possible uses of the emulator include:
+
+ o)  educational purposes, e.g. to learn how to write code for MIPS
+
+ o)  hobby operating system development; the emulator can be used as a
+     complement to testing your code on real hardware
+
+ o)  running guest operating systems in a "sandboxed" environment
+
+ o)  compiling your source code inside a guest operating system which you
+     otherwise would not have access to (e.g. various exotic ports of
+     NetBSD), to make sure that your source code is portable to those
+     platforms
+
+ o)  simulating (ethernet) networks of computers running various
+     operating systems, to study their interaction with each other
+
+ o)  debugging code in general
+
+Use your imagination :-)
+
+
+GXemul's limitations
+--------------------
+
+ o)  GXemul is not (in general) a cycle-accurate simulator, because it does
+     not simulate things smaller than an instruction. Pipe-line stalls,
+     instruction latency effects etc. are more or less completely ignored.
+
+ o)  Hardware devices have been implemented in an ad-hoc and as-needed
+     manner, usually only enough to fool certain guest operating systems
+     (e.g. NetBSD) that the hardware devices exist and function well
+     enough for those guest operating systems to use them.
+
+     A consequence of this is that a machine mode may be implemented well
+     enough to run NetBSD for that machine mode, but other guest operating
+     systems may not run at all, or behave strangely.
 
 
 Quick start
 -----------
 
-To compile, type './configure' and then 'make'.  This should work on most
-Unix- like systems, if not then please mail me a bug report.
+To compile, type './configure' and then 'make'. This should work on most
+Unix-like systems. If not, then please mail me a bug report.
+
+You might want to experiment with various CC and CFLAGS environment
+variable settings, to get optimum performance.
+
+If you are impatient, and want to try out running a guest operating system 
+inside GXemul, read this:  doc/guestoses.html#netbsdcatsinstall
+
+If you want to use GXemul for experimenting with code of your own, 
+then I suggest you compile a Hello World program according to the tips 
+listed here:  doc/experiments.html#hello
 
-Please read the the documentation in the doc/ sub-directory for more
-detailed information on how to use the emulator.
+Please read the rest of the documentation in the doc/ sub-directory for
+more detailed information on how to use the emulator.
 
 
 Feedback