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

Diff of /trunk/doc/intro.html

Parent Directory | Revision Log | View Patch Patch

-revision 4 by dpavlin,
Mon Oct  8 16:18:00 2007 UTC
+revision 12 by dpavlin,
Mon Oct  8 16:18:38 2007 UTC
 Line 1
- <html>
+ <html><head><title>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;Introduction</title>
- <head><title>GXemul documentation: Introduction</title>
+ <meta name="robots" content="noarchive,nofollow,noindex"></head>
- </head>
  <body bgcolor="#f8f8f8" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
  <table border=0 width=100% bgcolor="#d0d0d0"><tr>
  <td width=100% align=center valign=center><table border=0 width=100%><tr>
  <td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
- <b>GXemul documentation:</b></font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+ <b>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;</b></font>
  <font color="#000000" size="6"><b>Introduction</b>
  </font></td></tr></table></td></tr></table><p>
- <!-- The first 10 lines are cut away by the homepage updating script.  -->
  <!--
- $Id: intro.html,v 1.40 2005/04/27 15:22:17 debug Exp $
+ $Id: intro.html,v 1.61 2005/08/16 05:15:24 debug Exp $
  Copyright (C) 2003-2005  Anders Gavare.  All rights reserved.
-Line 52 
 SUCH DAMAGE.
+Line 49 
 SUCH DAMAGE.
    <li><a href="#overview">Overview</a>
    <li><a href="#free">Is GXemul Free software?</a>
    <li><a href="#build">How to compile/build the emulator</a>
+   <li><a href="#run">How to run the emulator</a>
    <li><a href="#cpus">Which CPU types does GXemul emulate?</a>
    <li><a href="#accuracy">Emulation accuracy</a>
    <li><a href="#emulmodes">Which machines does GXemul emulate?</a>
-   <li><a href="#guestos">Which guest OSes are possible to run?</a>
+   <li><a href="#guestos">Which guest OSes are possible to run in GXemul?</a>
  </ul>
-Line 66 
 SUCH DAMAGE.
+Line 64 
 SUCH DAMAGE.
  <a name="overview"></a>
  <h3>Overview:</h3>
- GXemul is a machine emulator, which can be used to experiment with
+ GXemul is an experimental instruction-level machine emulator. It can be
- binary code for (among others) MIPS-based machines. Several emulation
+ used to run binary code for MIPS-based machines, regardless of host
- modes are available. For some emulation modes, processors and surrounding
+ platform. Several emulation modes are available. For some modes,
- hardware components are emulated well enough to let unmodified operating
+ processors and surrounding hardware components are emulated well enough to
- systems run as if they were running on a real machine.
+ let unmodified operating systems run as if they were running on a real
+ machine.
- <p>
- It is important to keep in mind that devices and CPUs are not simulated
+ <p>(Non-MIPS emulation modes are also under development, but so far none
- with 100% accuracy. They are only "faked" well enough to make operating
+ of those modes has reached the completeness required to run unmodified
- systems (eg NetBSD) run. Still, the emulator could be of interest for
+ operating systems.)
- academic research and experiments, such as when learning how to write
+ <p>Devices and CPUs are not simulated with 100% accuracy. They are only
+ ``faked'' well enough to make operating systems (e.g. NetBSD) run without
+ complaining too much. Still, the emulator could be of interest for
+ academic research and experiments, such as when learning how to write
  operating system code.
- <p>
+ <p>The emulator is written in C, does not depend on external libraries
- The emulator is written in C, does not depend on external libraries (except
+ (except X11, but that is optional), and should compile and run on most
- X11, but that is optional), and should compile and run on most Unix-like
+ Unix-like systems. If it doesn't, then that is a bug.
- systems. If it doesn't, then that is a bug.
- (You do not need any MIPS compiler toolchain to build or use GXemul.
+ <p>The emulator contains code which tries to emulate the workings of CPUs
- If you need to compile MIPS binaries from sources, then of course you need
+ and surrounding hardware found in real machines, but it does not contain
- such a toolchain, but that is completely separate from GXemul. There
+ any ROM code. You will need some form of program (in binary form) to run
- is a <a href="technical.html#regtest">regression testing</a> framework,
+ in the emulator. For many emulation modes, PROM calls are handled by the
- which requires that a GNU CC for mips64-unknown-elf or similar is available.
- For simply building and using the emulator, it is not required.)
- <p>
- The emulator contains code which tries to emulate the workings of CPUs and
- surrounding hardware found in real machines, but it does not contain any
- ROM code. You will need some form of program (in binary form) to run in
- the emulator. For many emulation modes, PROM calls are handled by the
  emulator itself, so you do not need to use any ROM image at all.
- <p>
+ <p>You can use pre-compiled kernels (for example NetBSD kernels, or
- You can use pre-compiled kernels (for example NetBSD kernels, or Linux),
+ Linux), or other programs that are in binary format, and in some cases
- or other programs that are in binary format, and in some cases even actual
+ even actual ROM images. A couple of different file formats are supported
- ROM images. A couple of different file formats are supported (ELF, a.out,
+ (ELF, a.out, ECOFF, SREC, and raw binaries).
- ECOFF, SREC, raw binaries).
+ <p>If you do not have a kernel as a separate file, but you have a bootable
+ disk image, then it is sometimes possible to boot directly from that
+ image. (This works for example with DECstation emulation, or when booting
+ from ISO9660 CDROM images.)
-Line 111 
 ECOFF, SREC, raw binaries).
+Line 112 
 ECOFF, SREC, raw binaries).
  <a name="free"></a>
  <h3>Is GXemul Free software?</h3>
- Yes. I have released GXemul under a Free license.
+ Yes. I have released GXemul under a Free license. The code in GXemul is
- (For a definitions of the four freedoms associated with Free software,
+ Copyrighted software, it is <i>not</i> public domain. (If this is
- please read <a href="http://www.gnu.org/philosophy/free-sw.html">
+ confusing to you, you might want to read up on the definitions of the
- http://www.gnu.org/philosophy/free-sw.html</a>.)
+ four freedoms associated with Free software, <a
+ href="http://www.gnu.org/philosophy/free-sw.html">http://www.gnu.org/philosophy/free-sw.html</a>.)
+ <p>The code I have written is released under a 3-clause BSD-style license
+ (or "revised BSD-style" if one wants to use <a
+ href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>). Apart from
+ the code I have written, some files are copied from other sources such as
+ NetBSD, for example header files containing symbolic names of bitfields in
+ device registers. They are also covered by similar licenses, but with some
+ additional clauses. The main point, however, is that the licenses require
+ that the original Copyright and license terms are included when you make a
+ copy or modification.
+ <p>If you plan to redistribute GXemul <i>without</i> supplying the source
+ code, then you need to comply with each individual source file some other
+ way, for example by writing additional documentation containing copyright
+ notes. I have not done this, since I do not plan on making distributions
+ without source code. You need to check all individual files for details.
+ The "easiest way out" if you plan to redistribute code from GXemul is, of
+ course, to let it remain open source and simply supply the source code.
+ <p>(If a stable release of GXemul is packaged into binary form, and it is
+ obvious which version of GXemul was used to build the package, then it can
+ be argued that the source code is available, just not in that specific
+ package. Common sense should be used in this case, and not pedanticism.)
- <p>
- The code in GXemul is Copyrighted software, it is <i>not</i> public
- domain or anything like that.
- <p>
- The code I have written is released under a 3-clause BSD-style license
- (or "revised BSD-style" if one wants to use
- <a href="http://www.gnu.org/philosophy/bsd.html">GNU jargon</a>).
- Apart from the code I have written, some files are copied from other sources
- such as NetBSD, for example header files containing symbolic names of
- bitfields in device registers. They are also covered by similar licenses,
- but with some additional clauses. If you plan to redistribute GXemul
- (for example as a binary package), or reuse code from GXemul,
- then you should check those files for their license terms.
- <p>
- (The licenses usually require that the original Copyright and license
- terms are included when you make a copy or modification. The "easiest way
- out" if you plan to redistribute code from GXemul is to simply supply
- the source code. You should however check individual files for details.)
-Line 151 
 Uncompress the .tar.gz distribution file
+Line 157 
 Uncompress the .tar.gz distribution file
          $ <b>make</b>
  </pre>
- <p>
+ <p>This should work on most Unix-like systems. If it doesn't, then
- This should work on most Unix-like systems. If it doesn't, then
  mail me a bug report.
- <p>
+ <p>The emulator's performance is highly dependent on both runtime settings
- (Note for Windows users: there is a possibility that some releases
- and/or snapshots will also work with Cygwin, but I can't promise that.)
- <p>
- The emulator's performance is highly dependent on both runtime settings
  and on compiler settings, so you might want to experiment with different
  CC and CFLAGS environment variable values. For example, on a modern PC,
  you could try the following:
- <p>
+ <p><pre>
- <pre>
+         $ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
-         $ <b>CFLAGS="-mcpu=pentium4 -O3" ./configure</b>
+         $ <b>make</b>
-         $ <b>make</b>
  </pre>
+ <p><br>
+ <a name="run"></a>
+ <h3>How to run the emulator:</h3>
+ Once you have built GXemul, running it should be rather straight-forward.
+ Running <tt><b>gxemul</b></tt> without arguments (or with the
+ <b><tt>-h</tt></b> or <b><tt>-H</tt></b> command line options) will
+ display a help message.
  <p>
- Run <b>./configure --help</b> to get a list of configure options. (The
+ To get some ideas about what is possible to run in the emulator, please
- possible options differ between different releases and snapshots.)
+ read the section about <a href="guestoses.html">installing "guest"
+ operating systems</a>. If you are interested in using the emulator to
+ develop code on your own, then you should also read the section about
+ <a href="experiments.html#hello">Hello World</a>.
  <p>
- Once you have built GXemul, running it should be rather straight-forward.
  To exit the emulator, type CTRL-C to enter the
- single-step debugger, and then type <b>quit</b>.
+ single-step debugger, and then type <tt><b>quit</b></tt>.
  <p>
  If you are starting an emulation by entering settings directly on the
- command line, and you are not using the <b>-x</b> option, then all
+ command line, and you are not using the <tt><b>-x</b></tt> option, then all
  terminal input and output will go to the main controlling terminal.
  CTRL-C is used to break into the debugger, so in order to send CTRL-C to
  the running (emulated) program, you may use CTRL-B.
+ (This should be a reasonable compromise to allow the emulator to be usable
+ even on systems without X Windows.)
  <p>
- (This is an ugly hack; there is no way to send an actual CTRL-B to the
+ There is no way to send an actual CTRL-B to the emulated program, when
- emulated program, when typing in the main controlling terminal window.
+ typing in the main controlling terminal window. The solution is to either
- The solution is to either use configuration files, or use <b>-x</b>. Both
+ use <a href="configfiles.html">configuration files</a>, or use
- these solutions cause new xterms to be opened for each emulated serial
+ <tt><b>-x</b></tt>. Both these solutions cause new xterms to be opened for
- port. CTRL-B and CTRL-C both have their original meaning in those
+ each emulated serial port that is written to. CTRL-B and CTRL-C both have
- xterm windows.)
+ their original meaning in those xterm windows.
-Line 205 
 xterm windows.)
+Line 222 
 xterm windows.)
  <h4>MIPS:</h4>
- Emulation of R4000, which is a 64-bit CPU, was my initial goal. Right
+ Emulation of R4000, which is a 64-bit CPU, was my initial goal.
- now, R2000/R3000-like CPUs are also emulated (32-bit), and emulation of
+ R2000/R3000-like CPUs (32-bit), R1x000, and generic MIPS32/MIPS64-style
- R1x000 (at least the parts that are similar to R4000) is beginning to work
+ CPUs are also emulated, and are hopefully almost as stable as the R4000
- as expected. Code targeted for MIPS32 and MIPS64 also often work.
+ emulation.
- <p>
+ <p>I have written an experimental dynamic binary translation subsystem.
- I have written an experimental dynamic binary translation subsystem.
  This gives higher total performance than interpreting one instruction at a
- time and executing it. (If you wish to enable bintrans, add <b>-b</b> to
+ time and executing it. (If you wish to disable bintrans, add <b>-B</b> to
- the command line, but keep in mind that it is still experimental.)
+ the command line.)
- <h4>URISC:</h4>
- I have implemented an <a href="http://en.wikipedia.org/wiki/URISC">URISC</a>
- emulation mode, just for fun. The only instruction available in an URISC
- machine is "reverse subtract and skip on borrow". (It is probably not
- worth trying to do bintrans with URISC, because any reasonable URISC
- program relies on self-modifying code, which is bad for bintrans
- performance.)
  <h4>Other CPU types:</h4>
- There is some code for 64-bit (and 32-bit) POWER/PowerPC emulation too,
+ Some other CPU architectures can also be partially emulated. These are not
- but it only works for "Hello World" and similarly trivial programs. (There
+ working well enough yet to run guest operating systems.
- are some other CPU modes too, but they are working even less.)
-Line 244 
 are some other CPU modes too, but they a
+Line 247 
 are some other CPU modes too, but they a
  <a name="accuracy"></a>
  <h3>Emulation accuracy:</h3>
- GXemul is an instruction-level simulator; things that would happen in
+ GXemul is an instruction-level emulator; things that would happen in
  several steps within a real CPU are not taken into account (eg. pipe-line
- stages or out-of-order execution). Still, instruction-level accuracy seems
+ stalls or out-of-order execution). Still, instruction-level accuracy seems
  to be enough to be able to run complete guest operating systems inside the
  emulator.
+ <p>Caches are by default not emulated. In some cases, the existance of
+ caches is "faked" to let operating systems think that they are there.
+ (There is some old code for R2000/R3000 caches, but it has probably
+ suffered from bitrot by now.)
+ <p>The emulator is <i>not</i> timing-accurate. It can be run in a
+ "deterministic" mode, <tt><b>-D</b></tt>. The meaning of deterministic is
+ simply that running two emulations with the same settings will result in
+ identical runs. Obviously, this requires that no user interaction is
+ taking place, and that clock speeds are fixed with the <tt><b>-I</b></tt>
+ option. (Deterministic in this case does <i>not</i> mean that the
+ emulation will be identical to some actual real-world machine.)
-Line 275 
 are emulated well enough to run at least
+Line 291 
 are emulated well enough to run at least
    <p>
    <li><b>Cobalt</b>
          <br>Serial controller and PCI IDE.
+   <p>
+   <li><b>Malta (evbmips)</b>
+         <br>Serial controller and PCI IDE.
+   <p>
+   <li><b>SGI O2 ("IP32")</b>
+         <br>Serial controller and ethernet.&nbsp;&nbsp;<small>(Enough for
+         root-on-nfs, but not for disk boot.)</small>
  </ul>
- <p>
+ <p>There is code in GXemul for emulation of many other machine types; the
- There is code in GXemul for emulation of many other machine types;
+ degree to which these work range from almost being able to run a complete
- the degree to which these work range from "almost" being able to run
+ OS, to almost completely unsupported (perhaps just enough support to
- a complete OS, to almost completely unsupported (perhaps just enough
+ output a few boot messages via serial console).
- support to output a few boot messages via serial console).
+ <p>In addition to emulating real machines, there is also a "test-machine".
- <p>
+ A test-machine consists of one or more CPUs and a few experimental devices
- In addition to emulating real machines, there is also a "test-machine".
+ such as:
- A test-machine consists of one or more CPUs and a few experimental
- devices such as:
  <p>
  <ul>
    <li>a console I/O device (putchar() and getchar()...)
    <li>an inter-processor communication device, for SMP experiments
    <li>a very simple linear framebuffer device (for graphics output)
+   <li>a simple SCSI disk controller
+   <li>a simple ethernet controller
  </ul>
- <p>
+ <p>This mode is useful if you wish to run experimental code, but do not
- This mode is useful if you wish to run experimental code, but do not
  wish to target any specific real-world machine type, for example for
  educational purposes.
- <p>
+ <p>You can read more about these experimental devices <a
- You can read more about these experimental devices
+ href="experiments.html#expdevices">here</a>.
- <a href="experiments.html#expdevices">here</a>.
-Line 312 
 You can read more about these experiment
+Line 333 
 You can read more about these experiment
  <p><br>
  <a name="guestos"></a>
- <h3>Which guest OSes are possible to run?</h3>
+ <h3>Which guest OSes are possible to run in GXemul?</h3>
  This table lists the guest OSes that run well enough to be considered
  working in the emulator. They can boot from a harddisk image and be
-Line 322 
 interacted with similar to a real machin
+Line 343 
 interacted with similar to a real machin
  <center><table border="0">
          <tr>
            <td width="10"></td>
-           <td align="center"><a href="netbsd-pmax-20040630.png"><img src="netbsd-pmax-20040630_small.png"></a></td>
+           <td align="center"><a href="20050317-example.png"><img src="20050317-example_small.png"></a></td>
            <td width="15"></td>
            <td><a href="http://www.netbsd.org/Ports/pmax/">NetBSD/pmax</a>
                  <br>DECstation 5000/200</td>
-Line 393 
 interacted with similar to a real machin
+Line 414 
 interacted with similar to a real machin
                  <br>Cobalt</td>
          </tr>
+         <tr><td height="10"></td></tr>
+         <tr>
+           <td></td>
+           <td align="center"><a href="20050626-netbsd-sgimips-netboot.png"><img src="20050626-netbsd-sgimips-netboot_small.png"></a></td>
+           <td></td>
+           <td><a href="http://www.netbsd.org/Ports/sgimips/">NetBSD/sgimips</a>
+                 <br>SGI O2 ("IP32")</td>
+           <td></td>
+           <td align="center"><a href="20050622-netbsd-evbmips-malta.png"><img src="20050622-netbsd-evbmips-malta_small.png"></a></td>
+           <td></td>
+           <td><a href="http://www.netbsd.org/Ports/evbmips/">NetBSD/evbmips</a>
+                 <br>5Kc (and 4Kc) Malta<br>evaluation boards</td>
+           <td></td>
+         </tr>
  </table></center>

 Legend:



Removed from v.4
 


changed lines


 
Added in v.12
 Legend:



Removed from v.4
 


changed lines


 
Added in v.12
-Removed from v.4
+Added in v.12

	ViewVC Help
Powered by ViewVC 1.1.26