/[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

Annotation of /trunk/doc/intro.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 40 - (hide annotations)
Mon Oct 8 16:22:11 2007 UTC (16 years, 6 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 dpavlin 12 <html><head><title>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;Introduction</title>
2     <meta name="robots" content="noarchive,nofollow,noindex"></head>
3 dpavlin 4 <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 dpavlin 22 <b>Gavare's eXperimental Emulator:</b></font><br>
8 dpavlin 4 <font color="#000000" size="6"><b>Introduction</b>
9     </font></td></tr></table></td></tr></table><p>
10 dpavlin 2
11     <!--
12    
13 dpavlin 40 $Id: intro.html,v 1.110 2007/04/28 00:12:03 debug Exp $
14 dpavlin 2
15 dpavlin 34 Copyright (C) 2003-2007 Anders Gavare. All rights reserved.
16 dpavlin 2
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 dpavlin 22 <table border="0" width="99%"><tr><td valign="top" align="left">
49 dpavlin 2 <ul>
50     <li><a href="#overview">Overview</a>
51 dpavlin 4 <li><a href="#free">Is GXemul Free software?</a>
52 dpavlin 2 <li><a href="#build">How to compile/build the emulator</a>
53 dpavlin 6 <li><a href="#run">How to run the emulator</a>
54 dpavlin 22 <li><a href="#cpus">Which processor architectures does GXemul emulate?</a>
55 dpavlin 24 <li><a href="#hosts">Which host architectures are supported?</a>
56 dpavlin 2 <li><a href="#accuracy">Emulation accuracy</a>
57     <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
58     </ul>
59 dpavlin 22 </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 dpavlin 2
63    
64    
65    
66     <p><br>
67     <a name="overview"></a>
68     <h3>Overview:</h3>
69    
70 dpavlin 14 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 dpavlin 2
75 dpavlin 32 <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 dpavlin 12
81 dpavlin 22 <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 dpavlin 2
84 dpavlin 10 <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 dpavlin 2 emulator itself, so you do not need to use any ROM image at all.
89    
90 dpavlin 10 <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 dpavlin 2
95 dpavlin 10 <p>If you do not have a kernel as a separate file, but you have a bootable
96 dpavlin 6 disk image, then it is sometimes possible to boot directly from that
97 dpavlin 34 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 dpavlin 2
101 dpavlin 32 <p>Thanks to (in no specific order) Joachim Buss, Olivier Houchard, Juli
102 dpavlin 40 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 dpavlin 2
106    
107    
108 dpavlin 6
109    
110 dpavlin 10
111    
112 dpavlin 2 <p><br>
113     <a name="free"></a>
114 dpavlin 4 <h3>Is GXemul Free software?</h3>
115 dpavlin 2
116 dpavlin 6 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 dpavlin 2
122 dpavlin 12 <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 dpavlin 2
132 dpavlin 12 <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 dpavlin 2
140 dpavlin 22 <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 dpavlin 2
144    
145    
146    
147 dpavlin 12
148 dpavlin 2 <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 dpavlin 22 <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 dpavlin 2
162 dpavlin 12 <p>The emulator's performance is highly dependent on both runtime settings
163 dpavlin 2 and on compiler settings, so you might want to experiment with different
164 dpavlin 20 CC and CFLAGS environment variable values. For example, on an AMD Athlon
165 dpavlin 24 host, you might want to try setting <tt>CFLAGS</tt> to <tt>-march=athlon</tt>
166     before running <tt>configure</tt>.
167 dpavlin 2
168    
169 dpavlin 6
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 dpavlin 2 <p>
184 dpavlin 6 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 dpavlin 2 To exit the emulator, type CTRL-C to enter the
192 dpavlin 6 single-step debugger, and then type <tt><b>quit</b></tt>.
193 dpavlin 2
194 dpavlin 4 <p>
195     If you are starting an emulation by entering settings directly on the
196 dpavlin 6 command line, and you are not using the <tt><b>-x</b></tt> option, then all
197 dpavlin 4 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 dpavlin 6 (This should be a reasonable compromise to allow the emulator to be usable
201     even on systems without X Windows.)
202 dpavlin 2
203 dpavlin 4 <p>
204 dpavlin 6 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 dpavlin 2
211    
212    
213    
214 dpavlin 4
215 dpavlin 2 <p><br>
216     <a name="cpus"></a>
217 dpavlin 22 <h3>Which processor architectures does GXemul emulate?</h3>
218 dpavlin 2
219 dpavlin 24 The architectures that are emulated well enough to let at least one
220 dpavlin 32 guest operating system run (per architecture) are ARM, MIPS, PowerPC,
221     and SuperH.
222 dpavlin 2
223 dpavlin 34 <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 dpavlin 2
227    
228    
229 dpavlin 14
230 dpavlin 32
231 dpavlin 34
232 dpavlin 24 <p><br>
233     <a name="hosts"></a>
234     <h3>Which host architectures are supported?</h3>
235 dpavlin 2
236 dpavlin 32 GXemul should compile and run on any modern host architecture (64-bit or
237     32-bit word-length).
238 dpavlin 2
239 dpavlin 38 <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 dpavlin 6
244 dpavlin 2
245    
246    
247 dpavlin 32
248 dpavlin 24 <p><br>
249 dpavlin 2 <a name="accuracy"></a>
250     <h3>Emulation accuracy:</h3>
251    
252 dpavlin 6 GXemul is an instruction-level emulator; things that would happen in
253 dpavlin 24 several steps within a real CPU are not taken into account (e.g. pipe-line
254 dpavlin 6 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 dpavlin 2 emulator.
257    
258 dpavlin 24 <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 dpavlin 2
262 dpavlin 32 <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 dpavlin 2
270 dpavlin 32 <p>If the host is very slow, the emulated clocks might even lag behind
271     the real-world clock.
272 dpavlin 2
273    
274 dpavlin 6
275    
276 dpavlin 20
277    
278 dpavlin 2 <p><br>
279     <a name="emulmodes"></a>
280     <h3>Which machines does GXemul emulate?</h3>
281    
282 dpavlin 4 A few different machine types are emulated. The following machine types
283     are emulated well enough to run at least one "guest OS":
284 dpavlin 2
285     <p>
286     <ul>
287 dpavlin 24 <li><b><u>ARM</u></b>
288 dpavlin 14 <ul>
289 dpavlin 28 <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 dpavlin 30 <li><b>NetWinder</b> (<a href="guestoses.html#netbsdnetwinderinstall">NetBSD/netwinder</a>)
293 dpavlin 14 </ul>
294     <p>
295 dpavlin 24 <li><b><u>MIPS</u></b>
296 dpavlin 14 <ul>
297 dpavlin 28 <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 dpavlin 32 <li><b>NEC MobilePro 770, 780, 800, 880</b> (<a href="guestoses.html#netbsdhpcmipsinstall">NetBSD/hpcmips</a>)
304 dpavlin 28 <li><b>Cobalt</b> (<a href="guestoses.html#netbsdcobaltinstall">NetBSD/cobalt</a>)
305 dpavlin 34 <li><b>Malta</b> (<a href="guestoses.html#netbsdevbmipsinstall">NetBSD/evbmips</a>, Linux/Malta <font color="#0000e0">(<super>*1</super>)</font>)
306 dpavlin 30 <li><b>Algorithmics P5064</b> (<a href="guestoses.html#netbsdalgorinstall">NetBSD/algor</a>)
307 dpavlin 34 <li><b>SGI O2 (aka IP32)</b> <font color="#0000e0">(<super>*2</super>)</font>
308 dpavlin 28 (<a href="guestoses.html#netbsdsgimips">NetBSD/sgi</a>)
309 dpavlin 14 </ul>
310 dpavlin 20 <p>
311     <li><b><u>PowerPC</u></b>
312     <ul>
313 dpavlin 28 <li><b>IBM 6050/6070 (PReP, PowerPC Reference Platform)</b> (<a href="guestoses.html#netbsdprepinstall">NetBSD/prep</a>)
314 dpavlin 34 <li><b>MacPPC (generic "G4" Macintosh)</b> (<a href="guestoses.html#netbsdmacppcinstall">NetBSD/macppc</a>)
315 dpavlin 20 </ul>
316 dpavlin 32 <p>
317     <li><b><u>SuperH</u></b>
318     <ul>
319 dpavlin 36 <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 dpavlin 40 <li><b>Landisk</b> (<a href="guestoses.html#openbsdlandiskinstall">OpenBSD/landisk</a>)
321 dpavlin 32 </ul>
322 dpavlin 2 </ul>
323    
324 dpavlin 32 <p>
325     <small><font color="#0000e0">(<super>*1</super>)</font> =
326 dpavlin 34 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 dpavlin 32 <br><small><font color="#0000e0">(<super>*2</super>)</font> =
332 dpavlin 34 SGI O2 emulation is enough for root-on-nfs, but not for disk boot.</small>
333 dpavlin 22
334 dpavlin 34
335 dpavlin 10 <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 dpavlin 2
340 dpavlin 10 <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 dpavlin 2
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 dpavlin 32 <li>a simple disk controller
350 dpavlin 12 <li>a simple ethernet controller
351 dpavlin 32 <li>a real-time clock device
352 dpavlin 2 </ul>
353    
354 dpavlin 10 <p>This mode is useful if you wish to run experimental code, but do not
355 dpavlin 2 wish to target any specific real-world machine type, for example for
356     educational purposes.
357    
358 dpavlin 10 <p>You can read more about these experimental devices <a
359     href="experiments.html#expdevices">here</a>.
360 dpavlin 2
361    
362    
363    
364    
365    
366     </body>
367     </html>

  ViewVC Help
Powered by ViewVC 1.1.26