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.42 2005/06/26 08:42:26 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 -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 -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 -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 -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 -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	<html><head><title>GXemul documentation: Misc.</title>
2	<meta name="robots" content="noarchive,nofollow,noindex"></head>
3	<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
11	<!--
12
13	$Id: misc.html,v 1.42 2005/06/26 08:42:26 debug Exp $
14
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 -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 -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 -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 -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 -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	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	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>