/[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 4 - (show annotations)
Mon Oct 8 16:18:00 2007 UTC (12 years, 3 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 <html>
2 <head><title>GXemul documentation: Introduction</title>
3 </head>
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 <!-- The first 10 lines are cut away by the homepage updating script. -->
12
13
14 <!--
15
16 $Id: intro.html,v 1.40 2005/04/27 15:22:17 debug Exp $
17
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 <li><a href="#free">Is GXemul Free software?</a>
54 <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 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
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. 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
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 <h3>Is GXemul Free software?</h3>
113
114 Yes. I have released GXemul under a Free license.
115 (For a definitions of the four freedoms associated with Free software,
116 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 The code in GXemul is Copyrighted software, it is <i>not</i> public
121 domain or anything like that.
122
123 <p>
124 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 <a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
127 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 This should work on most Unix-like systems. If it doesn't, then
156 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 single-step debugger, and then type <b>quit</b>.
181
182 <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
189 <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
197
198
199
200
201
202 <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 A few different machine types are emulated. The following machine types
262 are emulated well enough to run at least one "guest OS":
263
264 <p>
265 <ul>
266 <li><b>DECstation 5000/200</b>&nbsp;&nbsp;("3max")
267 <br>Serial controller (including keyboard and mouse), ethernet,
268 SCSI, and graphical framebuffers.
269 <p>
270 <li><b>Acer Pica-61</b>&nbsp;&nbsp;(an ARC machine)
271 <br>Serial controller, "VGA" text console, and SCSI.
272 <p>
273 <li><b>NEC MobilePro 770, 780, 800, and 880</b>&nbsp;&nbsp;(HPCmips machines)
274 <br>Framebuffer, keyboard, and a PCMCIA IDE controller.
275 <p>
276 <li><b>Cobalt</b>
277 <br>Serial controller and PCI IDE.
278 </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 In addition to emulating real machines, there is also a "test-machine".
288 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 This table lists the guest OSes that run well enough to be considered
318 working in the emulator. They can boot from a harddisk image and be
319 interacted with similar to a real machine.
320
321 <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
335 </tr>
336
337 <tr><td height="10"></td></tr>
338
339 <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
352 <tr><td height="10"></td></tr>
353
354 <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
366 <tr><td height="10"></td></tr>
367
368 <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
381 <tr><td height="10"></td></tr>
382
383 <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
396 </table></center>
397
398
399 <p><br>
400
401 <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
413
414 </body>
415 </html>

  ViewVC Help
Powered by ViewVC 1.1.26