/[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 44 - (show annotations)
Mon Oct 8 16:22:56 2007 UTC (13 years, 3 months ago) by dpavlin
File MIME type: text/html
File size: 18438 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.1632 2007/09/11 21:46:35 debug Exp $
20070616	Implementing the MIPS32/64 revision 2 "ror" instruction.
20070617	Adding a struct for each physpage which keeps track of which
		ranges within that page (base offset, length) that are
		continuously translatable. When running with native code
		generation enabled (-b), a range is added after each read-
		ahead loop.
		Experimenting with using the physical program counter sample
		data (implemented 20070608) together with the "translatable
		range" information, to figure out which physical address ranges
		would be worth translating to native code (if the number of
		samples falling within a range is above a certain threshold).
20070618	Adding automagic building of .index comment files for
		src/file/, src/promemul/, src src/useremul/ as well.
		Adding a "has been translated" bit to the ranges, so that only
		not-yet-translated ranges will be sampled.
20070619	Moving src/cpu.c and src/memory_rw.c into src/cpus/,
		src/device.c into src/devices/, and src/machine.c into
		src/machines/.
		Creating a skeleton cc/ld native backend module; beginning on
		the function which will detect cc command line, etc.
20070620	Continuing on the native code generation infrastructure.
20070621	Moving src/x11.c and src/console.c into a new src/console/
		subdir (for everything that is console or framebuffer related).
		Moving src/symbol*.c into a new src/symbol/, which should
		contain anything that is symbol handling related.
20070624	Making the program counter sampling threshold a "settings
		variable" (sampling_threshold), i.e. it can now be changed
		during runtime.
		Switching the RELEASE notes format from plain text to HTML.
		If the TMPDIR environment variable is set, it is used instead
		of "/tmp" for temporary files.
		Continuing on the cc/ld backend: simple .c code is generated,
		the compiler and linker are called, etc.
		Adding detection of host architecture to the configure script
		(again), and adding icache invalidation support (only
		implemented for Alpha hosts so far).
20070625	Simplifying the program counter sampling mechanism.
20070626	Removing the cc/ld native code generation stuff, program
		counter sampling, etc; it would not have worked well in the
		general case.
20070627	Removing everything related to native code generation.
20070629	Removing the (practically unusable) support for multiple
		emulations. (The single emulation allowed now still supports
		multiple simultaneous machines, as before.)
		Beginning on PCCTWO and M88K interrupts.
20070723	Adding a dummy skeleton for emulation of M32R processors.
20070901	Fixing a warning found by "gcc version 4.3.0 20070817
		(experimental)" on amd64.
20070905	Removing some more traces of the old "multiple emulations"
		code.
		Also looking in /usr/local/include and /usr/local/lib for
		X11 libs, when running configure.
20070909	Minor updates to the guest OS install instructions, in
		preparation for the NetBSD 4.0 release.
20070918	More testing of NetBSD 4.0 RC1.

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>GXemul:</b></font>&nbsp;&nbsp;
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.125 2007/06/30 14:02:02 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/platforms 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 a framework for full-system computer architecture emulation.
71 Several processor architectures and machine types have been implemented.
72 It is working well enough to allow <a href="#emulmodes">unmodified
73 "guest" operating systems to run inside the emulator</a>, as if they were
74 running on real hardware.
75
76 <p>The emulator emulates (networks of) real machines. The machines may
77 consist of <a
78 href="http://en.wikipedia.org/wiki/ARM_architecture">ARM</a>, <a
79 href="http://en.wikipedia.org/wiki/MIPS_architecture">MIPS</a>, <a
80 href="http://en.wikipedia.org/wiki/Powerpc">PowerPC</a>, and <a
81 href="http://en.wikipedia.org/wiki/SuperH">SuperH</a> processors, and
82 various surrounding hardware components such as framebuffers, busses,
83 interrupt controllers, ethernet controllers, disk controllers, and serial
84 port controllers.
85
86 <p>GXemul, including the dynamic translation system, is implemented in
87 portable
88 <a href="http://en.wikipedia.org/wiki/C_(programming_language)">C</a>,
89 which means that the emulator will run on practically any 64-bit or 32-bit
90 <a href="http://en.wikipedia.org/wiki/Unix-like">Unix-like</a> systems,
91 with few or no modifications.
92
93 <p>Devices and processors are not simulated with 100% accuracy. They are
94 only "faked" well enough to allow guest operating systems to run without
95 complaining too much. Still, the emulator could be of interest for
96 academic research and experiments, such as when learning how to write
97 operating system code.
98
99 <p>The emulator contains code which tries to emulate the workings of CPUs
100 and surrounding hardware found in real machines, but it does not contain
101 any ROM code. You will need some form of program (in binary form) to run
102 in the emulator. For some emulation modes, PROM calls are handled by the
103 emulator itself, so you do not need to use any ROM image at all.
104
105 <p>You can use pre-compiled kernels (for example <a href="http://www.netbsd.org/">NetBSD</a>
106 kernels, or Linux), or other programs that are in binary format, and in some cases
107 even actual ROM images. A couple of different file formats are supported:
108 <a href="http://en.wikipedia.org/wiki/Executable_and_Linkable_Format">ELF</a>,
109 <a href="http://en.wikipedia.org/wiki/A.out">a.out</a>,
110 <a href="http://en.wikipedia.org/wiki/COFF">COFF</a>/<a href="http://en.wikipedia.org/wiki/ECOFF">ECOFF</a>,
111 <a href="http://en.wikipedia.org/wiki/SREC_%28file_format%29">SREC</a>, and raw binaries.
112
113 <p>If you do not have a kernel as a separate file, but you have a bootable
114 disk image, then it is sometimes possible to boot directly from that
115 image. This works for example with DECstation emulation, <a href="dreamcast.html">Dreamcast
116 emulation</a>, or when booting from generic <a href="http://en.wikipedia.org/wiki/ISO9660">ISO9660</a>
117 CDROM images if the kernel is included in the image as a plain file.
118
119 <p>Thanks to (in no specific order) Joachim Buss, Olivier Houchard, Juli
120 Mallett, Juan Romero Pardines, Carl van Schaik, Miod Vallat, Alec Voropay,
121 Göran Weinholt, Alexander Yurchenko, and everyone else who has provided me
122 with feedback.
123
124
125
126
127
128
129
130 <p><br>
131 <a name="free"></a>
132 <h3>Is GXemul Free software?</h3>
133
134 Yes. I have released GXemul under a Free license. The code in GXemul is
135 Copyrighted software, it is <i>not</i> public domain. (If this is
136 confusing to you, you might want to read up on the definitions of the
137 four freedoms associated with Free software, <a
138 href="http://www.gnu.org/philosophy/free-sw.html">http://www.gnu.org/philosophy/free-sw.html</a>.)
139
140 <p>The code I have written is released under a 3-clause BSD-style license
141 (or "revised BSD-style" if one wants to use <a
142 href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>). Apart from
143 the code I have written, some files are copied from other sources such as
144 NetBSD, for example header files containing symbolic names of bitfields in
145 device registers. They are also covered by similar licenses, but with some
146 additional clauses. The main point, however, is that the licenses require
147 that the original Copyright and license terms are included when you make a
148 copy or modification.
149
150 <p>If you plan to redistribute GXemul <i>without</i> supplying the source
151 code, then you need to comply with each individual source file some other
152 way, for example by writing additional documentation containing copyright
153 notes. I have not done this, since I do not plan on making distributions
154 without source code. You need to check all individual files for details.
155 The "easiest way out" if you plan to redistribute code from GXemul is, of
156 course, to let it remain Free Software and simply include the source code.
157
158 <p>In case you want to reuse parts of GXemul, but you need to do that
159 under a different license (e.g. the
160 <a href="http://www.gnu.org/licenses/gpl.html">GPL</a>), then contact me and
161 I can probably re-license/dual-license files on a case-by-case basis.
162
163
164
165
166
167 <p><br>
168 <a name="build"></a>
169 <h3>How to compile/build the emulator:</h3>
170
171 Uncompress the .tar.gz distribution file, and run
172 <pre>
173 $ <b>./configure</b>
174 $ <b>make</b>
175 </pre>
176
177 <p>This should work on most Unix-like systems. GXemul does not require any
178 specific libraries to build, however, if you build on a system which does
179 not have X11 libraries installed, some functionality will be lost.
180
181 <p>The emulator's performance is highly dependent on both runtime settings
182 and on compiler settings, so you might want to experiment with using
183 different <tt>CC</tt> and <tt>CFLAGS</tt> environment variable values when
184 running the <tt>configure</tt> script.
185
186 <p>On some platforms, it is possible that building GXemul will fail
187 because of too high optimization. When using GCC (the GNU compiler),
188 <tt>-O3</tt> is the default optimization level. This works fine on e.g.
189 amd64 and i386 systems, but on some more uncommon platforms, <tt>-O3</tt>
190 might trigger internal bugs in GCC itself. If this happens, try setting
191 <tt>CFLAGS</tt> to <tt>-O2</tt> before running <tt>./configure</tt>, and
192 try again,
193
194 <p>Note that there is no <tt>make install</tt> functionality; package
195 maintainers for individual operating systems solve this for their
196 corresponding OSes.
197
198
199
200
201
202
203
204 <p><br>
205 <a name="run"></a>
206 <h3>How to run the emulator:</h3>
207
208 Once you have built GXemul, running it should be rather straight-forward.
209 Running <tt><b>gxemul</b></tt> without arguments (or with the
210 <b><tt>-h</tt></b> or <b><tt>-H</tt></b> command line options) will
211 display a help message.
212
213 <p>To get some ideas about what is possible to run in the emulator, please
214 read the section about <a href="guestoses.html">installing "guest"
215 operating systems</a>. The most straight forward guest operating to
216 install is NetBSD/pmax; the instructions provided <a
217 href="guestoses.html#netbsdpmaxinstall">here</a> should let you install
218 NetBSD/pmax in a way very similar to how it is done on a real DECstation.
219
220 <p>If you are interested in using the emulator to develop code on your
221 own, then you should also read the section about <a
222 href="experiments.html#hello">Hello World</a>.
223
224 <p>To exit the emulator, type CTRL-C to enter the
225 single-step debugger, and then type <tt><b>quit</b></tt>.
226
227 <p>If you are starting an emulation by entering settings directly on the
228 command line, and you are not using the <tt><b>-x</b></tt> option, then
229 all terminal input and output will go to the main controlling terminal.
230 CTRL-C is used to break into the debugger, so in order to send CTRL-C to
231 the running (emulated) program, you may use CTRL-B. (This should be a
232 reasonable compromise to allow the emulator to be usable even on systems
233 without X Windows.)
234
235 <p>There is no way to send an actual CTRL-B to the emulated program, when
236 typing in the main controlling terminal window. The solution is to either
237 use <a href="configfiles.html">configuration files</a>, or use
238 <tt><b>-x</b></tt>. Both these solutions cause new xterms to be opened for
239 each emulated serial port that is written to. CTRL-B and CTRL-C both have
240 their original meaning in those xterm windows.
241
242
243
244
245
246 <p><br>
247 <a name="cpus"></a>
248 <h3>Which processor architectures does GXemul emulate?</h3>
249
250 The architectures that are emulated well enough to let at least one
251 guest operating system run (per architecture) are
252 <a href="http://en.wikipedia.org/wiki/ARM_architecture">ARM</a>,
253 <a href="http://en.wikipedia.org/wiki/MIPS_architecture">MIPS</a>,
254 <a href="http://en.wikipedia.org/wiki/Powerpc">PowerPC</a>, and
255 <a href="http://en.wikipedia.org/wiki/SuperH">SuperH</a>.
256
257 <p>Please read the sections about <a href="#emulmodes">emulation
258 modes</a> and <a href="guestoses.html">guest operating
259 systems</a> for more information about the machines and operating systems,
260 respectively, that can be considered "working" in the emulator.
261
262 <p>(There is some code in GXemul for emulation of other architectures, but
263 they are not stable or complete enough to be listed among the "working"
264 architectures.)
265
266
267
268
269
270
271 <p><br>
272 <a name="hosts"></a>
273 <h3>Which host architectures/platforms are supported?</h3>
274
275 GXemul should compile and run on any modern host architecture (64-bit or
276 32-bit word-length). I generally test it on
277 <a href="http://www.freebsd.org/platforms/amd64.html">FreeBSD/amd64</a> 6.x,
278 <a href="http://www.freebsd.org/platforms/alpha.html">FreeBSD/alpha</a> 4.x,
279 sometimes also on Linux (various platforms), and every
280 now and then also on <a href="http://www.netbsd.org/">NetBSD</a> or
281 <a href="http://www.openbsd.org/">OpenBSD</a> inside the emulator itself
282 (various platforms).
283
284 <p>Note 1: The <a href="translation.html">dynamic translation</a> engine
285 does <i>not</i> require backends for native code generation to be written
286 for each individual host architecture; the intermediate representation
287 that the dyntrans system uses can be executed on any host architecture.
288
289 <p>Note 2: Although GXemul may build and run on non-Unix-like platforms,
290 such as <a href="http://www.cygwin.com/">Cygwin</a>, Unix-like systems are
291 the primary platform. Some functionality may be lost when running on Cygwin.
292
293
294
295
296
297
298
299
300 <p><br>
301 <a name="accuracy"></a>
302 <h3>Emulation accuracy:</h3>
303
304 GXemul is an instruction-level emulator; things that would happen in
305 several steps within a real CPU are not taken into account (e.g. pipe-line
306 stalls or out-of-order execution). Still, instruction-level accuracy seems
307 to be enough to be able to run complete guest operating systems inside the
308 emulator.
309
310 <p>The existance of instruction and data caches is "faked" to let
311 operating systems think that they are there, but for all practical
312 purposes, these caches are non-working.
313
314 <p>The emulator is in general <i>not</i> timing-accurate, neither at the
315 instruction level nor on any higher level. An attempt is made to let
316 emulated clocks run at the same speed as the host (i.e. an emulated timer
317 running at 100 Hz will interrupt around 100 times per real second), but
318 since the host speed may vary, e.g. because of other running processes,
319 there is no guarantee as to how many instructions will be executed in
320 each of these 100 Hz cycles.
321
322 <p>If the host is very slow, the emulated clocks might even lag behind
323 the real-world clock.
324
325
326
327
328
329
330 <p><br>
331 <a name="emulmodes"></a>
332 <h3>Which machines does GXemul emulate?</h3>
333
334 A few different machine types are emulated. The following machine types
335 are emulated well enough to run at least one "guest OS":
336
337 <p>
338 <ul>
339 <li><b><u>ARM</u></b>
340 <ul>
341 <li><b>CATS</b> (<a href="guestoses.html#netbsdcatsinstall">NetBSD/cats</a>,
342 <a href="guestoses.html#openbsdcatsinstall">OpenBSD/cats</a>)
343 <li><b>IQ80321</b> (<a href="guestoses.html#netbsdevbarminstall">NetBSD/evbarm</a>)
344 <li><b>NetWinder</b> (<a href="guestoses.html#netbsdnetwinderinstall">NetBSD/netwinder</a>)
345 </ul>
346 <p>
347 <li><b><u>MIPS</u></b>
348 <ul>
349 <li><b>DECstation 5000/200</b> (<a href="guestoses.html#netbsdpmaxinstall">NetBSD/pmax</a>,
350 <a href="guestoses.html#openbsdpmaxinstall">OpenBSD/pmax</a>,
351 <a href="guestoses.html#ultrixinstall">Ultrix</a>,
352 <a href="guestoses.html#declinux">Linux/DECstation</a>,
353 <a href="guestoses.html#sprite">Sprite</a>)
354 <li><b>Acer Pica-61</b> (<a href="guestoses.html#netbsdarcinstall">NetBSD/arc</a>)
355 <li><b>NEC MobilePro 770, 780, 800, 880</b> (<a href="guestoses.html#netbsdhpcmipsinstall">NetBSD/hpcmips</a>)
356 <li><b>Cobalt</b> (<a href="guestoses.html#netbsdcobaltinstall">NetBSD/cobalt</a>)
357 <li><b>Malta</b> (<a href="guestoses.html#netbsdevbmipsinstall">NetBSD/evbmips</a>, Linux/Malta <font color="#0000e0">(<super>*1</super>)</font>)
358 <li><b>Algorithmics P5064</b> (<a href="guestoses.html#netbsdalgorinstall">NetBSD/algor</a>)
359 <li><b>SGI O2 (aka IP32)</b> <font color="#0000e0">(<super>*2</super>)</font>
360 (<a href="guestoses.html#netbsdsgimips">NetBSD/sgi</a>)
361 </ul>
362 <p>
363 <li><b><u>PowerPC</u></b>
364 <ul>
365 <li><b>IBM 6050/6070 (PReP, PowerPC Reference Platform)</b> (<a href="guestoses.html#netbsdprepinstall">NetBSD/prep</a>)
366 <li><b>MacPPC (generic "G4" Macintosh)</b> (<a href="guestoses.html#netbsdmacppcinstall">NetBSD/macppc</a>)
367 <li><b>Artesyn PM/PPC</b> <font color="#0000e0">(<super>*2</super>)</font>
368 (<a href="guestoses.html#netbsdpmppc">NetBSD/pmppc</a>)
369 </ul>
370 <p>
371 <li><b><u>SuperH</u></b>
372 <ul>
373 <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>)
374 <li><b>Landisk I-O DATA USL-5P</b> (<a href="guestoses.html#openbsdlandiskinstall">OpenBSD/landisk</a>)
375 </ul>
376 </ul>
377
378 <p>
379 <small><font color="#0000e0">(<super>*1</super>)</font> =
380 Linux/Malta may be run as a guest OS, however I have not yet found any stable
381 URL to pre-compiled Linux/Malta kernels. Thus, Linux/Malta emulation is not
382 tested for every release of the emulator; sometimes it works, sometimes
383 it doesn't.</small>
384
385 <br><small><font color="#0000e0">(<super>*2</super>)</font> =
386 The emulation is enough for root-on-nfs, but no disk controller (SCSI nor
387 IDE) is emulated yet for this machine type.</small>
388
389 <p>Note that of all of the machines above, none of them is emulated to
390 100%. The most complete emulation mode is probably the DECstation
391 5000/200. Things that will most likely <b>not</b> work include running
392 raw PROM images for most machines, SGI IRIX, MacOS X or Darwin, Windows
393 NT, or Dreamcast games.
394
395 <p>There is code in GXemul for emulation of several other machine types; the
396 degree to which these work range from almost being able to run a complete
397 OS, to almost completely unsupported, perhaps just enough support to
398 output a few boot messages via serial console. (See the end of
399 <a href="guestoses.html#generalnotes">this section</a> on the Guest OSes
400 page for some examples, but remember that these do not necessarily work.)
401
402 <p>In addition to emulating real machines, there is also a "test-machine".
403 A test-machine consists of one or more CPUs and a few experimental devices
404 such as:
405
406 <p>
407 <ul>
408 <li>a console I/O device (putchar() and getchar()...)
409 <li>an inter-processor communication device, for SMP experiments
410 <li>a very simple linear framebuffer device (for graphics output)
411 <li>a simple disk controller
412 <li>a simple ethernet controller
413 <li>a simple interrupt controller
414 <li>a real-time clock device
415 </ul>
416
417 <p>This mode is useful if you wish to run experimental code, but do not
418 wish to target any specific real-world machine type, for example for
419 educational purposes.
420
421 <p>You can read more about these experimental devices <a
422 href="experiments.html#expdevices">here</a>.
423
424
425
426
427
428
429 </body>
430 </html>

  ViewVC Help
Powered by ViewVC 1.1.26