trunk/doc/misc.html

<html>
<head><title>GXemul documentation: Misc.</title>
</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>
<!-- The first 10 lines are cut away by the homepage updating script.  -->


<!--

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