upstream/0.4.4.1/README

Gavare's eXperimental Emulator   --   GXemul 0.4.4.1
====================================================

Copyright (C) 2003-2007  Anders Gavare.


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.

Processors (ARM, MIPS, PowerPC, SuperH) are emulated using dynamic 
translation. Unlike some other dynamically translating emulators, GXemul 
does not need to generate native code, only a "runnable intermediate 
representation", and will thus run on any host architecture.

The documentation lists the machines and guest operating systems that can 
be regarded as "working" in GXemul. The best working guest operating 
systems are probably NetBSD/pmax and NetBSD/cats.

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 it does 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 rest of the documentation in the doc/ sub-directory for
more detailed information on how to use the emulator.


Feedback
--------

If you have found GXemul useful in some way, or feel like sending me
comments or feedback in general, then mail me at anders(at)gavare.se.

1	dpavlin	36	Gavare's eXperimental Emulator -- GXemul 0.4.4.1
2			====================================================
3	dpavlin	2
4	dpavlin	34	Copyright (C) 2003-2007 Anders Gavare.
5	dpavlin	2
6
7	dpavlin	24	Overview -- What is GXemul?
8			-----------------------------
9	dpavlin	2
10	dpavlin	14	GXemul is an experimental instruction-level machine emulator. Several
11			emulation modes are available. In some modes, processors and surrounding
12	dpavlin	12	hardware components are emulated well enough to let unmodified operating
13			systems (e.g. NetBSD) run as if they were running on a real machine.
14	dpavlin	2
15	dpavlin	34	Processors (ARM, MIPS, PowerPC, SuperH) are emulated using dynamic
16			translation. Unlike some other dynamically translating emulators, GXemul
17			does not need to generate native code, only a "runnable intermediate
18			representation", and will thus run on any host architecture.
19	dpavlin	2
20	dpavlin	34	The documentation lists the machines and guest operating systems that can
21			be regarded as "working" in GXemul. The best working guest operating
22			systems are probably NetBSD/pmax and NetBSD/cats.
23
24	dpavlin	24	Possible uses of the emulator include:
25	dpavlin	12
26	dpavlin	24	o) educational purposes, e.g. to learn how to write code for MIPS
27	dpavlin	20
28	dpavlin	24	o) hobby operating system development; the emulator can be used as a
29			complement to testing your code on real hardware
30
31			o) running guest operating systems in a "sandboxed" environment
32
33			o) compiling your source code inside a guest operating system which you
34			otherwise would not have access to (e.g. various exotic ports of
35			NetBSD), to make sure that your source code is portable to those
36			platforms
37
38			o) simulating (ethernet) networks of computers running various
39			operating systems, to study their interaction with each other
40
41			o) debugging code in general
42
43			Use your imagination :-)
44
45
46			GXemul's limitations
47			--------------------
48
49			o) GXemul is not (in general) a cycle-accurate simulator, because it does
50			not simulate things smaller than an instruction. Pipe-line stalls,
51			instruction latency effects etc. are more or less completely ignored.
52
53			o) Hardware devices have been implemented in an ad-hoc and as-needed
54			manner, usually only enough to fool certain guest operating systems
55			(e.g. NetBSD) that the hardware devices exist and function well
56			enough for those guest operating systems to use them.
57
58			A consequence of this is that a machine mode may be implemented well
59			enough to run NetBSD for that machine mode, but other guest operating
60			systems may not run at all, or behave strangely.
61
62
63	dpavlin	2	Quick start
64			-----------
65
66	dpavlin	4	To compile, type './configure' and then 'make'. This should work on most
67	dpavlin	28	Unix-like systems. If it does not, then please mail me a bug report.
68	dpavlin	2
69	dpavlin	24	You might want to experiment with various CC and CFLAGS environment
70			variable settings, to get optimum performance.
71
72	dpavlin	10	If you are impatient, and want to try out running a guest operating system
73	dpavlin	22	inside GXemul, read this: doc/guestoses.html#netbsdcatsinstall
74	dpavlin	2
75	dpavlin	10	If you want to use GXemul for experimenting with code of your own,
76			then I suggest you compile a Hello World program according to the tips
77			listed here: doc/experiments.html#hello
78	dpavlin	2
79	dpavlin	10	Please read the rest of the documentation in the doc/ sub-directory for
80			more detailed information on how to use the emulator.
81
82
83	dpavlin	2	Feedback
84			--------
85
86			If you have found GXemul useful in some way, or feel like sending me
87			comments or feedback in general, then mail me at anders(at)gavare.se.
88