/[gxemul]/trunk/doc/technical.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/technical.html

Parent Directory | Revision Log | View Patch Patch

-revision 2 by dpavlin,
Mon Oct  8 16:17:48 2007 UTC
+revision 42 by dpavlin,
Mon Oct  8 16:22:32 2007 UTC
 Line 1
- <html>
+ <html><head><title>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;Technical details</title>
- <head><title>GXemul documentation: Technical details</title>
+ <meta name="robots" content="noarchive,nofollow,noindex"></head>
- </head>
+ <body bgcolor="#f8f8f8" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
- <body bgcolor="#ffffff" text="#000000" link="#4040f0" vlink="#404040" alink="#ff0000">
+ <table border=0 width=100% bgcolor="#d0d0d0"><tr>
- <p>
+ <td width=100% align=center valign=center><table border=0 width=100%><tr>
- <table width=100%>
+ <td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
-   <tr><td width=100% bgcolor=#808070><font color=#ffffe0 size=6>
+ <b>Gavare's eXperimental Emulator:</b></font><br>
-   <b>GXemul documentation: Technical details</b></font></td></tr>
+ <font color="#000000" size="6"><b>Technical details</b>
- </table>
+ </font></td></tr></table></td></tr></table><p>
- <p>
- <!-- The first 10 lines are cut away by the homepage updating script.  -->
  <!--
- $Id: technical.html,v 1.47 2005/04/07 15:50:38 debug Exp $
+ $Id: technical.html,v 1.76 2007/06/15 18:07:08 debug Exp $
- Copyright (C) 2004-2005  Anders Gavare.  All rights reserved.
+ Copyright (C) 2004-2007  Anders Gavare.  All rights reserved.
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are met:
-Line 43 
 SUCH DAMAGE.
+Line 40 
 SUCH DAMAGE.
  -->
  <a href="./">Back to the index</a>
  <p><br>
  <h2>Technical details</h2>
- <p>
+ <p>This page describes some of the internals of GXemul.
- This page describes some of the internals of GXemul.
  <p>
  <ul>
-   <li><a href="#overview">Overview</a>
+   <li><a href="#speed">Speed and emulation modes</a>
-   <li><a href="#speed">Speed</a>
    <li><a href="#net">Networking</a>
    <li><a href="#devices">Emulation of hardware devices</a>
-   <li><a href="#regtest">Regression tests</a>
  </ul>
- <p><br>
- <a name="overview"></a>
- <h3>Overview</h3>
- In simple terms, GXemul is just a simple fetch-and-execute
- loop; an instruction is fetched from memory, and executed.
- <p>
- In reality, a lot of things need to be handled. Before each instruction is
- executed, the emulator checks to see if any interrupts are asserted which
- are not masked away. If so, then an INT exception is generated. Exceptions
- cause the program counter to be set to a specific value, and some of the
- system coprocessor's registers to be set to values signifying what kind of
- exception it was (an interrupt exception in this case).
- <p>
- Reading instructions from memory is done through a TLB, a translation
- lookaside buffer. The TLB on MIPS is software controlled, which means that
- the program running inside the emulator (for example an operating system
- kernel) has to take care of manually updating the TLB. Some memory
- addresses are translated into physical addresses directly, some are
- translated into valid physical addresses via the TLB, and some memory
- references are not valid. Invalid memory references cause exceptions.
- <p>
- After an instruction has been read from memory, the emulator checks which
- opcode it contains and executes the instruction. Executing an instruction
- usually involves reading some register and writing some register, or perhaps a
- load from memory (or a store to memory). The program counter is increased
- for every instruction.
- <p>
- Some memory references point to physical addresses which are not in the
- normal RAM address space. They may point to hardware devices. If that is
- the case, then loads and stores are converted into calls to a device
- access function. The device access function is then responsible for
- handling these reads and writes.  For example, a graphical framebuffer
- device may put a pixel on the screen when a value is written to it, or a
- serial controller device may output a character to stdout when written to.
  <p><br>
  <a name="speed"></a>
- <h3>Speed</h3>
+ <h3>Speed and emulation modes</h3>
- There are two modes in which the emulator can run, <b>a</b>) a straight forward
+ So, how fast is GXemul? There is no short answer to this. There is
- loop which fetches one instruction from emulated RAM and executes it
+ especially no answer to the question <b>What is the slowdown factor?</b>,
- (described in the previous section), and <b>b</b>)
+ because the host architecture and emulated architecture can usually not be
- using dynamic binary translation.
+ compared just like that.
+ <p>Performance depends on several factors, including (but not limited to)
+ host architecture, target architecture, host clock speed, which compiler
+ and compiler flags were used to build the emulator, what the workload is,
+ what additional runtime flags are given to the emulator, and so on.
+ <p>Devices are generally not timing-accurate: for example, if an emulated
+ operating system tries to read a block from disk, from its point of view
+ the read was instantaneous (no waiting). So 1 MIPS in an emulated OS might
+ have taken more than one million instructions on a real machine.
+ <p>Also, if the emulator says it has executed 1 million instructions, and
+ the CPU family in question was capable of scalar execution (i.e. one cycle
+ per instruction), it might still have taken more than 1 million cycles on
+ a real machine because of cache misses and similar micro-architectural
+ penalties that are not simulated by GXemul.
+ <p>Because of these issues, it is in my opinion best to measure
+ performance as the actual (real-world) time it takes to perform a task
+ with the emulator, e.g.:
- <p>
+ <ul>
- Mode <b>a</b> is very slow. On a 2.8 GHz Intel Xeon host the resulting
+   <li>"How long does it take to install NetBSD onto a disk image?"
- emulated machine is rougly equal to a 7 MHz R3000 (or a 3.5 MHz R4000).
+   <li>"How long does it take to compile XYZ inside NetBSD
- The actual performance varies a lot, maybe between 5 and 10 million
+         in the emulator?".
- instructions per second, depending on workload.
+ </ul>
- <p>
- Mode <b>b</b> ("bintrans") is still to be considered experimental, but
- gives higher performance than mode <b>a</b>. It translates MIPS machine
- code into machine code that can be executed on the host machine
- on-the-fly. The translation itself obviously takes some time, but this is
- usually made up for by the fact that the translated code chunks are
- executed multiple times.
- To run the emulator with binary translation enabled, just add <b>-b</b>
- to the command line.
- <p>
+ <p>So, how fast is it? :-)&nbsp;&nbsp;&nbsp;Answer: it varies.
- Only small pieces of MIPS machine code are translated, usually the size of
- a function, or less. There is no "intermediate representation" code, so
- all translations are done directly from MIPS to host machine code.
- <p>
- The default bintrans cache size is 16 MB, but you can change this by adding
- -DDEFAULT_BINTRANS_SIZE_IN_MB=<i>xx</i> to your CFLAGS environment variable
- before running the configure script, or by using the bintrans_size()
- configuration file option when running the emulator.
- <p>
- By default, an emulated OS running under DECstation emulation which listens to
- interrupts from the mc146818 clock will get interrupts that are close to the
- host's clock. That is, if the emulated OS says it wants 100 interrupts per
- second, it will get approximately 100 interrupts per real second.
- <p>
- There is however a -I option, which sets the number of emulated cycles per
- seconds to a fixed value. Let's say you wish to make the emulated OS think it
- is running on a 40 MHz DECstation, and not a 7 MHz one, then you can add
- -I 40000000 to the command line. This will not make the emulation faster, of
- course. It might even make it seem slower; for example, if NetBSD/pmax waits
-seconds for SCSI devices to settle during bootup, those 2 seconds will take
-*40000000 cycles (which will take more time than 2*7000000).
- <p>
- The -I option is also necessary if you want to run deterministic experiments,
- if a mc146818 device is present.
- <p>
- Some emulators make claims such as "x times slowdown," but in the case of
- GXemul, the host is often not a MIPS-based machine, and hence comparing
- one MIPS instruction to a host instruction doesn't work. Performance depends on
- a lot of factors, including (but not limited to) host architecture, host speed,
- which compiler and compiler flags were used to build GXemul, what the
- workload is, and so on. For example, if an emulated operating system tries
- to read a block from disk, from its point of view the read was instantaneous
- (no waiting). So 1 MIPS in an emulated OS might have taken more than one
- million instructions on a real machine.  Because of this, imho it is best
- to measure performance as the actual (real-world) time it takes to perform
- a task with the emulator.
-Line 181 
 a task with the emulator.
+Line 107 
 a task with the emulator.
  <a name="net"></a>
  <h3>Networking</h3>
- Running an entire operating system under emulation is very interesting in
+ <font color="#ff0000">NOTE/TODO: This section is very old.</font>
- itself, but for several reasons, running a modern OS without access to
- TCP/IP networking is a bit akward. Hence, I feel the need to implement TCP/IP
+ <p>Running an entire operating system under emulation is very interesting
- (networking) support in the emulator.
+ in itself, but for several reasons, running a modern OS without access to
+ TCP/IP networking is a bit akward. Hence, I feel the need to implement
+ TCP/IP (networking) support in the emulator.
  <p>
  As far as I have understood it, there seems to be two different ways to go:
-Line 205 
 As far as I have understood it, there se
+Line 133 
 As far as I have understood it, there se
                  connect from the emulated OS to the OS running on the
                  host, as packets sent out on the host's NIC are not
                  received by itself. (?)
+           <li>All specific networking protocols will be handled by the
+                 physical network.
          </ul>
    <p>
    or
-Line 233 
 As far as I have understood it, there se
+Line 163 
 As far as I have understood it, there se
          </ul>
  </ol>
- Other emulators that I have heard of seem to use the first one, if they
+ <p>
- support networking.
+ Some emulators/simulators use the first approach, while others use the
+ second. I think that SIMH and QEMU are examples of emulators using the
+ first and second approach, respectively.
  <p>
  Since I have choosen the second kind of implementation, I have to write
-Line 249 
 emulation (-E dec -e 3max):
+Line 181 
 emulation (-E dec -e 3max):
          and converted to ARP responses. (This is used by the emulated OS
          to find out the MAC address of the gateway.)
    <li>ICMP echo requests (that is the kind of packet produced by the
-         <b>ping</b> program) are interpreted and converted to ICMP echo
+         <b><tt>ping</tt></b> program) are interpreted and converted to ICMP echo
          replies, <i>regardless of the IP address</i>. This means that
          running ping from within the emulated OS will <i>always</i>
          receive a response. The ping packets never leave the emulated
-Line 263 
 emulation (-E dec -e 3max):
+Line 195 
 emulation (-E dec -e 3max):
          packets are handled (but more state is kept for each connection).
          <font color="#ff0000">NOTE: Much of the TCP handling code is very
          ugly and hardcoded.</font>
+ <!--
    <li>RARP is not implemented yet. (I haven't needed it so far.)
+ -->
  </ul>
+ <p>
  The gateway machine, which is the only "other" machine that the emulated
  OS sees on its emulated network, works as a NAT-style firewall/gateway. It
- has a fixed IPv4 address of 10.0.0.254. An OS running in the emulator
+ usually has a fixed IPv4 address of <tt>10.0.0.254</tt>. An OS running in
- can thus have any 10.x.x.x address; a typical choice would be 10.0.0.1.
+ the emulator would usually have an address of the form <tt>10.x.x.x</tt>;
+ a typical choice would be <tt>10.0.0.1</tt>.
  <p>
- Inside emulated NetBSD or OpenBSD, running the following commands should
+ Inside emulated NetBSD/pmax or OpenBSD/pmax, running the following
- configure the emulated NIC:
+ commands should configure the emulated NIC:
  <pre>
          # <b>ifconfig le0 10.0.0.1</b>
          # <b>route add default 10.0.0.254</b>
          add net default: gateway 10.0.0.254
  </pre>
+ <p>
  If you want nameserver lookups to work, you need a valid /etc/resolv.conf
  as well:
  <pre>
          # <b>echo nameserver 129.16.1.3 > /etc/resolv.conf</b>
  </pre>
- (But replace 129.16.1.3 with the actual real-world IP address of your
+ (But replace <tt>129.16.1.3</tt> with the actual real-world IP address of
- nearest nameserver.)
+ your nearest nameserver.)
  <p>
  Now, host lookups should work:
  <pre>
-Line 309 
 Now, host lookups should work:
+Line 247 
 Now, host lookups should work:
          uucp-gw-2.pa.dec.com    172799 IN       A       204.123.2.19
  </pre>
- To transfer files via UDP, you can use the tftp program.
+ <p>
+ At this point, UDP and TCP should (mostly) work.
- <pre>
-         # <b>tftp 12.34.56.78</b>
-         tftp> <b>get filename</b>
-         Received XXXXXX bytes in X.X seconds
-         tftp> <b>quit</b>
-         #
- </pre>
- or, to do it non-interactively (with ugly output):
- <pre>
-         # <b>echo get filename | tftp 12.34.56.78</b>
-         tftp> Received XXXXXX bytes in X.X seconds
-         tftp> #
- </pre>
- This, of course, requires that you have put the file <i>filename</i> in
+ <p>
- the root directory of the tftp server (12.34.56.78).
+ Here is an example of how to configure a server machine and an emulated
+ client machine for sharing files via NFS:
  <p>
- It is also possible to run NFS via UDP. This is very useful if you want to
+ (This is very useful if you want to share entire directory trees
- share entire directory trees between the emulated environment and another
+ between the emulated environment and another machine. These instruction
- machine. These instruction will work for FreeBSD, if you are running
+ will work for FreeBSD, if you are running something else, use your
- something else, use your imagination to modify them:
+ imagination to modify them.)
+ <p>
  <ul>
    <li>On the server, add a line to your /etc/exports file, exporting
          the files you wish to use in the emulator:<pre>
-Line 374 
 a CDROM ISO image. You can use a read-wr
+Line 299 
 a CDROM ISO image. You can use a read-wr
  files in both directions, but then you should be aware of the
  fragmentation issue mentioned above.
- <p>
- TCP is implemented to some extent, but should not be considered to be
- stable yet. It is enough to let NetBSD/pmax and OpenBSD/pmax install via
- ftp, though.
-Line 386 
 ftp, though.
+Line 309 
 ftp, though.
  <a name="devices"></a>
  <h3>Emulation of hardware devices</h3>
- Each file in the device/ directory is responsible for one hardware device.
+ Each file called <tt>dev_*.c</tt> in the
- These are used from src/machine.c, when initializing which hardware a
+ <a href="../src/devices/"><tt>src/devices/</tt></a> directory is
- particular machine model will be using, or when adding devices to a
+ responsible for one hardware device. These are used from
- machine using the <b>device()</b> command in configuration files.
+ <a href="../src/machines/"><tt>src/machines</tt></a><tt>/machine_*.c</tt>,
+ when initializing which hardware a particular machine model will be using,
- <p>
+ or when adding devices to a machine using the <tt>device()</tt> command in
- <font color="#ff0000">NOTE: 2005-02-26: I'm currently rewriting the
+ <a href="configfiles.html">configuration files</a>.
- device registry subsystem.</font>
- <p>
+ <p>(I'll be using the name "<tt>foo</tt>" as the name of the device in all
- (I'll be using the name 'foo' as the name of the device in all these
+ these examples.  This is pseudo code, it might need some modification to
- examples.  This is pseudo code, it might need some modification to
  actually compile and run.)
- <p>
+ <p>Each device should have the following:
- Each device should have the following:
  <p>
  <ul>
-   <li>A devinit function in dev_foo.c. It would typically look
+   <li>A <tt>devinit</tt> function in <tt>src/devices/dev_foo.c</tt>. It
-         something like this:
+         would typically look something like this:
  <pre>
-         /*
+         DEVINIT(foo)
-          *  devinit_foo():
-          */
-         int devinit_foo(struct devinit *devinit)
          {
-                 struct foo_data *d = malloc(sizeof(struct foo_data));
+                 struct foo_data *d;
-                 if (d == NULL) {
+                 CHECK_ALLOCATION(d = malloc(sizeof(struct foo_data)));
-                         fprintf(stderr, "out of memory\n");
+                 memset(d, 0, sizeof(struct foo_data));
-                         exit(1);
-                 }
-                 memset(d, 0, sizeof(struct foon_data));
                  /*
                   *  Set up stuff here, for example fill d with useful
-                  *  data. devinit contains settings like address, irq_nr,
+                  *  data. devinit contains settings like address, irq path,
                   *  and other things.
                   *
                   *  ...
                   */
+                 INTERRUPT_CONNECT(devinit->interrupt_path, d->irq);
                  memory_device_register(devinit->machine->memory, devinit->name,
                      devinit->addr, DEV_FOO_LENGTH,
-                     dev_foo_access, (void *)d, MEM_DEFAULT, NULL);
+                     dev_foo_access, (void *)d, DM_DEFAULT, NULL);
                  /*  This should only be here if the device
                      has a tick function:  */
-Line 443 
 Each device should have the following:
+Line 359 
 Each device should have the following:
          }
  </pre><br>
-   <li>At the top of dev_foo.c, the foo_data struct should be defined.
+         <p><tt>DEVINIT(foo)</tt> is defined as <tt>int devinit_foo(struct devinit *devinit)</tt>,
+         and the <tt>devinit</tt> argument contains everything that the device driver's
+         initialization function needs.
+   <p>
+   <li>At the top of <tt>dev_foo.c</tt>, the <tt>foo_data</tt> struct
+         should be defined.
  <pre>
          struct foo_data {
-                 int     irq_nr;
+                 struct interrupt        irq;
                  /*  ...  */
          }
  </pre><br>
+         (There is an exception to this rule; some legacy code and other
-   <li>If foo has a tick function (that is, something that needs to be
+         ugly hacks have their device structs defined in
-         run at regular intervals) then FOO_TICKSHIFT and a tick function
+         <tt>src/include/devices.h</tt> instead of <tt>dev_foo.c</tt>.
-         need to be defined as well:
+         New code should not add stuff to <tt>devices.h</tt>.)
+   <p>
+   <li>If <tt>foo</tt> has a tick function (that is, something that needs to be
+         run at regular intervals) then <tt>FOO_TICKSHIFT</tt> and a tick
+         function need to be defined as well:
  <pre>
-         #define FOO_TICKSHIFT           10
+         #define FOO_TICKSHIFT           14
-         void dev_foo_tick(struct cpu *cpu, void *extra)
+         DEVICE_TICK(foo)
          {
-                 struct foo_data *d = (struct foo_data *) extra;
+                 struct foo_data *d = extra;
                  if (.....)
-                         cpu_interrupt(cpu, d->irq_nr);
+                         INTERRUPT_ASSERT(d->irq);
                  else
-                         cpu_interrupt_ack(cpu, d->irq_nr);
+                         INTERRUPT_DEASSERT(d->irq);
          }
  </pre><br>
+   <li>Does this device belong to a standard bus?
+         <ul>
+           <li>If this device should be detectable as a PCI device, then
+                 glue code should be added to
+                 <tt>src/devices/bus_pci.c</tt>.
+           <li>If this is a legacy ISA device which should be usable by
+                 any machine which has an ISA bus, then the device should
+                 be added to <tt>src/devices/bus_isa.c</tt>.
+         </ul>
+   <p>
    <li>And last but not least, the device should have an access function.
          The access function is called whenever there is a load or store
-         to an address which is in the device' memory mapped region.
+         to an address which is in the device' memory mapped region. To
- <pre>
+         simplify things a little, a macro <tt>DEVICE_ACCESS(x)</tt>
-         int dev_foo_access(struct cpu *cpu, struct memory *mem,
+         is expanded into<pre>
+         int dev_x_access(struct cpu *cpu, struct memory *mem,
              uint64_t relative_addr, unsigned char *data, size_t len,
              int writeflag, void *extra)
+ </pre>  The access function can look like this:
+ <pre>
+         DEVICE_ACCESS(foo)
          {
                  struct foo_data *d = extra;
                  uint64_t idata = 0, odata = 0;
-                 idata = memory_readmax64(cpu, data, len);
+                 if (writeflag == MEM_WRITE)
+                         idata = memory_readmax64(cpu, data, len);
                  switch (relative_addr) {
-                 /* .... */
+                 /*  Handle accesses to individual addresses within
+                     the device here.  */
+                 /*  ...  */
                  }
                  if (writeflag == MEM_READ)
-Line 498 
 Each device should have the following:
+Line 445 
 Each device should have the following:
  </ul>
  <p>
- The return value of the access function has until 20040702 been a
+ The return value of the access function has until 2004-07-02 been a
  true/false value; 1 for success, or 0 for device access failure. A device
  access failure (on MIPS) will result in a DBE exception.
-Line 512 
 means that the access failed, and took 5
+Line 459 
 means that the access failed, and took 5
  <p>
  To be compatible with pre-20040702 devices, a return value of 0 is treated
- by the caller (in src/memory.c) as a value of -1.
+ by the caller (in <tt>src/memory_rw.c</tt>) as a value of -1.
- <p><br>
- <a name="regtest"></a>
- <h3>Regression tests</h3>
- In order to make sure that the emulator actually works like it is supposed
- to, it must be tested. For this purpose, there is a simple regression
- testing framework in the <b>tests/</b> directory.
- <p>
- <i>NOTE:  The regression testing framework is basically just a skeleton so far.
- Regression tests are very good to have. However, the fact that complete
- operating systems can run in the emulator indicate that the emulation is
- probably not too incorrect. This makes it less of a priority to write
- regression tests.</i>
- <p>
- To run all the regression tests, type <b>make regtest</b>. Each assembly
- language file matching the pattern <b>test_*.S</b> will be compiled and
- linked into a 64-bit MIPS ELF (using a gcc cross compiler), and run in the
- emulator. If everything goes well, you should see something like this:
- <pre>
-         $ make regtest
-         cd tests; make run_tests; cd ..
-         gcc33 -Wall -fomit-frame-pointer -fmove-all-movables -fpeephole -O2
-                 -mcpu=ev5 -I/usr/X11R6/include -lm -L/usr/X11R6/lib -lX11  do_tests.c
-                 -o do_tests
-         do_tests.c: In function `main':
-         do_tests.c:173: warning: unused variable `s'
-         /var/tmp//ccFOupvD.o: In function `do_tests':
-         /var/tmp//ccFOupvD.o(.text+0x3a8): warning: tmpnam() possibly used
-                 unsafely; consider using mkstemp()
-         mips64-unknown-elf-gcc -g -O3 -fno-builtin -fschedule-insns -mips64
-                 -mabi=64 test_common.c -c -o test_common.o
-         ./do_tests "mips64-unknown-elf-gcc -g -O3 -fno-builtin -fschedule-insns
-                 -mips64 -mabi=64" "mips64-unknown-elf-as -mabi=64 -mips64"
-                 "mips64-unknown-elf-ld -Ttext 0xa800000000030000 -e main
-                 --oformat=elf64-bigmips" "../gxemul"
-         Starting tests:
-           test_addu.S (-a)
-           test_addu.S (-a -b)
-           test_clo_clz.S (-a)
-           test_clo_clz.S (-a -b)
-           ..
-           test_unaligned.S (-a)
-           test_unaligned.S (-a -b)
-         Done. (12 tests done)
-             PASS:     12
-             FAIL:      0
-         ----------------
-           All tests OK
-         ----------------
- </pre>
- <p>
- Each test writes output to stdout, and there is a <b>test_*.good</b> for
- each <b>.S</b> file which contains the wanted output. If the actual output
- matches the <b>.good</b> file, then the test passes, otherwise it fails.
- <p>
- Read <b>tests/README</b> for more information.

 Legend:



Removed from v.2
 


changed lines


 
Added in v.42
 Legend:



Removed from v.2
 


changed lines


 
Added in v.42
-Removed from v.2
+Added in v.42

	ViewVC Help
Powered by ViewVC 1.1.26