/[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 40 - (show annotations)
Mon Oct 8 16:22:11 2007 UTC (16 years, 5 months ago) by dpavlin
File MIME type: text/html
File size: 14639 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.1539 2007/05/01 04:03:51 debug Exp $
20070415	Landisk PCLOCK should be 33.33 MHz, not 50 MHz. (This makes
		the clock run at correct speed.)
		FINALLY found and fixed the bug which caused OpenBSD/landisk
		to randomly bug out: an &-sign was missing in the special case
		handling of FPSCR in the 'LDS.L @Rm+,FPSCR' instruction.
		Adding similar special case handling for 'LDC.L @Rm+,SR'
		(calling sh_update_sr() instead of just loading).
		Implementing the 'FCNVSD FPUL,DRn' and 'FCNVDS DRm,FPUL'
		SuperH instructions.
		The 'LDC Rm,SR' instruction now immediately breaks out of the
		dyntrans loop if an interrupt is to be triggered.
20070416	In memory_rw.c, if mapping a page as writable, make sure to
		invalidate code translations even if the data access was a
		read.
		Minor SuperH updates.
20070418	Removing the dummy M68K emulation mode.
		Minor SH update (turning unnecessary sts_mach_rn, sts_macl_rn,
		and sts_pr_rn instruction handlers into mov_rm_rn).
20070419	Beginning to add a skeleton for an M88K mode: Adding a hack to
		allow OpenBSD/m88k a.out binaries to be loaded, and disassembly
		of a few simple 88K instructions.
		Commenting out the 'LDC Rm,SR' fix from a few days ago, because
		it made Linux/dreamcast bug out.
		Adding a hack to dev_sh4.c (an extra translation cache
		invalidation), which allows OpenBSD/landisk to boot ok after
		an install. Upgrading the Landisk machine mode to stable,
		updating documentation, etc.
20070420	Experimenting with adding a PCI controller (pcic) to dev_sh4.
		Adding a dummy Realtek 8139C+ skeleton device (dev_rtl8139c).
		Implementing the first M88K instructions (br, or[.u] imm), and
		adding disassembly of some more instructions.
20070421	Continuing a little on dev_rtl8139c.
20070422	Implementing the 9346 EEPROM "read" command for dev_rtl8139c.
		Finally found and fixed an old bug in the log n symbol search
		(it sometimes missed symbols). Debug trace (-i, -t etc) should
		now show more symbols. :-)
20070423	Continuing a little on M88K disassembly.
20070428	Fixing a memset arg order bug in src/net/net.c (thanks to
		Nigel Horne for noticing the bug).
		Applying parts of a patch from Carl van Schaik to clear out
		bottom bits of MIPS addresses more correctly, when using large
		page sizes, and doing some other minor cleanup/refactoring.
		Fixing a couple of warnings given by gcc with the -W option (a
		few more warnings than just plain -Wall).
		Reducing SuperH dyntrans physical address space from 64-bit to
		32-bit (since SH5/SH64 isn't imlemented yet anyway).
		Adding address-to-symbol annotation to a few more instructions
		in the SuperH instruction trace output.
		Beginning regression testing for the next release.
		Reverting the value of SCIF_DELAYED_TX_VALUE from 1 to 2,
		because OpenBSD/landisk may otherwise hang randomly.
20070429	The ugly hack/workaround to get OpenBSD/landisk booting without
		crashing does NOT work anymore (with the April 21 snapshot
		of OpenBSD/landisk). Strangely enough, removing the hack
		completely causes OpenBSD/landisk to work (!).
		More regression testing (re-testing everything SuperH-related,
		and some other things).
		Cobalt interrupts were actually broken; fixing by commenting
		out the DEC21143s in the Cobalt machine.
20070430	More regression testing.
20070501	Updating the OpenBSD/landisk install instructions to use
		4.1 instead of the current snapshot.
		GAAAH! OpenBSD/landisk 4.1 _needs_ the ugly hack/workaround;
		reintroducing it again. (The 4.1 kernel is actually from
		2007-03-11.)
		Simplifying the NetBSD/evbarm install instructions a bit.
		More regression testing.

==============  RELEASE 0.4.5.1  ==============


1 <html><head><title>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;Introduction</title>
2 <meta name="robots" content="noarchive,nofollow,noindex"></head>
3 <body bgcolor="#f8f8f8" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
4 <table border=0 width=100% bgcolor="#d0d0d0"><tr>
5 <td width=100% align=center valign=center><table border=0 width=100%><tr>
6 <td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
7 <b>Gavare's eXperimental Emulator:</b></font><br>
8 <font color="#000000" size="6"><b>Introduction</b>
9 </font></td></tr></table></td></tr></table><p>
10
11 <!--
12
13 $Id: intro.html,v 1.110 2007/04/28 00:12:03 debug Exp $
14
15 Copyright (C) 2003-2007 Anders Gavare. All rights reserved.
16
17 Redistribution and use in source and binary forms, with or without
18 modification, are permitted provided that the following conditions are met:
19
20 1. Redistributions of source code must retain the above copyright
21 notice, this list of conditions and the following disclaimer.
22 2. Redistributions in binary form must reproduce the above copyright
23 notice, this list of conditions and the following disclaimer in the
24 documentation and/or other materials provided with the distribution.
25 3. The name of the author may not be used to endorse or promote products
26 derived from this software without specific prior written permission.
27
28 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
29 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
30 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
31 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
32 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
36 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
37 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
38 SUCH DAMAGE.
39
40 -->
41
42 <a href="./">Back to the index</a>
43
44 <p><br>
45 <h2>Introduction</h2>
46
47 <p>
48 <table border="0" width="99%"><tr><td valign="top" align="left">
49 <ul>
50 <li><a href="#overview">Overview</a>
51 <li><a href="#free">Is GXemul Free software?</a>
52 <li><a href="#build">How to compile/build the emulator</a>
53 <li><a href="#run">How to run the emulator</a>
54 <li><a href="#cpus">Which processor architectures does GXemul emulate?</a>
55 <li><a href="#hosts">Which host architectures are supported?</a>
56 <li><a href="#accuracy">Emulation accuracy</a>
57 <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
58 </ul>
59 </td><td valign="center" align="center">
60 <a href="20050317-example.png"><img src="20050317-example_small.png"></a>
61 <p>NetBSD/pmax 1.6.2 with X11<br>running in GXemul</td></tr></table>
62
63
64
65
66 <p><br>
67 <a name="overview"></a>
68 <h3>Overview:</h3>
69
70 GXemul is an experimental instruction-level machine emulator. Several
71 emulation modes are available. In some modes, processors and surrounding
72 hardware components are emulated well enough to let unmodified operating
73 systems (e.g. NetBSD) run as if they were running on a real machine.
74
75 <p>Devices and processors are not simulated with 100% accuracy. They are
76 only ``faked'' well enough to allow guest operating systems to run without
77 complaining too much. Still, the emulator could be of interest for
78 academic research and experiments, such as when learning how to write
79 operating system code.
80
81 <p>The emulator is written in C, does not depend on third-party libraries,
82 and should compile and run on most 64-bit and 32-bit Unix-like systems.
83
84 <p>The emulator contains code which tries to emulate the workings of CPUs
85 and surrounding hardware found in real machines, but it does not contain
86 any ROM code. You will need some form of program (in binary form) to run
87 in the emulator. For many emulation modes, PROM calls are handled by the
88 emulator itself, so you do not need to use any ROM image at all.
89
90 <p>You can use pre-compiled kernels (for example NetBSD kernels, or
91 Linux), or other programs that are in binary format, and in some cases
92 even actual ROM images. A couple of different file formats are supported
93 (ELF, a.out, ECOFF, SREC, and raw binaries).
94
95 <p>If you do not have a kernel as a separate file, but you have a bootable
96 disk image, then it is sometimes possible to boot directly from that
97 image. (This works for example with DECstation emulation, Dreamcast
98 emulation, or when booting from generic ISO9660 CDROM images if the
99 kernel is included in the image as a plain file.)
100
101 <p>Thanks to (in no specific order) Joachim Buss, Olivier Houchard, Juli
102 Mallett, Juan Romero Pardines, Carl van Schaik, Alec Voropay, Göran
103 Weinholt, Alexander Yurchenko, and everyone else who has provided me with
104 feedback.
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>The code I have written is released under a 3-clause BSD-style license
123 (or "revised BSD-style" if one wants to use <a
124 href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>). Apart from
125 the code I have written, some files are copied from other sources such as
126 NetBSD, for example header files containing symbolic names of bitfields in
127 device registers. They are also covered by similar licenses, but with some
128 additional clauses. The main point, however, is that the licenses require
129 that the original Copyright and license terms are included when you make a
130 copy or modification.
131
132 <p>If you plan to redistribute GXemul <i>without</i> supplying the source
133 code, then you need to comply with each individual source file some other
134 way, for example by writing additional documentation containing copyright
135 notes. I have not done this, since I do not plan on making distributions
136 without source code. You need to check all individual files for details.
137 The "easiest way out" if you plan to redistribute code from GXemul is, of
138 course, to let it remain open source and simply supply the source code.
139
140 <p>In case you want to reuse parts of GXemul, but you need to do that
141 under a different license (e.g. the GPL), then contact me and I might
142 re-license/dual-license files on a case-by-case basis.
143
144
145
146
147
148 <p><br>
149 <a name="build"></a>
150 <h3>How to compile/build the emulator:</h3>
151
152 Uncompress the .tar.gz distribution file, and run
153 <pre>
154 $ <b>./configure</b>
155 $ <b>make</b>
156 </pre>
157
158 <p>This should work on most Unix-like systems. GXemul does not require any
159 specific libraries to build, however, if you build on a system which does
160 not have X11 libraries installed, some functionality will be lost.
161
162 <p>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 an AMD Athlon
165 host, you might want to try setting <tt>CFLAGS</tt> to <tt>-march=athlon</tt>
166 before running <tt>configure</tt>.
167
168
169
170
171
172
173
174 <p><br>
175 <a name="run"></a>
176 <h3>How to run the emulator:</h3>
177
178 Once you have built GXemul, running it should be rather straight-forward.
179 Running <tt><b>gxemul</b></tt> without arguments (or with the
180 <b><tt>-h</tt></b> or <b><tt>-H</tt></b> command line options) will
181 display a help message.
182
183 <p>
184 To get some ideas about what is possible to run in the emulator, please
185 read the section about <a href="guestoses.html">installing "guest"
186 operating systems</a>. If you are interested in using the emulator to
187 develop code on your own, then you should also read the section about
188 <a href="experiments.html#hello">Hello World</a>.
189
190 <p>
191 To exit the emulator, type CTRL-C to enter the
192 single-step debugger, and then type <tt><b>quit</b></tt>.
193
194 <p>
195 If you are starting an emulation by entering settings directly on the
196 command line, and you are not using the <tt><b>-x</b></tt> option, then all
197 terminal input and output will go to the main controlling terminal.
198 CTRL-C is used to break into the debugger, so in order to send CTRL-C to
199 the running (emulated) program, you may use CTRL-B.
200 (This should be a reasonable compromise to allow the emulator to be usable
201 even on systems without X Windows.)
202
203 <p>
204 There is no way to send an actual CTRL-B to the emulated program, when
205 typing in the main controlling terminal window. The solution is to either
206 use <a href="configfiles.html">configuration files</a>, or use
207 <tt><b>-x</b></tt>. Both these solutions cause new xterms to be opened for
208 each emulated serial port that is written to. CTRL-B and CTRL-C both have
209 their original meaning in those xterm windows.
210
211
212
213
214
215 <p><br>
216 <a name="cpus"></a>
217 <h3>Which processor architectures does GXemul emulate?</h3>
218
219 The architectures that are emulated well enough to let at least one
220 guest operating system run (per architecture) are ARM, MIPS, PowerPC,
221 and SuperH.
222
223 <p>Please read the page about <a href="guestoses.html">guest operating
224 systems</a> for more information about the machines and operating systems
225 that can be considered "working" in the emulator.
226
227
228
229
230
231
232 <p><br>
233 <a name="hosts"></a>
234 <h3>Which host architectures are supported?</h3>
235
236 GXemul should compile and run on any modern host architecture (64-bit or
237 32-bit word-length).
238
239 <p>Note: The <a href="translation.html">dynamic translation</a> engine
240 does <i>not</i> require backends for native code generation to be written
241 for each individual host architecture; the intermediate representation
242 that the dyntrans system uses can be executed on any host architecture.
243
244
245
246
247
248 <p><br>
249 <a name="accuracy"></a>
250 <h3>Emulation accuracy:</h3>
251
252 GXemul is an instruction-level emulator; things that would happen in
253 several steps within a real CPU are not taken into account (e.g. pipe-line
254 stalls or out-of-order execution). Still, instruction-level accuracy seems
255 to be enough to be able to run complete guest operating systems inside the
256 emulator.
257
258 <p>The existance of instruction and data caches is "faked" to let
259 operating systems think that they are there, but for all practical
260 purposes, these caches are non-working.
261
262 <p>The emulator is in general <i>not</i> timing-accurate, neither at the
263 instruction level nor on any higher level. An attempt is made to let
264 emulated clocks run at the same speed as the host (i.e. an emulated timer
265 running at 100 Hz will interrupt around 100 times per real second), but
266 since the host speed may vary, e.g. because of other running processes,
267 there is no guarantee as to how many instructions will be executed in
268 each of these 100 Hz cycles.
269
270 <p>If the host is very slow, the emulated clocks might even lag behind
271 the real-world clock.
272
273
274
275
276
277
278 <p><br>
279 <a name="emulmodes"></a>
280 <h3>Which machines does GXemul emulate?</h3>
281
282 A few different machine types are emulated. The following machine types
283 are emulated well enough to run at least one "guest OS":
284
285 <p>
286 <ul>
287 <li><b><u>ARM</u></b>
288 <ul>
289 <li><b>CATS</b> (<a href="guestoses.html#netbsdcatsinstall">NetBSD/cats</a>,
290 <a href="guestoses.html#openbsdcatsinstall">OpenBSD/cats</a>)
291 <li><b>IQ80321</b> (<a href="guestoses.html#netbsdevbarminstall">NetBSD/evbarm</a>)
292 <li><b>NetWinder</b> (<a href="guestoses.html#netbsdnetwinderinstall">NetBSD/netwinder</a>)
293 </ul>
294 <p>
295 <li><b><u>MIPS</u></b>
296 <ul>
297 <li><b>DECstation 5000/200</b> (<a href="guestoses.html#netbsdpmaxinstall">NetBSD/pmax</a>,
298 <a href="guestoses.html#openbsdpmaxinstall">OpenBSD/pmax</a>,
299 <a href="guestoses.html#ultrixinstall">Ultrix</a>,
300 <a href="guestoses.html#declinux">Linux/DECstation</a>,
301 <a href="guestoses.html#sprite">Sprite</a>)
302 <li><b>Acer Pica-61</b> (<a href="guestoses.html#netbsdarcinstall">NetBSD/arc</a>)
303 <li><b>NEC MobilePro 770, 780, 800, 880</b> (<a href="guestoses.html#netbsdhpcmipsinstall">NetBSD/hpcmips</a>)
304 <li><b>Cobalt</b> (<a href="guestoses.html#netbsdcobaltinstall">NetBSD/cobalt</a>)
305 <li><b>Malta</b> (<a href="guestoses.html#netbsdevbmipsinstall">NetBSD/evbmips</a>, Linux/Malta <font color="#0000e0">(<super>*1</super>)</font>)
306 <li><b>Algorithmics P5064</b> (<a href="guestoses.html#netbsdalgorinstall">NetBSD/algor</a>)
307 <li><b>SGI O2 (aka IP32)</b> <font color="#0000e0">(<super>*2</super>)</font>
308 (<a href="guestoses.html#netbsdsgimips">NetBSD/sgi</a>)
309 </ul>
310 <p>
311 <li><b><u>PowerPC</u></b>
312 <ul>
313 <li><b>IBM 6050/6070 (PReP, PowerPC Reference Platform)</b> (<a href="guestoses.html#netbsdprepinstall">NetBSD/prep</a>)
314 <li><b>MacPPC (generic "G4" Macintosh)</b> (<a href="guestoses.html#netbsdmacppcinstall">NetBSD/macppc</a>)
315 </ul>
316 <p>
317 <li><b><u>SuperH</u></b>
318 <ul>
319 <li><b>Sega Dreamcast</b> (<a href="dreamcast.html#netbsd_generic_md">NetBSD/dreamcast</a>, <a href="dreamcast.html#linux_live_cd">Linux/dreamcast</a>)
320 <li><b>Landisk</b> (<a href="guestoses.html#openbsdlandiskinstall">OpenBSD/landisk</a>)
321 </ul>
322 </ul>
323
324 <p>
325 <small><font color="#0000e0">(<super>*1</super>)</font> =
326 Linux/Malta may be run as a guest OS, however I have not yet found any stable
327 URL to pre-compiled Linux/Malta kernels. Thus, Linux/Malta emulation is not
328 tested for every release of the emulator; sometimes it works, sometimes
329 it doesn't.</small>
330
331 <br><small><font color="#0000e0">(<super>*2</super>)</font> =
332 SGI O2 emulation is enough for root-on-nfs, but not for disk boot.</small>
333
334
335 <p>There is code in GXemul for emulation of many other machine types; the
336 degree to which these work range from almost being able to run a complete
337 OS, to almost completely unsupported (perhaps just enough support to
338 output a few boot messages via serial console).
339
340 <p>In addition to emulating real machines, there is also a "test-machine".
341 A test-machine consists of one or more CPUs and a few experimental devices
342 such as:
343
344 <p>
345 <ul>
346 <li>a console I/O device (putchar() and getchar()...)
347 <li>an inter-processor communication device, for SMP experiments
348 <li>a very simple linear framebuffer device (for graphics output)
349 <li>a simple disk controller
350 <li>a simple ethernet controller
351 <li>a real-time clock device
352 </ul>
353
354 <p>This mode is useful if you wish to run experimental code, but do not
355 wish to target any specific real-world machine type, for example for
356 educational purposes.
357
358 <p>You can read more about these experimental devices <a
359 href="experiments.html#expdevices">here</a>.
360
361
362
363
364
365
366 </body>
367 </html>

  ViewVC Help
Powered by ViewVC 1.1.26