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

Parent Directory | Revision Log | View Patch Patch

-revision 12 by dpavlin,
Mon Oct  8 16:18:38 2007 UTC
+revision 40 by dpavlin,
Mon Oct  8 16:22:11 2007 UTC
 Line 4
  <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>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;</b></font>
+ <b>Gavare's eXperimental Emulator:</b></font><br>
  <font color="#000000" size="6"><b>Miscellaneous</b>
  </font></td></tr></table></td></tr></table><p>
  <!--
- $Id: misc.html,v 1.50 2005/08/16 05:15:24 debug Exp $
+ $Id: misc.html,v 1.68 2007/04/28 09:18:34 debug Exp $
- Copyright (C) 2003-2005  Anders Gavare.  All rights reserved.
+ Copyright (C) 2003-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 47 
 SUCH DAMAGE.
  <p>
  <ul>
-   <li><a href="#networking">Networking</a>
    <li><a href="#devel">Writing operating system code, or
          developing firmware, using GXemul</a>
    <li><a href="#compilercontruct">Using GXemul in compiler contruction courses</a>
    <li><a href="#disk">How to start the emulator with a disk image</a>
+   <li><a href="#tape_images">How to start the emulator with tape images</a>
+   <li><a href="#disk_overlays">How to use disk image overlays</a>
+   <li><a href="#filexfer">Transfering files to/from the guest OS</a>
    <li><a href="#largeimages">How to extract large gzipped disk images</a>
    <li><a href="#userland">Running userland binaries</a>
    <li><a href="#promdump">Using a PROM dump from a real machine</a>
-Line 63 
 SUCH DAMAGE.
+Line 65 
 SUCH DAMAGE.
- <p><br>
- <a name="networking"></a>
- <h3>Networking:</h3>
- It is possible to let the guest OS running inside the emulator get access to
- the Internet. If you are interested in the technical details, and the
- reasons why networking is implemented in the emulator the way it currently
- is implemented, you might want to read the <a href="technical.html#net">
- networking section in the technical documentation</a>.
- <p>
- The guest OS running inside the emulator uses a private IPv4 address, such
- as 10.0.0.1, and the emulator acts as a NAT-like gateway/firewall at IPv4
- address 10.0.0.254. To the outside world it will seem like it is the host's
- OS that connects to other machines on the internet, not the guest OS.
- <p>
- <font color="#ff0000">NOTE: This is still experimental!
- As of 2004-07-21, ARP + ICMP + UDP + TCP are emulated well enough to let
- NetBSD and OpenBSD install via ftp, and use the network for many normal
- activities, but not everything works yet.</font>
  <p><br>
-Line 94 
 activities, but not everything works yet
+Line 73 
 activities, but not everything works yet
  Is this a good idea?  The answer is yes and no, depending on the level of
  detail you need in your simulations. If you are developing an operating
- system or operating system kernel of your own, and wish to target
+ system or operating system kernel of your own, then the emulator can be a
- MIPS-like systems in general, then the answer might be yes, for
+ complement to testing on real hardware.
- experimental purposes.
- <p>Some examples of things that <i>don't</i> work, that you should keep in
+ <p>Important things to keep in mind:
- mind:
  <ul>
          <li>Porting code to a specific machine mode, e.g. a Silicon Graphics
-         machine, using GXemul, will not necessarily cause the code to
+         machine, using GXemul, will not "magically" cause the code to
          work on a real machine. Sometimes code works in GXemul which doesn't
          work on real hardware, sometimes it's the other way around.
-Line 111 
 mind:
+Line 88 
 mind:
          <li>GXemul contains bugs, and many things are not yet implemented.
          <p>
-         <li>I have only implemented devices in GXemul to the degree that
+         <li><b>Very important!</b> I have only implemented devices in GXemul
-         NetBSD, OpenBSD, etc, don't complain too much. One way to say it
+         to the degree that NetBSD, OpenBSD, Linux, etc don't complain too much.
-         is that the device implementations are "lazy hacks", based on the
+         <p>
-         assumption that the emulated OS is already developed and bug-free.
+         If you are developing a driver for a device which is emulated by
-         They are not intended to be used for development of new OS code,
+         GXemul, and your driver does not seem to be working, then the
-         so if you do that, then be prepared for bugs and inconsitencies.
+         probability of a bug in GXemul's implementation of the device is
+         very much higher than that of a bug in your driver.
+         <p>
+         The device implementations in GXemul are based on the assumption
+         that the emulated OS is already developed and bug-free. They are
+         not primarily intended to be used for development of new device
+         driver code in operating systems, so if you do that, then be
+         prepared for bugs and inconsitencies.
          <p>
          <li>CPU details in GXemul are usually wrong. If your code depends
          on, say, R10000 or MIPS64 specifics, chances are that GXemul will
-         not be sufficient. Again, this was done as "lazy hacks", and pretty
+         not be sufficient. One example is different revisions of ISAs;
-         much assumes that the OS being emulated is already developed
+         some instructions which should trigger an exception on a
-         and bug-free.
+         real MIPS processor usually execute anyway in GXemul. Another
+         example is if userland code tries to access kernel memory; in some
+         cases there is protection against this, but not in all cases (to get
+         higher performance).
          <p>
          <li>Caches. There is no cache emulation in GXemul right now. Caches
          for R2000/R3000 are faked well enough to run NetBSD, Ultrix, etc
-Line 145 
 your code during development, but it sho
+Line 130 
 your code during development, but it sho
  <h3>Using GXemul in compiler contruction courses:</h3>
  If you are learning how to write a compiler, and wish to target a
- realistic target platform, then MIPS (as emulated by GXemul)
+ realistic target platform, then MIPS or ARM (as emulated by GXemul)
- might be a suitable choice.
+ might be suitable choices.
  <ul>
    <li><b>(+)</b>&nbsp;&nbsp;Your compiler needs to output real assembly
-         language code, which the assembler (eg gas, the GNU assembler) can
+         language code, which the assembler (e.g. gas, the GNU assembler) can
          then compile into object format, and then you need to link this
          into an executable image. This is much closer to how things work
          in real life than running assembly language listings in a simulator
-         (eg SPIM).
+         (e.g. SPIM).
    <p>
    <li><b>(-)</b>&nbsp;&nbsp;GXemul does not simulate out-of-order
          execution, penalties related to instruction scheduling, or
-Line 182 
 emulated DECstation machine, you would u
+Line 167 
 emulated DECstation machine, you would u
  <pre>
          $ <b>gxemul -e 3max -d pmax_diskimage.fs netbsd-pmax-INSTALL</b>
  </pre>
- <p>
- NOTE: For some emulation modes, such as the DECstation mode, you do
+ <p>NOTE: For some emulation modes, such as the DECstation mode, you do
- <i>not</i> have to specify the name of the kernel, if the disk image is
+ <i>not</i> actually have to specify the name of the kernel, if the disk
- bootable!
+ image is bootable!
- <p>
- It is possible to have more than one disk. For each -d argument, a disk
+ <p>It is possible to have more than one disk. For each -d argument, a disk
  image is added; the first will be SCSI target 0, the second will be target 1, and so on,
  unless you specify explicitly which ID number the devices should have.
  <pre>
          $ <b>gxemul -e 3max -d disk0.raw -d disk1.raw -d 5:disk2.raw netbsd-pmax-INSTALL</b>
  </pre>
  Note: In the example above, disk2.raw will get scsi id 5.
- <p>
- If a filename has a 'c' prefix, or ends with ".iso", then it is assumed to be
+ <p>If a filename has a 'c' prefix, or ends with ".iso", then it is assumed to be
  a CDROM device (this can be overridden with a 'd' prefix, to force a read/write disk).
  For example, the following command would start the emulator with two
  CDROM images, and one harddisk image:
-Line 214 
 use it as a CD-ROM directly accessible f
+Line 199 
 use it as a CD-ROM directly accessible f
  </pre>
  It is probably possible to use harddisks as well this way, but I would not
  recommend it.
- <p>
+ <p><br>
+ <a name="tape_images"></a>
+ <h3>How to start the emulator with tape images:</h3>
  Using emulated tape drives is a bit more complicated than disks, because a
  tape can be made up of several "files" with space in between. The solution
  I have choosen is to have one file in the host's file system space for each
-Line 264 
 every time a tape is rewound, it is reop
+Line 258 
 every time a tape is rewound, it is reop
  on the command line. By changing what the symbolic name points to,
  you can "switch tapes" without quiting and restarting the emulator.
+ <p>
+ <font color="#ff0000">Note: Tape support is most likely very buggy,
+ because it has not been tested much, and has probably also suffered
+ from bit-rot by now.</font>
+ <p><br>
+ <a name="disk_overlays"></a>
+ <h3>How to use disk image overlays:</h3>
+ This is most likely best understood by an example:
+ <p><ul>
+   <li>Install e.g. <a href="guestoses.html#netbsdcatsinstall">NetBSD/cats</a>.
+         You will end up with a disk image called
+         <tt>nbsd_cats.img</tt>.
+   <p>
+   <li>Running the following command will boot straight from the disk
+         image, with no overlay images:<pre>
+         <b>gxemul -XEcats -d nbsd_cats.img netbsd.aout-GENERIC.gz</b>
+ </pre>
+   <li>You may now create an overlay file, a corresponding map file,
+         and start the emulator with the overlay image connected to
+         the same (explicit) ID as the base disk image:<pre>
+         <b>touch overlay.img overlay.img.map
+         gxemul -XEcats -d 0:nbsd_cats.img -d V0:overlay.img netbsd.aout-GENERIC.gz</b>
+ </pre>
+   <li>Any changes to the filesystem you perform when using the overlay
+         will only be written to that overlay. For example, to perform
+         a "roll back", you can do the following:<pre>
+         <b>rm -f overlay.img overlay.img.map
+         touch overlay.img overlay.img.map</b>
+ </pre>
+         and then simply start the emulator again, with the newly created
+         overlay image.
+ </ul>
+ <p>It is also possible to add multiple overlays. In that case, writes
+ always go the the <i>last</i> added overlay.
+ <p>GXemul uses Unix' way of supporting files with "holes",
+ so even if <tt>ls -l overlay.img</tt> says that the overlay is several
+ gigabytes large, <tt>du overlay.img</tt> should reveal that only the
+ blocks that have actually been written to have been stored in the
+ overlay, e.g.:<pre>
+         <b>$ ls -l
+         ..
+         -rw-r--r--  1 debug  wheel  3072319488 Mar 24 11:59 nbsd_cats.img
+         -rw-r--r--  1 debug  wheel     2465354 Mar 24 11:44 netbsd.aout-GENERIC.gz
+         -rw-r--r--  1 debug  wheel  2930841600 Mar 24 14:02 overlay.img
+         -rw-r--r--  1 debug  wheel      715538 Mar 24 14:02 overlay.img.map
+         $ du overlay.img
+    overlay.img
+ </b>
+ </pre>
+ <p>The .map file is simply a raw bitmap telling which blocks of the
+ overlay file that are in use.
+ <p><br>
+ <a name="filexfer"></a>
+ <h3>Transfering files to/from the guest OS:</h3>
+ If the emulated machine supports networking (see <a
+ href="networking.html#intro">this section</a> for more info), then the easiest
+ way to transfer files is probably to use FTP or similar methods.
+ <p>There is another way of transfering files which works for any kind of
+ emulated machine which supports disks (either SCSI or IDE). Any file can
+ be supplied as a disk image. For example, consider the following:<pre>
+         $ <b>gxemul -XEcats -d nbsd_cats.img -d archive.tar.gz netbsd-GENERIC</b>
+ </pre>
+ This will start NetBSD/cats with <tt>nbsd_cats.img</tt> as IDE master on
+ controller 0 (wd0), and <tt>archive.tar.gz</tt> as IDE slave on controller
+(wd1). From inside NetBSD, it is now possible to extract the files using
+ the following command:<pre>
+         (inside emulated NetBSD/cats)
+         # <b>tar zxvf /dev/wd1c</b>
+ </pre>
+ Don't worry if NetBSD complains about lack of disklabel; it doesn't
+ matter. On some machines, NetBSD uses <tt>wd1d</tt> instead of
+ <tt>wd1c</tt> for the entire disk.
+ There is also a minor problem: reading the end of the disk image. If you
+ experience problems untaring archives like this, then pad out the archive
+ first with some zeroes.
+ <p>Transfering files <i>out</i> from the emulated operating system to the
+ host can be done the same way. First, prepare an empty archive file:<pre>
+         $ <b>dd if=/dev/zero of=newarchive.tar bs=1024 count=1 seek=10000</b>
+ </pre>This example created a 10 MB empty file. Then, start the emulator
+ like this:<pre>
+         $ <b>gxemul -XEcats -d nbsd_cats.img -d archive.tar netbsd-GENERIC</b>
+ </pre>
+ and transfer files by creating an archive directly onto the disk image:<pre>
+         (inside emulated NetBSD/cats)
+         # <b>tar cvf /dev/wd1c filenames</b>
+ </pre>
+ where filenames are the files or directories to transfer.
  <p><br>
-Line 310 
 count.)
+Line 416 
 count.)
  <a name="userland"></a>
  <h3>Running userland binaries:</h3>
- <font color="#ff0000">Note: This does not really work yet.</font>
+ <font color="#ff0000">Note: This feature does not really work yet.
+ It is currently disabled in stable release builds of the emulator.</font>
  <p>There is some skeleton code for running userland programs as well. This
  will not emulate any particular machine, but instead try to translate
-Line 480 
 This binary image can now be used in the
+Line 587 
 This binary image can now be used in the
           osconsole=3
          >>
  </pre>
- <i>(Note: at the moment, this doesn't work. I must have broken something when
- fixing something else, but this is what it looked like at the time.)</i>
+ <p><font color="#ff0000">(Note: at the moment, this doesn't work.
- <p>
+ I must have broken something when fixing something else, but this
- During bootup, the PROM complains <i>a lot</i> about hardware failures.
+ is what it looked like at the time.)</font>
+ <p>During bootup, the PROM complains <i>a lot</i> about hardware failures.
  That's because the emulator doesn't emulate the hardware well enough yet.
- <p>
- The command line options used are: -e 3min for
+ <p>The command line options used are: <tt>-e 3min</tt> for
- "DECstation 3min" (5000/1xx), -Q to supress the emulator's own PROM
+ "DECstation 3min" (5000/1xx), <tt>-Q</tt> to supress the emulator's own PROM
- call emulation, -M128 for 128MB RAM (because GXemul doesn't correctly
+ call emulation, <tt>-M128</tt> for 128MB RAM (because GXemul doesn't correctly
  emulate memory detection well enough for the PROM to accept, so it will
- always believe there is 128MB ram anyway), and -q to supress debug messages.
+ always believe there is 128MB ram anyway), and <tt>-q</tt> to supress debug messages.
- The 0xbfc00000 in front of the filename tells GXemul that it is a raw
+ The <tt>0xbfc00000</tt> in front of the filename tells GXemul that it is a raw
  binary file which should be loaded at a specific virtual address.
-Line 499 
 binary file which should be loaded at a
+Line 608 
 binary file which should be loaded at a
  <h4>Dumping the PROM on a SGI O2:</h4>
  The general ideas in this section applies to using ROM images from other
- machines as well. Besides DECstation, I've also tried this on an SGI IP32
+ machines as well. I have also tried this on an SGI IP32 ("O2"), in addition
- ("O2").
+ to the DECstation.
- <p>
- For the O2, a suitable command to dump the prom memory range is
+ <p>For the O2, a suitable command to dump the prom memory range is
  <pre>
          &gt;&gt; <b>dump -b 0xBFC00000:0xBFC80000</b>
  </pre>
  Make sure you capture all the output (via serial console) into a file,
- and then run experiments/sgiprom_to_bin on the captured file.
+ and then run <tt>experiments/sgiprom_to_bin</tt> on the captured file.
- <p>
- (2005-01-16: The emulator doesn't really emulate the IP32 well enough to
- actually run the PROM image without using special hacks, but it might do
- so some time in the future.)
+ <p>
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+ <a href="sgi-o2-real.jpg"><img src="sgi-o2-real_small.jpg"></a>
+ &nbsp;&nbsp;&nbsp;
+ <a href="20050817-sgi-o2-success-7.png"><img src="20050817-sgi-o2-success-7_small.png"></a>
+ &nbsp;&nbsp;&nbsp;
+ <a href="20050817-sgi-o2-success-8.png"><img src="20050817-sgi-o2-success-8_small.png"></a>
+ <p>The photo on the left is from the real machine. The other two are
+ screenshots of the PROM running experimentally in GXemul, using <tt>-Y2</tt>
+ framebuffer scaledown.
+ <p>Normally during bootup, the IP32 PROM does a Power-On test which makes
+ sure that the caches and other things are working properly. GXemul doesn't
+ emulate all those things well enough for the tests to pass. The
+ experimental screenshots above were taken with cache detection skipped
+ manually.
+ <p><font color="#ff0000">
+ In other words: don't expect this to work out-of-the-box with GXemul right
+ now. It might work once I've added correct cache emulation.</font>
+ <p>The command line used to start the emulator, once correct cache
+ emulation has been implemented, would be something like <tt>gxemul -XQeo2
+xbfc00000:prom.bin</tt>.
+ <p>The same caution applies when dealing with SGI PROMs as with
+ DECstation PROMs: GXemul doesn't really emulate the hardware, it only
+ "fakes" devices well enough to fool some things, primarily NetBSD, that
+ it is emulating a real machine. ROM code is usually a <i>lot</i> more
+ picky about the details.
+ <p>The graphics used in the O2 is (as far as I know) undocumented. Combining
+ some traces of info from how Linux/O2 draws to the screen with some
+ reverse-engineering of my own, I've implemented enough of the controller to
+ let the PROM draw rectangles and bitmaps, but not much more. The SCSI
+ controller is not implemented yet either.

 Legend:



Removed from v.12
 


changed lines


 
Added in v.40
 Legend:



Removed from v.12
 


changed lines


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

	ViewVC Help
Powered by ViewVC 1.1.26