/[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 8 - (hide annotations)
Mon Oct 8 16:18:19 2007 UTC (13 years, 3 months ago) by dpavlin
File MIME type: text/html
File size: 16275 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.777 2005/06/12 12:31:52 debug Exp $
==============  RELEASE 0.3.3.1  ==============

20050609	Adding simple MIPS IPIs (to dev_mp).
20050611	Adding an ugly hack to track down low-reference bugs
		(define TRACE_NULL_CRASHES, or configure --tracenull).
		Other minor updates.
20050612	Adding a dummy evbmips mode.

==============  RELEASE 0.3.3.2  ==============


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

  ViewVC Help
Powered by ViewVC 1.1.26