/[gxemul]/trunk/doc/intro.html
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Annotation of /trunk/doc/intro.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4 - (hide annotations)
Mon Oct 8 16:18:00 2007 UTC (12 years, 4 months ago) by dpavlin
File MIME type: text/html
File size: 14670 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.707 2005/04/27 16:37:33 debug Exp $
20050408	Some minor updates to the wdc. Linux now doesn't complain
		anymore if a disk is non-present.
20050409	Various minor fixes (a bintrans bug, and some other things).
		The wdc seems to work with Playstation2 emulation, but there
		is a _long_ annoying delay when disks are detected.
		Fixing a really important bintrans bug (when devices and RAM
		are mixed within 4KB pages), which was triggered with
		NetBSD/playstation2 kernels.
20050410	Adding a dummy dev_ps2_ether (just so that NetBSD doesn't
		complain as much during bootup).
		Symbols starting with '$' are now ignored.
		Renaming dev_ps2_ohci.c to dev_ohci.c, etc.
20050411	Moving the bintrans-cache-isolation check from cpu_mips.c to
		cpu_mips_coproc.c. (I thought this would give a speedup, but
		it's not noticable.)
		Better playstation2 sbus interrupt code.
		Skip ahead many ticks if the count register is read manually.
		(This increases the speed of delay-loops that simply read
		the count register.)
20050412	Updates to the playstation2 timer/interrupt code.
		Some other minor updates.
20050413	NetBSD/cobalt runs from a disk image :-) including userland;
		updating the documentation on how to install NetBSD/cobalt
		using NetBSD/pmax (!).
		Some minor bintrans updates (no real speed improvement) and
		other minor updates (playstation2 now uses the -o options).
20050414	Adding a dummy x86 (and AMD64) mode.
20050415	Adding some (32-bit and 16-bit) x86 instructions.
		Adding some initial support for non-SCSI, non-IDE floppy
		images. (The x86 mode can boot from these, more or less.)
		Moving the devices/ and include/ directories to src/devices/
		and src/include/, respectively.
20050416	Continuing on the x86 stuff. (Adding pc_bios.c and some simple
		support for software interrupts in 16-bit mode.)
20050417	Ripping out most of the x86 instruction decoding stuff, trying
		to rewrite it in a cleaner way.
		Disabling some of the least working CPU families in the
		configure script (sparc, x86, alpha, hppa), so that they are
		not enabled by default.
20050418	Trying to fix the bug which caused problems when turning on
		and off bintrans interactively, by flushing the bintrans cache
		whenever bintrans is manually (re)enabled.
20050419	Adding the 'lswi' ppc instruction.
		Minor updates to the x86 instruction decoding.
20050420	Renaming x86 register name indices from R_xx to X86_R_xx (this
		makes building on Tru64 nicer).
20050422	Adding a check for duplicate MIPS TLB entries on tlbwr/tlbwi.
20050427	Adding screenshots to guestoses.html.
		Some minor fixes and testing for the next release.

==============  RELEASE 0.3.2  ==============


1 dpavlin 2 <html>
2     <head><title>GXemul documentation: Introduction</title>
3     </head>
4 dpavlin 4 <body bgcolor="#f8f8f8" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
5     <table border=0 width=100% bgcolor="#d0d0d0"><tr>
6     <td width=100% align=center valign=center><table border=0 width=100%><tr>
7     <td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
8     <b>GXemul documentation:</b></font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
9     <font color="#000000" size="6"><b>Introduction</b>
10     </font></td></tr></table></td></tr></table><p>
11 dpavlin 2 <!-- The first 10 lines are cut away by the homepage updating script. -->
12    
13    
14     <!--
15    
16 dpavlin 4 $Id: intro.html,v 1.40 2005/04/27 15:22:17 debug Exp $
17 dpavlin 2
18     Copyright (C) 2003-2005 Anders Gavare. All rights reserved.
19    
20     Redistribution and use in source and binary forms, with or without
21     modification, are permitted provided that the following conditions are met:
22    
23     1. Redistributions of source code must retain the above copyright
24     notice, this list of conditions and the following disclaimer.
25     2. Redistributions in binary form must reproduce the above copyright
26     notice, this list of conditions and the following disclaimer in the
27     documentation and/or other materials provided with the distribution.
28     3. The name of the author may not be used to endorse or promote products
29     derived from this software without specific prior written permission.
30    
31     THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
32     ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
33     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
34     ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
35     FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
36     DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
37     OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
38     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
39     LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
40     OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
41     SUCH DAMAGE.
42    
43     -->
44    
45     <a href="./">Back to the index</a>
46    
47     <p><br>
48     <h2>Introduction</h2>
49    
50     <p>
51     <ul>
52     <li><a href="#overview">Overview</a>
53 dpavlin 4 <li><a href="#free">Is GXemul Free software?</a>
54 dpavlin 2 <li><a href="#build">How to compile/build the emulator</a>
55     <li><a href="#cpus">Which CPU types does GXemul emulate?</a>
56     <li><a href="#accuracy">Emulation accuracy</a>
57     <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
58     <li><a href="#guestos">Which guest OSes are possible to run?</a>
59     </ul>
60    
61    
62    
63    
64    
65     <p><br>
66     <a name="overview"></a>
67     <h3>Overview:</h3>
68    
69     GXemul is a machine emulator, which can be used to experiment with
70     binary code for (among others) MIPS-based machines. Several emulation
71     modes are available. For some emulation modes, processors and surrounding
72     hardware components are emulated well enough to let unmodified operating
73     systems run as if they were running on a real machine.
74    
75     <p>
76 dpavlin 4 It is important to keep in mind that devices and CPUs are not simulated
77     with 100% accuracy. They are only "faked" well enough to make operating
78     systems (eg NetBSD) run. Still, the emulator could be of interest for
79     academic research and experiments, such as when learning how to write
80     operating system code.
81 dpavlin 2
82     <p>
83     The emulator is written in C, does not depend on external libraries (except
84     X11, but that is optional), and should compile and run on most Unix-like
85     systems. If it doesn't, then that is a bug.
86 dpavlin 4 (You do not need any MIPS compiler toolchain to build or use GXemul.
87     If you need to compile MIPS binaries from sources, then of course you need
88     such a toolchain, but that is completely separate from GXemul. There
89     is a <a href="technical.html#regtest">regression testing</a> framework,
90     which requires that a GNU CC for mips64-unknown-elf or similar is available.
91     For simply building and using the emulator, it is not required.)
92 dpavlin 2
93     <p>
94     The emulator contains code which tries to emulate the workings of CPUs and
95     surrounding hardware found in real machines, but it does not contain any
96     ROM code. You will need some form of program (in binary form) to run in
97     the emulator. For many emulation modes, PROM calls are handled by the
98     emulator itself, so you do not need to use any ROM image at all.
99    
100     <p>
101     You can use pre-compiled kernels (for example NetBSD kernels, or Linux),
102     or other programs that are in binary format, and in some cases even actual
103     ROM images. A couple of different file formats are supported (ELF, a.out,
104     ECOFF, SREC, raw binaries).
105    
106    
107    
108    
109    
110     <p><br>
111     <a name="free"></a>
112 dpavlin 4 <h3>Is GXemul Free software?</h3>
113 dpavlin 2
114 dpavlin 4 Yes. I have released GXemul under a Free license.
115     (For a definitions of the four freedoms associated with Free software,
116 dpavlin 2 please read <a href="http://www.gnu.org/philosophy/free-sw.html">
117     http://www.gnu.org/philosophy/free-sw.html</a>.)
118    
119     <p>
120 dpavlin 4 The code in GXemul is Copyrighted software, it is <i>not</i> public
121     domain or anything like that.
122    
123     <p>
124 dpavlin 2 The code I have written is released under a 3-clause BSD-style license
125     (or "revised BSD-style" if one wants to use
126 dpavlin 4 <a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
127 dpavlin 2 Apart from the code I have written, some files are copied from other sources
128     such as NetBSD, for example header files containing symbolic names of
129     bitfields in device registers. They are also covered by similar licenses,
130     but with some additional clauses. If you plan to redistribute GXemul
131     (for example as a binary package), or reuse code from GXemul,
132     then you should check those files for their license terms.
133    
134     <p>
135     (The licenses usually require that the original Copyright and license
136     terms are included when you make a copy or modification. The "easiest way
137     out" if you plan to redistribute code from GXemul is to simply supply
138     the source code. You should however check individual files for details.)
139    
140    
141    
142    
143    
144     <p><br>
145     <a name="build"></a>
146     <h3>How to compile/build the emulator:</h3>
147    
148     Uncompress the .tar.gz distribution file, and run
149     <pre>
150     $ <b>./configure</b>
151     $ <b>make</b>
152     </pre>
153    
154     <p>
155 dpavlin 4 This should work on most Unix-like systems. If it doesn't, then
156 dpavlin 2 mail me a bug report.
157    
158     <p>
159     (Note for Windows users: there is a possibility that some releases
160     and/or snapshots will also work with Cygwin, but I can't promise that.)
161    
162     <p>
163     The emulator's performance is highly dependent on both runtime settings
164     and on compiler settings, so you might want to experiment with different
165     CC and CFLAGS environment variable values. For example, on a modern PC,
166     you could try the following:
167     <p>
168     <pre>
169     $ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
170     $ <b>make</b>
171     </pre>
172    
173     <p>
174     Run <b>./configure --help</b> to get a list of configure options. (The
175     possible options differ between different releases and snapshots.)
176    
177     <p>
178     Once you have built GXemul, running it should be rather straight-forward.
179     To exit the emulator, type CTRL-C to enter the
180 dpavlin 4 single-step debugger, and then type <b>quit</b>.
181 dpavlin 2
182 dpavlin 4 <p>
183     If you are starting an emulation by entering settings directly on the
184     command line, and you are not using the <b>-x</b> option, then all
185     terminal input and output will go to the main controlling terminal.
186     CTRL-C is used to break into the debugger, so in order to send CTRL-C to
187     the running (emulated) program, you may use CTRL-B.
188 dpavlin 2
189 dpavlin 4 <p>
190     (This is an ugly hack; there is no way to send an actual CTRL-B to the
191     emulated program, when typing in the main controlling terminal window.
192     The solution is to either use configuration files, or use <b>-x</b>. Both
193     these solutions cause new xterms to be opened for each emulated serial
194     port. CTRL-B and CTRL-C both have their original meaning in those
195     xterm windows.)
196 dpavlin 2
197    
198    
199    
200 dpavlin 4
201    
202 dpavlin 2 <p><br>
203     <a name="cpus"></a>
204     <h3>Which CPU types does GXemul emulate?</h3>
205    
206     <h4>MIPS:</h4>
207    
208     Emulation of R4000, which is a 64-bit CPU, was my initial goal. Right
209     now, R2000/R3000-like CPUs are also emulated (32-bit), and emulation of
210     R1x000 (at least the parts that are similar to R4000) is beginning to work
211     as expected. Code targeted for MIPS32 and MIPS64 also often work.
212    
213     <p>
214     I have written an experimental dynamic binary translation subsystem.
215     This gives higher total performance than interpreting one instruction at a
216     time and executing it. (If you wish to enable bintrans, add <b>-b</b> to
217     the command line, but keep in mind that it is still experimental.)
218    
219    
220    
221     <h4>URISC:</h4>
222    
223     I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
224     emulation mode, just for fun. The only instruction available in an URISC
225     machine is "reverse subtract and skip on borrow". (It is probably not
226     worth trying to do bintrans with URISC, because any reasonable URISC
227     program relies on self-modifying code, which is bad for bintrans
228     performance.)
229    
230    
231    
232    
233     <h4>Other CPU types:</h4>
234    
235     There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation too,
236     but it only works for "Hello World" and similarly trivial programs. (There
237     are some other CPU modes too, but they are working even less.)
238    
239    
240    
241    
242    
243     <p><br>
244     <a name="accuracy"></a>
245     <h3>Emulation accuracy:</h3>
246    
247     GXemul is an instruction-level simulator; things that would happen in
248     several steps within a real CPU are not taken into account (eg. pipe-line
249     stages or out-of-order execution). Still, instruction-level accuracy seems
250     to be enough to be able to run complete guest operating systems inside the
251     emulator.
252    
253    
254    
255    
256    
257     <p><br>
258     <a name="emulmodes"></a>
259     <h3>Which machines does GXemul emulate?</h3>
260    
261 dpavlin 4 A few different machine types are emulated. The following machine types
262     are emulated well enough to run at least one "guest OS":
263 dpavlin 2
264     <p>
265     <ul>
266 dpavlin 4 <li><b>DECstation 5000/200</b>&nbsp;&nbsp;("3max")
267     <br>Serial controller (including keyboard and mouse), ethernet,
268     SCSI, and graphical framebuffers.
269 dpavlin 2 <p>
270     <li><b>Acer Pica-61</b>&nbsp;&nbsp;(an ARC machine)
271 dpavlin 4 <br>Serial controller, "VGA" text console, and SCSI.
272 dpavlin 2 <p>
273     <li><b>NEC MobilePro 770, 780, 800, and 880</b>&nbsp;&nbsp;(HPCmips machines)
274 dpavlin 4 <br>Framebuffer, keyboard, and a PCMCIA IDE controller.
275     <p>
276     <li><b>Cobalt</b>
277     <br>Serial controller and PCI IDE.
278 dpavlin 2 </ul>
279    
280     <p>
281     There is code in GXemul for emulation of many other machine types;
282     the degree to which these work range from "almost" being able to run
283     a complete OS, to almost completely unsupported (perhaps just enough
284     support to output a few boot messages via serial console).
285    
286     <p>
287 dpavlin 4 In addition to emulating real machines, there is also a "test-machine".
288 dpavlin 2 A test-machine consists of one or more CPUs and a few experimental
289     devices such as:
290    
291     <p>
292     <ul>
293     <li>a console I/O device (putchar() and getchar()...)
294     <li>an inter-processor communication device, for SMP experiments
295     <li>a very simple linear framebuffer device (for graphics output)
296     </ul>
297    
298     <p>
299     This mode is useful if you wish to run experimental code, but do not
300     wish to target any specific real-world machine type, for example for
301     educational purposes.
302    
303     <p>
304     You can read more about these experimental devices
305     <a href="experiments.html#expdevices">here</a>.
306    
307    
308    
309    
310    
311    
312    
313     <p><br>
314     <a name="guestos"></a>
315     <h3>Which guest OSes are possible to run?</h3>
316    
317 dpavlin 4 This table lists the guest OSes that run well enough to be considered
318 dpavlin 2 working in the emulator. They can boot from a harddisk image and be
319 dpavlin 4 interacted with similar to a real machine.
320 dpavlin 2
321 dpavlin 4 <p>
322     <center><table border="0">
323     <tr>
324     <td width="10"></td>
325     <td align="center"><a href="netbsd-pmax-20040630.png"><img src="netbsd-pmax-20040630_small.png"></a></td>
326     <td width="15"></td>
327     <td><a href="http://www.netbsd.org/Ports/pmax/">NetBSD/pmax</a>
328     <br>DECstation 5000/200</td>
329     <td width="30"></td>
330     <td align="center"><a href="20041024-netbsd-arc-installed.gif"><img src="20041024-netbsd-arc-installed_small.gif"></a></td>
331     <td width="15"></td>
332     <td><a href="http://www.netbsd.org/Ports/arc/">NetBSD/arc</a>
333     <br>Acer Pica-61</td>
334 dpavlin 2
335 dpavlin 4 </tr>
336 dpavlin 2
337 dpavlin 4 <tr><td height="10"></td></tr>
338 dpavlin 2
339 dpavlin 4 <tr>
340     <td></td>
341     <td align="center"><a href="openbsd-pmax-20040710.png"><img src="openbsd-pmax-20040710_small.png"></a></td>
342     <td></td>
343     <td><a href="http://www.openbsd.org/pmax.html">OpenBSD/pmax</a>
344     <br>DECstation 5000/200</td>
345     <td></td>
346     <td align="center"><a href="20041024-openbsd-arc-installed.gif"><img src="20041024-openbsd-arc-installed_small.gif"></a></td>
347     <td></td>
348     <td><a href="http://www.openbsd.org/arc.html">OpenBSD/arc</a>
349     <br>Acer Pica-61</td>
350     </tr>
351 dpavlin 2
352 dpavlin 4 <tr><td height="10"></td></tr>
353 dpavlin 2
354 dpavlin 4 <tr>
355     <td></td>
356     <td align="center"><a href="ultrix4.5-20040706.png"><img src="ultrix4.5-20040706_small.gif"></a></td>
357     <td></td>
358     <td>Ultrix/RISC<br>DECstation 5000/200</td>
359     <td></td>
360     <td align="center"><a href="20041213-debian_4.png"><img src="20041213-debian_4_small.gif"></a></td>
361     <td></td>
362     <td><a href="http://www.debian.org/">Debian&nbsp;GNU/Linux</a>&nbsp;<super>*</super>
363     <br>DECstation 5000/200</td>
364     </tr>
365 dpavlin 2
366 dpavlin 4 <tr><td height="10"></td></tr>
367 dpavlin 2
368 dpavlin 4 <tr>
369     <td></td>
370     <td align="center"><a href="sprite-20040711.png"><img src="sprite-20040711_small.png"></a></td>
371     <td></td>
372     <td><a href="http://www.cs.berkeley.edu/projects/sprite/retrospective.html">Sprite</a>
373     <br>DECstation 5000/200</td>
374     <td></td>
375     <td align="center"><a href="20041129-redhat_mips.png"><img src="20041129-redhat_mips_small.png"></a></td>
376     <td></td>
377     <td>Redhat&nbsp;Linux&nbsp;<super>*</super>
378     <br>DECstation 5000/200</td>
379     </tr>
380 dpavlin 2
381 dpavlin 4 <tr><td height="10"></td></tr>
382 dpavlin 2
383 dpavlin 4 <tr>
384     <td></td>
385     <td align="center"><a href="20050427-netbsd-hpcmips-2.png"><img src="20050427-netbsd-hpcmips-2_small.png"></a></td>
386     <td></td>
387     <td><a href="http://www.netbsd.org/Ports/hpcmips/">NetBSD/hpcmips</a>
388     <br>NEC MobilePro 770, 780, 800, 880</td>
389     <td></td>
390     <td align="center"><a href="20050413-netbsd-cobalt.png"><img src="20050413-netbsd-cobalt_small.png"></a></td>
391     <td></td>
392     <td><a href="http://www.netbsd.org/Ports/cobalt/">NetBSD/cobalt</a>
393     <br>Cobalt</td>
394     </tr>
395 dpavlin 2
396 dpavlin 4 </table></center>
397 dpavlin 2
398    
399 dpavlin 4 <p><br>
400 dpavlin 2
401 dpavlin 4 <super>*</super> Although Linux runs under DECstation emulation, the
402     default 2.4.27 kernel in Debian GNU/Linux does not support keyboards on
403     the 5000/200 (the specific DECstation model being emulated), so when the
404     login prompt is reached you cannot interact with the system. Kaj-Michael
405     Lang has compiled and made available a newer kernel from the current
406     mips-linux development tree. You can find it here: <a
407     href="http://home.tal.org/~milang/o2/kernels/">http://home.tal.org/~milang/o2/kernels</a>/<a
408     href="http://home.tal.org/~milang/o2/kernels/vmlinux-2.4.29-rc2-r3k-mipsel-decstation">vmlinux-2.4.29-rc2-r3k-mipsel-decstation</a>
409     This newer kernel supports keyboard input, but it does not have Debian's
410     ethernet patches, so you will not be able to use keyboard/framebuffer
411     <i>and</i> networking at the same time.
412 dpavlin 2
413    
414     </body>
415     </html>

  ViewVC Help
Powered by ViewVC 1.1.26