/[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 10 - (show annotations)
Mon Oct 8 16:18:27 2007 UTC (13 years, 3 months ago) by dpavlin
File MIME type: text/html
File size: 16909 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.815 2005/06/27 23:04:35 debug Exp $
20050617	Experimenting some more with netbooting OpenBSD/sgi. Adding
		a hack which allows emulated ethernet networks to be
		distributed across multiple emulator processes.
20050618	Minor updates (documentation, dummy YAMON emulation, etc).
20050620	strcpy/strcat -> strlcpy/strlcat updates.
		Some more progress on evbmips (Malta).
20050621	Adding a section to doc/configfiles.html about ethernet
		emulation across multiple hosts.
		Beginning the work on the ARM translation engine (using the
		dynamic-but-not-binary translation method).
		Fixing a bintrans bug: 0x9fc00000 should always be treated as
		PROM area, just as 0xbfc00000 is.
		Minor progress on Malta emulation (the PCI-ISA bus).
20050622	NetBSD/evbmips can now be installed (using another emulated
		machine) and run (including userland and so on). :-)
		Spliting up the bintrans haddr_entry field into two (one for
		read, one for write). Probably not much of a speed increase,
		though.
		Updating some NetBSD 2.0 -> 2.0.2 in the documentation.
20050623	Minor updates (documentation, the TODO file, etc).
		gzipped kernels are now always automagically gunzipped when
		loaded.
20050624	Adding a dummy Playstation Portable (PSP) mode, just barely
		enough to run Hello World (in weird colors :-).
		Removing the -b command line option; old bintrans is enabled
		by default instead. It makes more sense.
		Trying to finally fix the non-working performance measurement
		thing (instr/second etc).
20050625	Continuing on the essential basics for ARM emulation. Two
		instructions seem to work, a branch and a simple "mov". (The
		mov arguments are not correct yet.) Performance is definitely
		reasonable.
		Various other minor updates.
		Adding the ARM "bl" instruction.
		Adding support for combining multiple ARM instructions into one
		function call. ("mov" + "mov" is the only one implemented so
		far, but it seems to work.)
		Cleaning up some IP32 interrupt things (crime/mace); disabling
		the PS/2 keyboard controller on IP32, so that NetBSD/sgimips
		boots into userland again.
20050626	Finally! NetBSD/sgimips netboots. Adding instructions to
		doc/guestoses.html on how to set up an nfs server etc.
		Various other minor fixes.
		Playstation Portable ".pbp" files can now be used directly.
		(The ELF part of the .pbp is extracted transparently.)
		Converting some sprintf -> snprintf.
		Adding some more instructions to the ARM disassembler.
20050627	More ARM updates. Adding some simple ldr(b), str(b),
		cmps, and conditional branch instructions, enough to run
		a simple Hello World program.
		All ARM instructions are now inlined/generated for all possible
		condition codes.
		Adding add and sub, and more load/store instructions.
		Removing dummy files: cpu_alpha.c, cpu_hppa.c, and cpu_sparc.c.
		Some minor documentation updates; preparing for a 0.3.4
		release. Updating some URLs.

==============  RELEASE 0.3.4  ==============


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.53 2005/06/26 08:42:26 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 in GXemul?</a>
59 </ul>
60
61
62
63
64
65 <p><br>
66 <a name="overview"></a>
67 <h3>Overview:</h3>
68
69 GXemul is an experimental instruction-level machine emulator. It can be
70 used to run binary code for (among others) MIPS-based machines, regardless
71 of host platform. Several emulation modes are available. For some modes,
72 processors and surrounding hardware components are emulated well enough to
73 let unmodified operating systems run as if they were running on a real
74 machine.
75
76 <p>Devices and CPUs are not simulated with 100% accuracy. They are only
77 ``faked'' well enough to make operating systems (e.g. 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>The emulator is written in C, does not depend on external libraries
83 (except X11, but that is optional), and should compile and run on most
84 Unix-like systems. If it doesn't, then that is a bug. (You do not need any
85 MIPS compiler toolchain to build or use GXemul. If you need to compile
86 MIPS binaries from sources, then of course you need such a toolchain, but
87 that is completely separate from GXemul.)
88
89 <p>The emulator contains code which tries to emulate the workings of CPUs
90 and surrounding hardware found in real machines, but it does not contain
91 any ROM code. You will need some form of program (in binary form) to run
92 in the emulator. For many emulation modes, PROM calls are handled by the
93 emulator itself, so you do not need to use any ROM image at all.
94
95 <p>You can use pre-compiled kernels (for example NetBSD kernels, or
96 Linux), or other programs that are in binary format, and in some cases
97 even actual ROM images. A couple of different file formats are supported
98 (ELF, a.out, ECOFF, SREC, and raw binaries).
99
100 <p>If you do not have a kernel as a separate file, but you have a bootable
101 disk image, then it is sometimes possible to boot directly from that
102 image. (This works for example with DECstation emulation, or when booting
103 from ISO9660 CDROM images.)
104
105
106
107
108
109
110
111
112 <p><br>
113 <a name="free"></a>
114 <h3>Is GXemul Free software?</h3>
115
116 Yes. I have released GXemul under a Free license. The code in GXemul is
117 Copyrighted software, it is <i>not</i> public domain. (If this is
118 confusing to you, you might want to read up on the definitions of the
119 four freedoms associated with Free software, <a
120 href="http://www.gnu.org/philosophy/free-sw.html">http://www.gnu.org/philosophy/free-sw.html</a>.)
121
122 <p>
123 The code I have written is released under a 3-clause BSD-style license
124 (or "revised BSD-style" if one wants to use
125 <a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
126 Apart from the code I have written, some files are copied from other sources
127 such as NetBSD, for example header files containing symbolic names of
128 bitfields in device registers. They are also covered by similar licenses,
129 but with some additional clauses. If you plan to redistribute GXemul
130 (for example as a binary package), or reuse code from GXemul,
131 then you should check those files for their license terms.
132
133 <p>
134 (The licenses usually require that the original Copyright and license
135 terms are included when you make a copy or modification. The "easiest way
136 out" if you plan to redistribute code from GXemul is to simply supply
137 the source code. You should however check individual files for details.)
138
139
140
141
142
143 <p><br>
144 <a name="build"></a>
145 <h3>How to compile/build the emulator:</h3>
146
147 Uncompress the .tar.gz distribution file, and run
148 <pre>
149 $ <b>./configure</b>
150 $ <b>make</b>
151 </pre>
152
153 <p>
154 This should work on most Unix-like systems. If it doesn't, then
155 mail me a bug report.
156
157 <p>
158 (Note for Windows users: there is a possibility that some releases
159 and/or snapshots will also work with Cygwin, but I can't promise that.)
160
161 <p>
162 The emulator's performance is highly dependent on both runtime settings
163 and on compiler settings, so you might want to experiment with different
164 CC and CFLAGS environment variable values. For example, on a modern PC,
165 you could try the following:
166 <p>
167 <pre>
168 $ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
169 $ <b>make</b>
170 </pre>
171
172 <p>
173 Run <b><tt>./configure --help</tt></b> to get a list of configure options. (The
174 possible options differ between different releases and snapshots.)
175
176
177
178
179
180
181 <p><br>
182 <a name="run"></a>
183 <h3>How to run the emulator:</h3>
184
185 Once you have built GXemul, running it should be rather straight-forward.
186 Running <tt><b>gxemul</b></tt> without arguments (or with the
187 <b><tt>-h</tt></b> or <b><tt>-H</tt></b> command line options) will
188 display a help message.
189
190 <p>
191 To get some ideas about what is possible to run in the emulator, please
192 read the section about <a href="guestoses.html">installing "guest"
193 operating systems</a>. If you are interested in using the emulator to
194 develop code on your own, then you should also read the section about
195 <a href="experiments.html#hello">Hello World</a>.
196
197 <p>
198 To exit the emulator, type CTRL-C to enter the
199 single-step debugger, and then type <tt><b>quit</b></tt>.
200
201 <p>
202 If you are starting an emulation by entering settings directly on the
203 command line, and you are not using the <tt><b>-x</b></tt> option, then all
204 terminal input and output will go to the main controlling terminal.
205 CTRL-C is used to break into the debugger, so in order to send CTRL-C to
206 the running (emulated) program, you may use CTRL-B.
207 (This should be a reasonable compromise to allow the emulator to be usable
208 even on systems without X Windows.)
209
210 <p>
211 There is no way to send an actual CTRL-B to the emulated program, when
212 typing in the main controlling terminal window. The solution is to either
213 use <a href="configfiles.html">configuration files</a>, or use
214 <tt><b>-x</b></tt>. Both these solutions cause new xterms to be opened for
215 each emulated serial port that is written to. CTRL-B and CTRL-C both have
216 their original meaning in those xterm windows.
217
218
219
220
221
222 <p><br>
223 <a name="cpus"></a>
224 <h3>Which CPU types does GXemul emulate?</h3>
225
226 <h4>MIPS:</h4>
227
228 Emulation of R4000, which is a 64-bit CPU, was my initial goal.
229 R2000/R3000-like CPUs (32-bit), R1x000, and generic MIPS32/MIPS64-style
230 CPUs are also emulated, and are hopefully almost as stable as the R4000
231 emulation.
232
233 <p>
234 I have written an experimental dynamic binary translation subsystem.
235 This gives higher total performance than interpreting one instruction at a
236 time and executing it. (If you wish to enable bintrans, add <b>-b</b> to
237 the command line, but keep in mind that it is still experimental.)
238
239
240 <h4>URISC:</h4>
241
242 I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
243 emulation mode, just for fun. The only instruction available in an URISC
244 machine is "reverse subtract and skip on borrow". (It is probably not
245 worth trying to do bintrans with URISC, because any reasonable URISC
246 program relies on self-modifying code, which is bad for bintrans
247 performance.)
248
249
250 <h4>Other CPU types:</h4>
251
252 Some other CPU architectures can also be partially emulated. These are not
253 working well enough yet to run guest operating systems.
254
255
256
257
258
259
260 <p><br>
261 <a name="accuracy"></a>
262 <h3>Emulation accuracy:</h3>
263
264 GXemul is an instruction-level emulator; things that would happen in
265 several steps within a real CPU are not taken into account (eg. pipe-line
266 stalls or out-of-order execution). Still, instruction-level accuracy seems
267 to be enough to be able to run complete guest operating systems inside the
268 emulator.
269
270 <p>
271 Caches are by default not emulated. In some cases, the existance of caches
272 is "faked" to let operating systems think that they are there. (There is
273 some old code for R2000/R3000 caches, but it has probably suffered from
274 bitrot by now.)
275
276 <p>
277 The emulator is <i>not</i> timing-accurate. It can be run in a
278 "deterministic" mode, <tt><b>-D</b></tt>. The meaning of deterministic is
279 simply that running two emulations with the same settings will result in
280 identical runs. Obviously, this requires that no user interaction is
281 taking place, and that clock speeds are fixed with the <tt><b>-I</b></tt>
282 option. (Deterministic in this case does <i>not</i> mean that the emulation
283 will be identical to some actual real-world machine.)
284
285
286
287
288
289 <p><br>
290 <a name="emulmodes"></a>
291 <h3>Which machines does GXemul emulate?</h3>
292
293 A few different machine types are emulated. The following machine types
294 are emulated well enough to run at least one "guest OS":
295
296 <p>
297 <ul>
298 <li><b>DECstation 5000/200</b>&nbsp;&nbsp;("3max")
299 <br>Serial controller (including keyboard and mouse), ethernet,
300 SCSI, and graphical framebuffers.
301 <p>
302 <li><b>Acer Pica-61</b>&nbsp;&nbsp;(an ARC machine)
303 <br>Serial controller, "VGA" text console, and SCSI.
304 <p>
305 <li><b>NEC MobilePro 770, 780, 800, and 880</b>&nbsp;&nbsp;(HPCmips machines)
306 <br>Framebuffer, keyboard, and a PCMCIA IDE controller.
307 <p>
308 <li><b>Cobalt</b>
309 <br>Serial controller and PCI IDE.
310 <p>
311 <li><b>Malta (evbmips)</b>
312 <br>Serial controller and PCI IDE.
313 <p>
314 <li><b>SGI O2 ("IP32")</b>
315 <br>Serial controller and ethernet.&nbsp;&nbsp;<small>(Enough for
316 root-on-nfs, but not for disk boot.)</small>
317 </ul>
318
319 <p>There is code in GXemul for emulation of many other machine types; the
320 degree to which these work range from almost being able to run a complete
321 OS, to almost completely unsupported (perhaps just enough support to
322 output a few boot messages via serial console).
323
324 <p>In addition to emulating real machines, there is also a "test-machine".
325 A test-machine consists of one or more CPUs and a few experimental devices
326 such as:
327
328 <p>
329 <ul>
330 <li>a console I/O device (putchar() and getchar()...)
331 <li>an inter-processor communication device, for SMP experiments
332 <li>a very simple linear framebuffer device (for graphics output)
333 </ul>
334
335 <p>This mode is useful if you wish to run experimental code, but do not
336 wish to target any specific real-world machine type, for example for
337 educational purposes.
338
339 <p>You can read more about these experimental devices <a
340 href="experiments.html#expdevices">here</a>.
341
342
343
344
345
346
347
348 <p><br>
349 <a name="guestos"></a>
350 <h3>Which guest OSes are possible to run in GXemul?</h3>
351
352 This table lists the guest OSes that run well enough to be considered
353 working in the emulator. They can boot from a harddisk image and be
354 interacted with similar to a real machine.
355
356 <p>
357 <center><table border="0">
358 <tr>
359 <td width="10"></td>
360 <td align="center"><a href="20050317-example.png"><img src="20050317-example_small.png"></a></td>
361 <td width="15"></td>
362 <td><a href="http://www.netbsd.org/Ports/pmax/">NetBSD/pmax</a>
363 <br>DECstation 5000/200</td>
364 <td width="30"></td>
365 <td align="center"><a href="20041024-netbsd-arc-installed.gif"><img src="20041024-netbsd-arc-installed_small.gif"></a></td>
366 <td width="15"></td>
367 <td><a href="http://www.netbsd.org/Ports/arc/">NetBSD/arc</a>
368 <br>Acer Pica-61</td>
369
370 </tr>
371
372 <tr><td height="10"></td></tr>
373
374 <tr>
375 <td></td>
376 <td align="center"><a href="openbsd-pmax-20040710.png"><img src="openbsd-pmax-20040710_small.png"></a></td>
377 <td></td>
378 <td><a href="http://www.openbsd.org/pmax.html">OpenBSD/pmax</a>
379 <br>DECstation 5000/200</td>
380 <td></td>
381 <td align="center"><a href="20041024-openbsd-arc-installed.gif"><img src="20041024-openbsd-arc-installed_small.gif"></a></td>
382 <td></td>
383 <td><a href="http://www.openbsd.org/arc.html">OpenBSD/arc</a>
384 <br>Acer Pica-61</td>
385 </tr>
386
387 <tr><td height="10"></td></tr>
388
389 <tr>
390 <td></td>
391 <td align="center"><a href="ultrix4.5-20040706.png"><img src="ultrix4.5-20040706_small.gif"></a></td>
392 <td></td>
393 <td>Ultrix/RISC<br>DECstation 5000/200</td>
394 <td></td>
395 <td align="center"><a href="20041213-debian_4.png"><img src="20041213-debian_4_small.gif"></a></td>
396 <td></td>
397 <td><a href="http://www.debian.org/">Debian&nbsp;GNU/Linux</a>&nbsp;<super>*</super>
398 <br>DECstation 5000/200</td>
399 </tr>
400
401 <tr><td height="10"></td></tr>
402
403 <tr>
404 <td></td>
405 <td align="center"><a href="sprite-20040711.png"><img src="sprite-20040711_small.png"></a></td>
406 <td></td>
407 <td><a href="http://www.cs.berkeley.edu/projects/sprite/retrospective.html">Sprite</a>
408 <br>DECstation 5000/200</td>
409 <td></td>
410 <td align="center"><a href="20041129-redhat_mips.png"><img src="20041129-redhat_mips_small.png"></a></td>
411 <td></td>
412 <td>Redhat&nbsp;Linux&nbsp;<super>*</super>
413 <br>DECstation 5000/200</td>
414 </tr>
415
416 <tr><td height="10"></td></tr>
417
418 <tr>
419 <td></td>
420 <td align="center"><a href="20050427-netbsd-hpcmips-2.png"><img src="20050427-netbsd-hpcmips-2_small.png"></a></td>
421 <td></td>
422 <td><a href="http://www.netbsd.org/Ports/hpcmips/">NetBSD/hpcmips</a>
423 <br>NEC MobilePro 770, 780, 800, 880</td>
424 <td></td>
425 <td align="center"><a href="20050413-netbsd-cobalt.png"><img src="20050413-netbsd-cobalt_small.png"></a></td>
426 <td></td>
427 <td><a href="http://www.netbsd.org/Ports/cobalt/">NetBSD/cobalt</a>
428 <br>Cobalt</td>
429 </tr>
430
431 <tr><td height="10"></td></tr>
432
433 <tr>
434 <td></td>
435 <td align="center"><a href="20050626-netbsd-sgimips-netboot.png"><img src="20050626-netbsd-sgimips-netboot_small.png"></a></td>
436 <td></td>
437 <td><a href="http://www.netbsd.org/Ports/sgimips/">NetBSD/sgimips</a>
438 <br>SGI O2 ("IP32")</td>
439 <td></td>
440 <td align="center"><a href="20050622-netbsd-evbmips-malta.png"><img src="20050622-netbsd-evbmips-malta_small.png"></a></td>
441 <td></td>
442 <td><a href="http://www.netbsd.org/Ports/evbmips/">NetBSD/evbmips</a>
443 <br>5Kc (and 4Kc) Malta<br>evaluation boards</td>
444 <td></td>
445 </tr>
446
447 </table></center>
448
449
450 <p><br>
451
452 <super>*</super> Although Linux runs under DECstation emulation, the
453 default 2.4.27 kernel in Debian GNU/Linux does not support keyboards on
454 the 5000/200 (the specific DECstation model being emulated), so when the
455 login prompt is reached you cannot interact with the system. Kaj-Michael
456 Lang has compiled and made available a newer kernel from the current
457 mips-linux development tree. You can find it here: <a
458 href="http://home.tal.org/~milang/o2/kernels/">http://home.tal.org/~milang/o2/kernels</a>/<a
459 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>
460 This newer kernel supports keyboard input, but it does not have Debian's
461 ethernet patches, so you will not be able to use keyboard/framebuffer
462 <i>and</i> networking at the same time.
463
464
465 </body>
466 </html>

  ViewVC Help
Powered by ViewVC 1.1.26