--- trunk/README	2007/10/08 16:18:51	14
+++ trunk/README	2007/10/08 16:20:10	26
@@ -1,19 +1,61 @@
-Gavare's eXperimental Emulator   --   GXemul 0.3.6
-==================================================
+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. 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.
 
-The processor architecture best emulated by GXemul is MIPS, but other
-architectures are also partially emulated.
+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
@@ -22,8 +64,11 @@
 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, please read this:  doc/guestoses.html#netbsdinstall
+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