trunk/doc/misc.html

<html><head><title>GXemul documentation: Misc.</title>
<meta name="robots" content="noarchive,nofollow,noindex"></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;
<font color="#000000" size="6"><b>Misc.</b>
</font></td></tr></table></td></tr></table><p>

<!--

$Id: misc.html,v 1.41 2005/06/04 22:47:49 debug Exp $

Copyright (C) 2003-2005  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:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

-->

<a href="./">Back to the index</a>

<p><br>
<h2>Misc.</h2>

<p>
<ul>
  <li><a href="#networking">Networking</a>
  <li><a href="#portmips">Porting operating systems to MIPS 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="#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>
</ul>


<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>
<a name="portmips"></a>
<h3>Porting operating systems to MIPS using GXemul:</h3>

Is this a good idea?  The answer is yes and no, depending on what you are
trying to port to. If you are developing an operating system or operating
system kernel of your own, and wish to target MIPS-like systems in general,
then the answer might be yes, for experimental purposes.

<p>
However, if you think that you can port an operating system
to, say, the Silicon Graphics machine mode of GXemul and hope that your
operating system will run on a real SGI machine, then you will most
likely fail. GXemul simply does not emulate things well enough for that to work.
Another example would be specific CPU details; if your code depends on,
say, R10000 specifics, chances are that GXemul will not be sufficient.

<p>
In many cases, hardware devices in GXemul are only implemented well
enough to fool eg. NetBSD that they are working correctly, while in
fact they don't work very much at all.  Please keep this in mind, if you plan
to use GXemul when porting your code to MIPS.


<p><br>
<a name="compilercontruct"></a>
<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)
might be a suitable choice.

<ul>
  <li><b>(+)</b>&nbsp;&nbsp;Your compiler needs to output real assembly
        language code, which the assembler (eg 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).
  <p>
  <li><b>(-)</b>&nbsp;&nbsp;GXemul does not simulate out-of-order
        execution, penalties related to instruction scheduling, or
        load-delays, so it cannot be used to create optimizing compilers
        that take advantage of such processor features. GXemul keeps
        track of the number of instructions executed, but that's it.
</ul>


<p><br>
<a name="disk"></a>
<h3>How to start the emulator with a disk image:</h3>

Add <i>-d [prefixes:]diskimagefilename</i> to the command line, where prefixes
are one or more single-character options. Run <b>gxemul -h</b>
to get a list of possible options.

<p>
Here are some examples. If you want to run a NetBSD/pmax kernel on an
emulated DECstation machine, you would use a command line such as this:
<pre>
        $ <b>gxemul -E dec -e 3max -b -d pmax_diskimage.fs netbsd-pmax-INSTALL</b>
</pre>
<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 
bootable!
<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 dec -e 3max -b -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
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:
<pre>
        $ <b>gxemul -E dec -e 3max -b -d image.iso -d disk0.img -d c:second_cdrom.img netbsd-pmax-INSTALL</b>
</pre>
Usually, the device with the lowest id becomes the boot device. To override
this, add a 'b' prefix to one of the devices:
<pre>
        $ <b>gxemul -E dec -e 3max -b -d rootdisk.img -d bc:install-cd.iso name_of_kernel</b>
</pre>
If you have a physical CD-ROM drive on the host machine, say /dev/cd0c, you can
use it as a CD-ROM directly accessible from within the emulator:
<pre>
        $ <b>gxemul -E dec -e 3max -b -d rootdisk.img -d bc:/dev/cd0c name_of_kernel</b>
</pre>
It is probably possible to use harddisks as well this way, but I would not
recommend it.
<p>
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
tape file. The prefix for using tapes is 't', and the filename given is
for the <i>first</i> file on that tape (number zero, implicitly). For
files following file nr 0, a dot and the filenumber is appended to the
filename.
<p>
As an example, starting the emulator with
<pre>
        <b>-d t4:mytape.img</b>
</pre>
will cause SCSI id 4 to be a tape device, using the following file number
to name translation scheme:
<p>
<center>
 <table border="0">
  <tr>
    <td><b>File number:</b></td>
    <td><b>File name in the host's filesystem:</b></td>
  </tr>
  <tr>
    <td align="center">0</td>
    <td align="left">mytape.img</td>
  </tr>
  <tr>
    <td align="center">1</td>
    <td align="left">mytape.img.1</td>
  </tr>
  <tr>
    <td align="center">2</td>
    <td align="left">mytape.img.2</td>
  </tr>
  <tr>
    <td align="center">..</td>
    <td align="left">..</td>
  </tr>
 </table>
</center>
<p>
If you already have a number of tape files, which should be placed on the
same emulated tape, then you might not want to rename all those files.
Use symbolic links instead (ln -s).
<p>
There is another advantage to using symbolic links for tape filenames:
every time a tape is rewound, it is reopened using the filename given
on the command line. By changing what the symbolic name points to,
you can "switch tapes" without quiting and restarting the emulator.


<p><br>
<a name="largeimages"></a>
<h3>How to extract large gzipped disk images:</h3>

Unix filesystems usually support large files with "holes". Holes are 
zero-filled blocks that don't actually exist on disk. This is very 
practical for emulated disk images, as it is possible to create a very 
large disk image without using up much space at all.

<p>
Using gzip and gunzip on disk images can be <i>very</i> slow, as these 
files can be multiple gigabytes large, but this is usually necessary for
transfering disk images over the internet. If you receive a gzipped disk 
image, say disk.img.gz, and run a naive
<p>
<pre>
        $ <b>gunzip disk.img.gz</b>
</pre>
<p>
on it, you will not end up with an optimized file unless 
gunzip supports that. (In my experiments, it doesn't.)  In plain English, 
if you type <b>ls -l</b> and the filesize is 9 GB, it will actually occupy 
9 GB of disk space! This is often unacceptable.
<p>
Using a simple tool which only writes blocks that are non-zero, a lot of 
space can be saved. Compile the program cp_removeblocks in the 
experiments/ directory, and type:
<p>
<pre>
        $ <b>gunzip -c disk.img.gz | cp_removeblocks /dev/stdin disk.img</b>
</pre>

<p>
This will give you a disk.img which looks like it is 9 GB, and works like
the real file, but the holes are not written out to the disk. (You can see
this by running for example <b>du disk.img</b> to see the physical block
count.)


<p><br>
<a name="userland"></a>
<h3>Running userland binaries:</h3>

You can run (some) userland programs as well. This will not emulate any
particular machine, but instead try to translate syscalls from for example
NetBSD/pmax into the host's OS' syscalls. Right now, this is just a 
proof-of-concept, to show that it would work; there's lots of work left to 
do to make it actually run useful programs (for example dynamically linked 
programs).

<p>

<ul>
  <li><b>NetBSD/pmax:</b>
        <br>
        Running /bin/hostname or /bin/date and similarly trivial
        programs from the NetBSD/pmax distribution works:<pre>
        $ <b>gxemul -q -u netbsd/pmax pmax_bin_hostname</b>
        tab.csbnet.se
        $ <b>gxemul -q -u netbsd/pmax pmax_bin_date</b>
        Sun Jan 25 02:26:14 GMT 2004
        $ <b>gxemul -q -u netbsd/pmax pmax_bin_sleep</b>
        usage: pmax_bin_sleep seconds
        $ <b>gxemul -q -u netbsd/pmax pmax_bin_sleep 5</b>
        $ <b>gxemul -q -u netbsd/pmax pmax_bin_sync</b>
</pre>

  <p>
  <li><b>Ultrix:</b>
        <br>
        At least /bin/date and /bin/hostname work:<pre>
        $ <b>gxemul -q -u ultrix ultrix4_bin_date</b>
        UNIMPLEMENTED ultrix syscall 54
        UNIMPLEMENTED ultrix syscall 62
        Mon Feb  9 12:50:59 WET 2004
        $ <b>gxemul -q -u ultrix ultrix4_bin_hostname</b>
        tab.csbnet.se
</pre>

  <p>
  <li><b>NetBSD/powerpc:</b>
        <br>
        /bin/sync from NetBSD/macppc works, but probably not much else.<pre>
        $ <b>gxemul -v -u netbsd/powerpc netbsd-1.6.2-macppc-bin-sync</b>
        ...
        [ sync() ]
        [ exit(0) ]
        cpu_run_deinit(): All CPUs halted.

</pre>

  <p>
  <li><b>Linux/PPC64:</b>
        <br>
        The <a href="http://www-106.ibm.com/developerworks/library/l-ppc/#h13">64-bit Hello World assembly language example</a>
        on IBM's developerWorks pages runs:<pre>
        $ <b>ppc64-unknown-linux-as hello-ppc64.s -o hello-ppc64.o</b>
        $ <b>ppc64-unknown-linux-ld hello-ppc64.o -o hello-ppc64</b>
        $ <b>gxemul -q -u linux/ppc64 hello-ppc64</b>
        Hello, world!

</pre>

</ul>


<p><br>
<a name="promdump"></a>
<h3>Using a PROM dump from a real machine:</h3>

Raw PROM images from real machines can, in a few cases, be used in
the emulator. ROM code is usually much more sensitive to correctness
of the emulator than operating system kernels or userland programs
are, so don't expect any PROM image to just magically work.


<p>
<h4>Dumping the PROM on a DECstation 5000/125:</h4>
The image first needs to be extracted from the machine. There are
several ways to do this.
<ul>
  <li>Use hardware to read the PROM chip(s) directly. Not easy if you
        don't have such a hardware reader.
  <li>Copy the PROM memory range into a file, from a running
        operating system. You need a running OS, and it must
        have access to the PROM memory range. NetBSD, for example,
        doesn't allow that from userland.
  <li>Hook up a serial console and dump using the PROM's own dump
        command.
</ul>
<p>
The easiest way is to hook up a serial console. The terminal must be
able to capture output to a file.
<p>
These are approximately the commands that I used:
<pre>
        >><b>cnfg</b>                             <i>Show machine configuration</i>

        >><b>printenv</b>                         <i>Show environment variables</i>

        >><b>setenv more 0</b>                    <i>This turns off the More messages</i>

        >><b>e -x 0xbfc00000:0xbfffffff</b>       <i>Dump the PROM data</i>
</pre>
<p>
Remember that DECstations are little endian, so if the dump data
looks like this:
<pre>
        bfc00000:  0x0bf0007e
</pre>
then the bytes in memory are actually 0x7e, 0x00, 0xf0, and 0x0b.
<p>
At 9600 bps, about 10KB can be dumped per minute, so it takes a while.
Once enough of the PROM has been dumped, you can press CTRL-C to break out.
Then, restore the more environment variable:
<pre>
        >><b>setenv more 24</b>
</pre>
<p>
Now, convert the data you just saved (little-endian words -> bytes),
and store in a file. Let's call this file DECstation5000_125_promdump.bin.
<pre>
        $ <b>decprom_dump_txt_to_bin DECstation5000_125_promdump.txt DECstation5000_125_promdump.bin</b>
</pre>
This binary image can now be used in the emulator:
<pre>
        $ <b>gxemul -E dec -e 3min -Q -M128 -q 0xbfc00000:DECstation5000_125_promdump.bin</b>

        KN02-BA V5.7e   
        ?TFL:  3/scc/access (1:Ln1 reg-12: actual=0x00 xpctd=0x01) [KN02-BA]
        ?TFL:  3/scc/io (1:Ln0 tx bfr not empty. status=0X 0) [KN02-BA]
        ...
        --More--?TFL: 3/scsi/cntl (CUX, cause= 1000002C)
        >><b>?</b>
         ? [cmd]
         boot [[-z #] [-n] #/path [ARG...]]
         cat SCRPT
         cnfg [#]
         d [-bhw] [-S #] RNG VAL
         e [-bhwcdoux] [-S #] RNG
         erl [-c]
         go [ADR]
         init [#] [-m] [ARG...]
         ls [#]
         passwd [-c] [-s]
         printenv [EVN]
         restart
         script SCRPT
         setenv EVN STR
         sh [-belvS] [SCRPT] [ARG..]
         t [-l] #/STR [ARG..]
         unsetenv EVN
        >><b>cnfg</b>
         3: KN02-BA  DEC      V5.7e    TCF0  (128 MB)
                                             (enet: 00-00-00-00-00-00)
                                             (SCSI = 7)
         0: PMAG-BA  DEC      V5.3a    TCF0
        >><b>printenv</b>
         boot=
         testaction=q
         haltaction=h
         more=24
         #=3
         console=*
         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>
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 dec for DECstation, -e 3min for
"model 3" (5000/1xx), -Q to supress the emulator's own PROM
call emulation, -M128 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.
The 0xbfc00000 in front of the filename tells GXemul that it is a raw
binary file which should be loaded at a specific virtual address.


<p><br>
<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
("O2").
<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.
<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>

</body>
</html>
1	dpavlin	8	<html><head><title>GXemul documentation: Misc.</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			<b>GXemul documentation:</b></font>
8			<font color="#000000" size="6"><b>Misc.</b>
9			</font></td></tr></table></td></tr></table><p>
10	dpavlin	2
11			<!--
12
13	dpavlin	8	$Id: misc.html,v 1.41 2005/06/04 22:47:49 debug Exp $
14	dpavlin	2
15			Copyright (C) 2003-2005 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>Misc.</h2>
46
47			<p>
48			<ul>
49			<li><a href="#networking">Networking</a>
50			<li><a href="#portmips">Porting operating systems to MIPS using GXemul</a>
51			<li><a href="#compilercontruct">Using GXemul in compiler contruction courses</a>
52			<li><a href="#disk">How to start the emulator with a disk image</a>
53			<li><a href="#largeimages">How to extract large gzipped disk images</a>
54			<li><a href="#userland">Running userland binaries</a>
55			<li><a href="#promdump">Using a PROM dump from a real machine</a>
56			</ul>
57
58
59
60
61
62
63
64			<p><br>
65			<a name="networking"></a>
66			<h3>Networking:</h3>
67
68			It is possible to let the guest OS running inside the emulator get access to
69			the Internet. If you are interested in the technical details, and the
70			reasons why networking is implemented in the emulator the way it currently
71			is implemented, you might want to read the <a href="technical.html#net">
72			networking section in the technical documentation</a>.
73			<p>
74			The guest OS running inside the emulator uses a private IPv4 address, such
75			as 10.0.0.1, and the emulator acts as a NAT-like gateway/firewall at IPv4
76			address 10.0.0.254. To the outside world it will seem like it is the host's
77			OS that connects to other machines on the internet, not the guest OS.
78			<p>
79			<font color="#ff0000">NOTE: This is still experimental!
80			As of 2004-07-21, ARP + ICMP + UDP + TCP are emulated well enough to let
81			NetBSD and OpenBSD install via ftp, and use the network for many normal
82			activities, but not everything works yet.</font>
83
84
85
86
87
88
89			<p><br>
90			<a name="portmips"></a>
91			<h3>Porting operating systems to MIPS using GXemul:</h3>
92
93			Is this a good idea? The answer is yes and no, depending on what you are
94			trying to port to. If you are developing an operating system or operating
95			system kernel of your own, and wish to target MIPS-like systems in general,
96			then the answer might be yes, for experimental purposes.
97
98			<p>
99			However, if you think that you can port an operating system
100			to, say, the Silicon Graphics machine mode of GXemul and hope that your
101			operating system will run on a real SGI machine, then you will most
102			likely fail. GXemul simply does not emulate things well enough for that to work.
103			Another example would be specific CPU details; if your code depends on,
104			say, R10000 specifics, chances are that GXemul will not be sufficient.
105
106			<p>
107			In many cases, hardware devices in GXemul are only implemented well
108			enough to fool eg. NetBSD that they are working correctly, while in
109			fact they don't work very much at all. Please keep this in mind, if you plan
110			to use GXemul when porting your code to MIPS.
111
112
113
114
115
116
117
118			<p><br>
119			<a name="compilercontruct"></a>
120			<h3>Using GXemul in compiler contruction courses:</h3>
121
122			If you are learning how to write a compiler, and wish to target a
123			realistic target platform, then MIPS (as emulated by GXemul)
124			might be a suitable choice.
125
126			<ul>
127			<li><b>(+)</b>  Your compiler needs to output real assembly
128			language code, which the assembler (eg gas, the GNU assembler) can
129			then compile into object format, and then you need to link this
130			into an executable image. This is much closer to how things work
131			in real life than running assembly language listings in a simulator
132			(eg SPIM).
133			<p>
134			<li><b>(-)</b>  GXemul does not simulate out-of-order
135			execution, penalties related to instruction scheduling, or
136			load-delays, so it cannot be used to create optimizing compilers
137			that take advantage of such processor features. GXemul keeps
138			track of the number of instructions executed, but that's it.
139			</ul>
140
141
142
143
144
145
146			<p><br>
147			<a name="disk"></a>
148			<h3>How to start the emulator with a disk image:</h3>
149
150			Add <i>-d [prefixes:]diskimagefilename</i> to the command line, where prefixes
151			are one or more single-character options. Run <b>gxemul -h</b>
152			to get a list of possible options.
153
154			<p>
155			Here are some examples. If you want to run a NetBSD/pmax kernel on an
156			emulated DECstation machine, you would use a command line such as this:
157			<pre>
158			$ <b>gxemul -E dec -e 3max -b -d pmax_diskimage.fs netbsd-pmax-INSTALL</b>
159			</pre>
160			<p>
161			NOTE: For some emulation modes, such as the DECstation mode, you do
162			<i>not</i> have to specify the name of the kernel, if the disk image is
163			bootable!
164			<p>
165			It is possible to have more than one disk. For each -d argument, a disk
166			image is added; the first will be SCSI target 0, the second will be target 1, and so on,
167			unless you specify explicitly which ID number the devices should have.
168			<pre>
169			$ <b>gxemul -E dec -e 3max -b -d disk0.raw -d disk1.raw -d 5:disk2.raw netbsd-pmax-INSTALL</b>
170			</pre>
171			Note: In the example above, disk2.raw will get scsi id 5.
172			<p>
173			If a filename has a 'c' prefix, or ends with ".iso", then it is assumed to be
174			a CDROM device (this can be overridden with a 'd' prefix, to force a read/write disk).
175			For example, the following command would start the emulator with two
176			CDROM images, and one harddisk image:
177			<pre>
178			$ <b>gxemul -E dec -e 3max -b -d image.iso -d disk0.img -d c:second_cdrom.img netbsd-pmax-INSTALL</b>
179			</pre>
180			Usually, the device with the lowest id becomes the boot device. To override
181			this, add a 'b' prefix to one of the devices:
182			<pre>
183			$ <b>gxemul -E dec -e 3max -b -d rootdisk.img -d bc:install-cd.iso name_of_kernel</b>
184			</pre>
185			If you have a physical CD-ROM drive on the host machine, say /dev/cd0c, you can
186			use it as a CD-ROM directly accessible from within the emulator:
187			<pre>
188			$ <b>gxemul -E dec -e 3max -b -d rootdisk.img -d bc:/dev/cd0c name_of_kernel</b>
189			</pre>
190			It is probably possible to use harddisks as well this way, but I would not
191			recommend it.
192			<p>
193			Using emulated tape drives is a bit more complicated than disks, because a
194			tape can be made up of several "files" with space in between. The solution
195			I have choosen is to have one file in the host's file system space for each
196			tape file. The prefix for using tapes is 't', and the filename given is
197			for the <i>first</i> file on that tape (number zero, implicitly). For
198			files following file nr 0, a dot and the filenumber is appended to the
199			filename.
200			<p>
201			As an example, starting the emulator with
202			<pre>
203			<b>-d t4:mytape.img</b>
204			</pre>
205			will cause SCSI id 4 to be a tape device, using the following file number
206			to name translation scheme:
207			<p>
208			<center>
209			<table border="0">
210			<tr>
211			<td><b>File number:</b></td>
212			<td><b>File name in the host's filesystem:</b></td>
213			</tr>
214			<tr>
215			<td align="center">0</td>
216			<td align="left">mytape.img</td>
217			</tr>
218			<tr>
219			<td align="center">1</td>
220			<td align="left">mytape.img.1</td>
221			</tr>
222			<tr>
223			<td align="center">2</td>
224			<td align="left">mytape.img.2</td>
225			</tr>
226			<tr>
227			<td align="center">..</td>
228			<td align="left">..</td>
229			</tr>
230			</table>
231			</center>
232			<p>
233			If you already have a number of tape files, which should be placed on the
234			same emulated tape, then you might not want to rename all those files.
235			Use symbolic links instead (ln -s).
236			<p>
237			There is another advantage to using symbolic links for tape filenames:
238			every time a tape is rewound, it is reopened using the filename given
239			on the command line. By changing what the symbolic name points to,
240			you can "switch tapes" without quiting and restarting the emulator.
241
242
243
244			<p><br>
245			<a name="largeimages"></a>
246			<h3>How to extract large gzipped disk images:</h3>
247
248			Unix filesystems usually support large files with "holes". Holes are
249			zero-filled blocks that don't actually exist on disk. This is very
250			practical for emulated disk images, as it is possible to create a very
251			large disk image without using up much space at all.
252
253			<p>
254			Using gzip and gunzip on disk images can be <i>very</i> slow, as these
255			files can be multiple gigabytes large, but this is usually necessary for
256			transfering disk images over the internet. If you receive a gzipped disk
257			image, say disk.img.gz, and run a naive
258			<p>
259			<pre>
260			$ <b>gunzip disk.img.gz</b>
261			</pre>
262			<p>
263			on it, you will not end up with an optimized file unless
264			gunzip supports that. (In my experiments, it doesn't.) In plain English,
265			if you type <b>ls -l</b> and the filesize is 9 GB, it will actually occupy
266			9 GB of disk space! This is often unacceptable.
267			<p>
268			Using a simple tool which only writes blocks that are non-zero, a lot of
269			space can be saved. Compile the program cp_removeblocks in the
270			experiments/ directory, and type:
271			<p>
272			<pre>
273			$ <b>gunzip -c disk.img.gz \| cp_removeblocks /dev/stdin disk.img</b>
274			</pre>
275
276			<p>
277			This will give you a disk.img which looks like it is 9 GB, and works like
278			the real file, but the holes are not written out to the disk. (You can see
279			this by running for example <b>du disk.img</b> to see the physical block
280			count.)
281
282
283
284			<p><br>
285			<a name="userland"></a>
286			<h3>Running userland binaries:</h3>
287
288			You can run (some) userland programs as well. This will not emulate any
289			particular machine, but instead try to translate syscalls from for example
290			NetBSD/pmax into the host's OS' syscalls. Right now, this is just a
291			proof-of-concept, to show that it would work; there's lots of work left to
292			do to make it actually run useful programs (for example dynamically linked
293			programs).
294
295			<p>
296
297			<ul>
298			<li><b>NetBSD/pmax:</b>
299			<br>
300			Running /bin/hostname or /bin/date and similarly trivial
301			programs from the NetBSD/pmax distribution works:<pre>
302			$ <b>gxemul -q -u netbsd/pmax pmax_bin_hostname</b>
303			tab.csbnet.se
304			$ <b>gxemul -q -u netbsd/pmax pmax_bin_date</b>
305			Sun Jan 25 02:26:14 GMT 2004
306			$ <b>gxemul -q -u netbsd/pmax pmax_bin_sleep</b>
307			usage: pmax_bin_sleep seconds
308			$ <b>gxemul -q -u netbsd/pmax pmax_bin_sleep 5</b>
309			$ <b>gxemul -q -u netbsd/pmax pmax_bin_sync</b>
310			</pre>
311
312			<p>
313			<li><b>Ultrix:</b>
314			<br>
315			At least /bin/date and /bin/hostname work:<pre>
316			$ <b>gxemul -q -u ultrix ultrix4_bin_date</b>
317			UNIMPLEMENTED ultrix syscall 54
318			UNIMPLEMENTED ultrix syscall 62
319			Mon Feb 9 12:50:59 WET 2004
320			$ <b>gxemul -q -u ultrix ultrix4_bin_hostname</b>
321			tab.csbnet.se
322			</pre>
323
324			<p>
325			<li><b>NetBSD/powerpc:</b>
326			<br>
327			/bin/sync from NetBSD/macppc works, but probably not much else.<pre>
328			$ <b>gxemul -v -u netbsd/powerpc netbsd-1.6.2-macppc-bin-sync</b>
329			...
330			[ sync() ]
331			[ exit(0) ]
332			cpu_run_deinit(): All CPUs halted.
333
334			</pre>
335
336			<p>
337			<li><b>Linux/PPC64:</b>
338			<br>
339			The <a href="http://www-106.ibm.com/developerworks/library/l-ppc/#h13">64-bit Hello World assembly language example</a>
340			on IBM's developerWorks pages runs:<pre>
341			$ <b>ppc64-unknown-linux-as hello-ppc64.s -o hello-ppc64.o</b>
342			$ <b>ppc64-unknown-linux-ld hello-ppc64.o -o hello-ppc64</b>
343			$ <b>gxemul -q -u linux/ppc64 hello-ppc64</b>
344			Hello, world!
345
346			</pre>
347
348			</ul>
349
350
351
352
353
354			<p><br>
355			<a name="promdump"></a>
356			<h3>Using a PROM dump from a real machine:</h3>
357
358			Raw PROM images from real machines can, in a few cases, be used in
359			the emulator. ROM code is usually much more sensitive to correctness
360			of the emulator than operating system kernels or userland programs
361			are, so don't expect any PROM image to just magically work.
362
363
364			<p>
365			<h4>Dumping the PROM on a DECstation 5000/125:</h4>
366			The image first needs to be extracted from the machine. There are
367			several ways to do this.
368			<ul>
369			<li>Use hardware to read the PROM chip(s) directly. Not easy if you
370			don't have such a hardware reader.
371			<li>Copy the PROM memory range into a file, from a running
372			operating system. You need a running OS, and it must
373			have access to the PROM memory range. NetBSD, for example,
374			doesn't allow that from userland.
375			<li>Hook up a serial console and dump using the PROM's own dump
376			command.
377			</ul>
378			<p>
379			The easiest way is to hook up a serial console. The terminal must be
380			able to capture output to a file.
381			<p>
382			These are approximately the commands that I used:
383			<pre>
384			>><b>cnfg</b> <i>Show machine configuration</i>
385
386			>><b>printenv</b> <i>Show environment variables</i>
387
388			>><b>setenv more 0</b> <i>This turns off the More messages</i>
389
390			>><b>e -x 0xbfc00000:0xbfffffff</b> <i>Dump the PROM data</i>
391			</pre>
392			<p>
393			Remember that DECstations are little endian, so if the dump data
394			looks like this:
395			<pre>
396			bfc00000: 0x0bf0007e
397			</pre>
398			then the bytes in memory are actually 0x7e, 0x00, 0xf0, and 0x0b.
399			<p>
400			At 9600 bps, about 10KB can be dumped per minute, so it takes a while.
401			Once enough of the PROM has been dumped, you can press CTRL-C to break out.
402			Then, restore the more environment variable:
403			<pre>
404			>><b>setenv more 24</b>
405			</pre>
406			<p>
407			Now, convert the data you just saved (little-endian words -> bytes),
408			and store in a file. Let's call this file DECstation5000_125_promdump.bin.
409			<pre>
410			$ <b>decprom_dump_txt_to_bin DECstation5000_125_promdump.txt DECstation5000_125_promdump.bin</b>
411			</pre>
412			This binary image can now be used in the emulator:
413			<pre>
414			$ <b>gxemul -E dec -e 3min -Q -M128 -q 0xbfc00000:DECstation5000_125_promdump.bin</b>
415
416			KN02-BA V5.7e
417			?TFL: 3/scc/access (1:Ln1 reg-12: actual=0x00 xpctd=0x01) [KN02-BA]
418			?TFL: 3/scc/io (1:Ln0 tx bfr not empty. status=0X 0) [KN02-BA]
419			...
420			--More--?TFL: 3/scsi/cntl (CUX, cause= 1000002C)
421			>><b>?</b>
422			? [cmd]
423			boot [[-z #] [-n] #/path [ARG...]]
424			cat SCRPT
425			cnfg [#]
426			d [-bhw] [-S #] RNG VAL
427			e [-bhwcdoux] [-S #] RNG
428			erl [-c]
429			go [ADR]
430			init [#] [-m] [ARG...]
431			ls [#]
432			passwd [-c] [-s]
433			printenv [EVN]
434			restart
435			script SCRPT
436			setenv EVN STR
437			sh [-belvS] [SCRPT] [ARG..]
438			t [-l] #/STR [ARG..]
439			unsetenv EVN
440			>><b>cnfg</b>
441			3: KN02-BA DEC V5.7e TCF0 (128 MB)
442			(enet: 00-00-00-00-00-00)
443			(SCSI = 7)
444			0: PMAG-BA DEC V5.3a TCF0
445			>><b>printenv</b>
446			boot=
447			testaction=q
448			haltaction=h
449			more=24
450			#=3
451			console=*
452			osconsole=3
453			>>
454			</pre>
455			<i>(Note: at the moment, this doesn't work. I must have broken something when
456			fixing something else, but this is what it looked like at the time.)</i>
457			<p>
458			During bootup, the PROM complains <i>a lot</i> about hardware failures.
459			That's because the emulator doesn't emulate the hardware well enough yet.
460			<p>
461	dpavlin	4	The command line options used are: -E dec for DECstation, -e 3min for
462			"model 3" (5000/1xx), -Q to supress the emulator's own PROM
463	dpavlin	2	call emulation, -M128 for 128MB RAM (because GXemul doesn't correctly
464			emulate memory detection well enough for the PROM to accept, so it will
465			always believe there is 128MB ram anyway), and -q to supress debug messages.
466			The 0xbfc00000 in front of the filename tells GXemul that it is a raw
467			binary file which should be loaded at a specific virtual address.
468
469
470			<p><br>
471			<h4>Dumping the PROM on a SGI O2:</h4>
472
473			The general ideas in this section applies to using ROM images from other
474			machines as well. Besides DECstation, I've also tried this on an SGI IP32
475			("O2").
476			<p>
477			For the O2, a suitable command to dump the prom memory range is
478			<pre>
479			>> <b>dump -b 0xBFC00000:0xBFC80000</b>
480			</pre>
481			Make sure you capture all the output (via serial console) into a file,
482			and then run experiments/sgiprom_to_bin on the captured file.
483			<p>
484			(2005-01-16: The emulator doesn't really emulate the IP32 well enough to
485			actually run the PROM image without using special hacks, but it might do
486			so some time in the future.)
487
488
489
490
491
492			</p>
493
494			</body>
495			</html>