/[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

Contents of /trunk/doc/intro.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 8 - (show annotations)
Mon Oct 8 16:18:19 2007 UTC (16 years, 5 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 <html>
2 <head><title>GXemul documentation: Introduction</title>
3 <meta name="robots" content="noarchive,nofollow,noindex">
4 </head>
5 <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
13 <!--
14
15 $Id: intro.html,v 1.47 2005/06/04 22:47:49 debug Exp $
16
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 <li><a href="#free">Is GXemul Free software?</a>
53 <li><a href="#build">How to compile/build the emulator</a>
54 <li><a href="#run">How to run 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 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 operating system code.
81
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 (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.)
89
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 ECOFF, SREC, and raw binaries).
102
103 <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
109
110
111
112
113
114 <p><br>
115 <a name="free"></a>
116 <h3>Is GXemul Free software?</h3>
117
118 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
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 <a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
128 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 This should work on most Unix-like systems. If it doesn't, then
157 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 Run <b><tt>./configure --help</tt></b> to get a list of configure options. (The
176 possible options differ between different releases and snapshots.)
177
178
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 <p>
193 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 To exit the emulator, type CTRL-C to enter the
201 single-step debugger, and then type <tt><b>quit</b></tt>.
202
203 <p>
204 If you are starting an emulation by entering settings directly on the
205 command line, and you are not using the <tt><b>-x</b></tt> option, then all
206 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 (This should be a reasonable compromise to allow the emulator to be usable
210 even on systems without X Windows.)
211
212 <p>
213 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
220
221
222
223
224 <p><br>
225 <a name="cpus"></a>
226 <h3>Which CPU types does GXemul emulate?</h3>
227
228 <h4>MIPS:</h4>
229
230 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
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 <h4>POWER/PowerPC</h4>
253
254 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
258
259 <h4>Other CPU types:</h4>
260
261 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
264
265
266
267
268 <p><br>
269 <a name="accuracy"></a>
270 <h3>Emulation accuracy:</h3>
271
272 GXemul is an instruction-level emulator; things that would happen in
273 several steps within a real CPU are not taken into account (eg. pipe-line
274 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 emulator.
277
278 <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
284 <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
293
294
295
296
297 <p><br>
298 <a name="emulmodes"></a>
299 <h3>Which machines does GXemul emulate?</h3>
300
301 A few different machine types are emulated. The following machine types
302 are emulated well enough to run at least one "guest OS":
303
304 <p>
305 <ul>
306 <li><b>DECstation 5000/200</b>&nbsp;&nbsp;("3max")
307 <br>Serial controller (including keyboard and mouse), ethernet,
308 SCSI, and graphical framebuffers.
309 <p>
310 <li><b>Acer Pica-61</b>&nbsp;&nbsp;(an ARC machine)
311 <br>Serial controller, "VGA" text console, and SCSI.
312 <p>
313 <li><b>NEC MobilePro 770, 780, 800, and 880</b>&nbsp;&nbsp;(HPCmips machines)
314 <br>Framebuffer, keyboard, and a PCMCIA IDE controller.
315 <p>
316 <li><b>Cobalt</b>
317 <br>Serial controller and PCI IDE.
318 </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 In addition to emulating real machines, there is also a "test-machine".
328 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 This table lists the guest OSes that run well enough to be considered
358 working in the emulator. They can boot from a harddisk image and be
359 interacted with similar to a real machine.
360
361 <p>
362 <center><table border="0">
363 <tr>
364 <td width="10"></td>
365 <td align="center"><a href="20050317-example.png"><img src="20050317-example_small.png"></a></td>
366 <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
375 </tr>
376
377 <tr><td height="10"></td></tr>
378
379 <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
392 <tr><td height="10"></td></tr>
393
394 <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
406 <tr><td height="10"></td></tr>
407
408 <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
421 <tr><td height="10"></td></tr>
422
423 <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
436 </table></center>
437
438
439 <p><br>
440
441 <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
453
454 </body>
455 </html>

  ViewVC Help
Powered by ViewVC 1.1.26