Annotation of /upstream/20070918/README



          --------------------------------------------------------
            Gavare's eXperimental Emulator   --   GXemul 0.4.6.1
          --------------------------------------------------------


Copyright (C) 2003-2007  Anders Gavare


Overview  --  What is GXemul?
-----------------------------

GXemul is a framework for full-system computer architecture emulation. 
Several processor architectures and machine types have been implemented. 
It is working well enough to allow unmodified "guest" operating systems to 
run inside the emulator, as if they were running on real hardware.

The emulator emulates (networks of) real machines. The machines may 
consist of ARM, MIPS, PowerPC, and SuperH processors, and various 
surrounding hardware components such as framebuffers, busses, interrupt 
controllers, ethernet controllers, disk controllers, and serial port 
controllers.

GXemul, including the dynamic translation system, is implemented in 
portable C, which means that the emulator will run on practically 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 GXemul include:

 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)  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)  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 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#netbsdpmaxinstall

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