/[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 6 - (show annotations)
Mon Oct 8 16:18:11 2007 UTC (13 years, 3 months ago) by dpavlin
File MIME type: text/html
File size: 16293 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.772 2005/06/04 12:02:16 debug Exp $
20050428	Disabling the "-fmove-all-movables" option in the configure
		script, because it causes the compile to fail on OpenBSD/sgi.
20050502	Minor updates.
20050503	Removing the WRT54G mode (it was bogus anyway), and adding a
		comment about Windows NT for MIPS in doc/experiments.html.
		Minor updates to the x86 instruction decoding.
20050504	Adding some more x86 instructions.
		Adding support for reading files from ISO9660 CDROMs (including
		gzipped files). It's an ugly hack, but it seems to work.
		Various other minor updates (dev_vga.c, pc_bios.c etc).
20050505	Some more x86-related updates.
		Beginning (what I hope will be) a major code cleanup phase.
		"bootris" (an x86 bootsector) runs :-)
20050506	Adding some more x86 instructions.
20050507	tmpnam => mkstemp.
		Working on a hack to allow VGA charcells to be shown even when
		not running with X11.
		Adding more x86 instructions.
20050508	x86 32-bit SIB addressing fix, and more instructions.
20050509	Adding more x86 instructions.
20050510	Minor documentation updates, and other updates (x86 stuff etc.)
20050511	More x86-related updates.
20050513	Various updates, mostly x86-related. (Trying to fix flag 
		calculation, factoring out the ugly shift/rotate code, and
		some other things.)
20050514	Adding support for loading some old i386 a.out executables.
		Finally beginning the cleanup of machine/PROM/bios dependant
		info.
		Some minor documentation updates.
		Trying to clean up ARCBIOS stuff a little.
20050515	Trying to make it possible to actually use more than one disk
		type per machine (floppy, ide, scsi).
		Trying to clean up the kbd vs PROM console stuff. (For PC and
		ARC emulation modes, mostly.)
		Beginning to add an 8259 interrupt controller, and connecting
		it to the x86 emulation.
20050516	The first x86 interrupts seem to work (keyboard stuff).
		Adding a 8253/8254 programmable interval timer skeleton.
		FreeDOS now reaches a command prompt and can be interacted
		with.
20050517	After some bugfixes, MS-DOS also (sometimes) reaches a
		command prompt now.
		Trying to fix the pckbc to work with MS-DOS' keyb.com, but no
		success yet.
20050518	Adding a simple 32-bit x86 MMU skeleton.
20050519	Some more work on the x86 stuff. (Beginning the work on paging,
		and various other fixes).
20050520	More updates. Working on dev_vga (4-bit graphics modes), adding
		40 columns support to the PC bios emulation.
		Trying to add support for resizing windows when switching
		between graphics modes.
20050521	Many more x86-related updates.
20050522	Correcting the initial stack pointer's sign-extension for
		ARCBIOS emulation (thanks to Alec Voropay for noticing the
		error).
		Continuing on the cleanup (ARCBIOS etc).
		dev_vga updates.
20050523	More x86 updates: trying to add some support for protected mode
		interrupts (via gate descriptors) and many other fixes.
		More ARCBIOS cleanup.
		Adding a device flag which indicates that reads cause no
		side-effects. (Useful for the "dump" command in the debugger,
		and other things.)
		Adding support for directly starting up x86 ELFs, skipping the
		bootloader stage. (Most ELFs, however, are not suitable for
		this.)
20050524	Adding simple 32-bit x86 TSS task switching, but no privilege
		level support yet.
		More work on dev_vga. A small "Copper bars" demo works. :-)
		Adding support for Trap Flag (single-step exceptions), at least
		in real mode, and various other x86-related fixes.
20050525	Adding a new disk image prefix (gH;S;) which can be used to
		override the default nr of heads and sectors per track.
20050527	Various bug fixes, more work on the x86 mode (stack change on
		interrupts between different priv.levels), and some minor
		documentation updates.
20050528	Various fixes (x86 stuff).
20050529	More x86 fixes. An OpenBSD/i386 bootfloppy reaches userland
		and can be interacted with (although there are problems with
		key repetition). NetBSD/i386 triggers a serious CISC-related
		problem: instruction fetches across page boundaries, where
		the later part isn't actually part of the instruction.
20050530	Various minor updates. (Documentation updates, etc.)
20050531	Adding some experimental code (experiments/new_test_*) which
		could be useful for dynamic (but not binary) translation in
		the future.
20050602	Adding a dummy ARM skeleton.
		Fixing the pckbc key repetition problem (by adding release
		scancodes for all keypresses).
20050603	Minor updates for the next release.
20050604	Release testing. Minor updates.

==============  RELEASE 0.3.3  ==============

20050604	There'll probably be a 0.3.3.1 release soon, with some very
		very tiny updates.


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

  ViewVC Help
Powered by ViewVC 1.1.26