1 |
.\" $Id: gxemul.1,v 1.14 2005/04/16 02:38:21 debug Exp $ |
2 |
.\" |
3 |
.\" Copyright (C) 2004-2005 Anders Gavare. All rights reserved. |
4 |
.\" |
5 |
.\" Redistribution and use in source and binary forms, with or without |
6 |
.\" modification, are permitted provided that the following conditions are met: |
7 |
.\" |
8 |
.\" 1. Redistributions of source code must retain the above copyright |
9 |
.\" notice, this list of conditions and the following disclaimer. |
10 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
11 |
.\" notice, this list of conditions and the following disclaimer in the |
12 |
.\" documentation and/or other materials provided with the distribution. |
13 |
.\" 3. The name of the author may not be used to endorse or promote products |
14 |
.\" derived from this software without specific prior written permission. |
15 |
.\" |
16 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
17 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
18 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
19 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
20 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
21 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
22 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
23 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
24 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
25 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
26 |
.\" SUCH DAMAGE. |
27 |
.\" |
28 |
.\" |
29 |
.\" This is a minimal man page for GXemul. Process this file with |
30 |
.\" groff -man -Tascii gxemul.1 or nroff -man gxemul.1 |
31 |
.\" |
32 |
.Dd APRIL 2005 |
33 |
.Dt GXEMUL 1 |
34 |
.Os |
35 |
.Sh NAME |
36 |
.Nm gxemul |
37 |
.Nd an experimental machine emulator |
38 |
.Sh SYNOPSIS |
39 |
.Nm |
40 |
.Op machine, other, and general options |
41 |
.Op file Ar ... |
42 |
.Nm |
43 |
.Op general options |
44 |
.Op Ar @configfile ... |
45 |
.Nm |
46 |
.Op userland, other, and general options |
47 |
.Ar file Op Ar args ... |
48 |
.Sh DESCRIPTION |
49 |
.Nm |
50 |
is an experimental instruction-level machine emulator. It can be used |
51 |
to run binary code for (among others) MIPS-based machines. |
52 |
Several emulation modes are available. For some emulation modes, processors |
53 |
and surrounding hardware components are emulated well enough to let |
54 |
unmodified operating systems (eg NetBSD) run as if they were running on a |
55 |
real machine. |
56 |
.Pp |
57 |
There are three ways to invoke the emulator. When emulating a |
58 |
complete machine, settings can be entered directly on the command line, or |
59 |
they can be read from a configuration file. When emulating a userland |
60 |
environment (syscall-only emulation, not emulating complete machines), |
61 |
then the program name and its argument should be given on the command |
62 |
line. |
63 |
.Pp |
64 |
The easiest way to use the emulator is to supply settings directly on the |
65 |
command line. The most important thing you need to supply is the |
66 |
file argument. This is the name of a binary file (an ELF, a.out, ECOFF, |
67 |
SREC, or a raw binary image) which you wish to run in the emulator. This file |
68 |
might be an operating system kernel, or perhaps a ROM image file. |
69 |
.Pp |
70 |
If more than one filename is supplied, all files are loaded into memory, |
71 |
and the entry point (if available) is taken from the last file. |
72 |
.Pp |
73 |
Apart from the name of a binary file, it is also necessary to select |
74 |
which specific emulation mode to use. For example, a MIPS-based machine |
75 |
from DEC (a DECstation) is very different from a MIPS-based machine |
76 |
from SGI. Use |
77 |
.Nm |
78 |
.Fl H |
79 |
to get a list of available emulation modes. |
80 |
.Pp |
81 |
(There is an exception to the normal invocation usage mentioned above; |
82 |
if you want to use the DECstation emulation mode, and have a bootable |
83 |
DECstation harddisk or CDROM image, then just supplying the diskimage via |
84 |
the |
85 |
.Fl d |
86 |
option is sufficient. The filename of the kernel can then be |
87 |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
88 |
doesn't need the kernel as a separate file.) |
89 |
.Pp |
90 |
Machine selection options: |
91 |
.Bl -tag -width Ds |
92 |
.It Fl E Ar t |
93 |
Try to emulate machine type |
94 |
.Ar "t". |
95 |
(Use |
96 |
.Fl H |
97 |
to get a list of types.) |
98 |
.It Fl e Ar st |
99 |
Try to emulate machine subtype |
100 |
.Ar "st". |
101 |
Use this together with |
102 |
.Fl E . |
103 |
(This option is not always needed, if a machine type has no subtypes.) |
104 |
.El |
105 |
.Pp |
106 |
Other options: |
107 |
.Bl -tag -width Ds |
108 |
.It Fl B |
109 |
Disable dynamic binary translation completely. By default, bintrans |
110 |
will be turned on if the host architecture supports it. |
111 |
However, in this release (0.3.1), there is no new bintrans system. |
112 |
If you want to enable binary translation, use |
113 |
.Fl "b". |
114 |
.It Fl b |
115 |
Use the OLD binary translation subsystem. (Alpha and i386 hosts only.) |
116 |
.It Fl C Ar x |
117 |
Try to emulate a specific CPU type, |
118 |
.Ar "x". |
119 |
This overrides the default CPU type for the machine being emulated. |
120 |
(Use |
121 |
.Fl H |
122 |
to get a list of available CPU types.) |
123 |
.It Fl d Ar name |
124 |
Add |
125 |
.Ar name |
126 |
as a disk image. By adding one or more modifier characters and then a |
127 |
colon (":") as a prefix to |
128 |
.Ar "name", |
129 |
you can modify the disk image's behaviour. Available modifiers are: |
130 |
.Bl -tag -width Ds |
131 |
.It b |
132 |
Specifies that this is a boot device. |
133 |
.It c |
134 |
CD-ROM. |
135 |
.It d |
136 |
DISK (this is the default). |
137 |
.It f |
138 |
FLOPPY. |
139 |
.It i |
140 |
IDE. |
141 |
.It r |
142 |
Read-only (don't allow changes to be written to the file). |
143 |
.It s |
144 |
SCSI (this is the default for most machine types). |
145 |
.It t |
146 |
Tape. |
147 |
.It 0-7 |
148 |
Force a specific SCSI ID number. |
149 |
.El |
150 |
.Pp |
151 |
Filenames ending with ".iso" are assumed to be CDROM images. Files with a |
152 |
size of exactly 1.44 MB are assumed to be floppy images. All others |
153 |
are assumed to be disks. |
154 |
.It Fl I Ar x |
155 |
Emulate clock interrupts at |
156 |
.Ar x |
157 |
Hz. (This affects emulated clock devices only, not actual runtime speed. |
158 |
This disables automatic clock adjustments, which is otherwise turned on.) |
159 |
(This option is probably only valid for DECstation emulation.) |
160 |
.It Fl i |
161 |
Display each instruction as it is being executed. |
162 |
.It Fl J |
163 |
Disable some speed tricks. |
164 |
.It Fl j Ar n |
165 |
Set the name of the kernel to |
166 |
.Ar "n". |
167 |
Useful names are "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix. |
168 |
("netbsd" is usually the default value.) |
169 |
.It Fl M Ar m |
170 |
Emulate |
171 |
.Ar m |
172 |
MBs of physical RAM. This overrides the default amount of RAM for the |
173 |
selected machine type. |
174 |
.It Fl m Ar nr |
175 |
Run at most |
176 |
.Ar nr |
177 |
instructions (on any cpu). |
178 |
.It Fl N |
179 |
Display nr of instructions/second average, at regular intervals. |
180 |
.It Fl n Ar nr |
181 |
Set nr of CPUs (for SMP experiments). |
182 |
.It Fl O |
183 |
Force a "netboot" (tftp instead of disk), even when a disk image is |
184 |
present (for DECstation, SGI, and ARC emulation). |
185 |
.It Fl o Ar arg |
186 |
Set the boot argument (for DEC, ARC, or SGI emulation). |
187 |
Default |
188 |
.Ar arg |
189 |
for DEC is '-a', for ARC '-aN'. |
190 |
.It Fl p Ar pc |
191 |
Add a breakpoint (remember to use the '0x' prefix for hex). |
192 |
.It Fl Q |
193 |
Disable the built-in PROM emulation. This is useful for running raw ROM |
194 |
images from real machines. |
195 |
.It Fl R |
196 |
Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.) |
197 |
.It Fl r |
198 |
Dump register contents for every executed instruction. |
199 |
.It Fl S |
200 |
Initialize the emulated RAM to random data, instead of zeroes. |
201 |
.It Fl T |
202 |
Enter the single-step debugger on unimplemented memory accesses. |
203 |
.It Fl t |
204 |
Show a trace tree of all function calls being made. |
205 |
.It Fl U |
206 |
Enable slow_serial_interrupts_hack_for_linux. |
207 |
.It Fl X |
208 |
Use X11. |
209 |
.It Fl x |
210 |
Open up new xterms for emulated serial ports. (Default is to open up |
211 |
xterms when using configuration files, but not when starting an |
212 |
emulation with settings directly on the command line.) |
213 |
.It Fl Y Ar n |
214 |
Scale down framebuffer windows by |
215 |
.Ar n |
216 |
x |
217 |
.Ar n |
218 |
times. |
219 |
.It Fl y Ar x |
220 |
Set max_random_cycles_per_chunk to |
221 |
.Ar x |
222 |
(experimental). |
223 |
.It Fl Z Ar n |
224 |
Set the number of graphics cards, for emulating a dual-head or tripple-head |
225 |
environment. (Only for DECstation emulation so far.) |
226 |
.It Fl z Ar disp |
227 |
Add |
228 |
.Ar disp |
229 |
as an X11 display to use for framebuffers. |
230 |
.El |
231 |
.Pp |
232 |
Userland options: |
233 |
.Bl -tag -width Ds |
234 |
.It Fl u Ar emul-mode |
235 |
Userland-only (syscall) emulation. (Use |
236 |
.Fl H |
237 |
to get a list of available emulation modes.) Some (but not all) of the |
238 |
options listed under Other options above can also be used with userland |
239 |
emulation. |
240 |
.El |
241 |
.Pp |
242 |
General options: |
243 |
.Bl -tag -width Ds |
244 |
.It Fl D |
245 |
Guarantee fully deterministic behaviour. Normally, the emulator calls |
246 |
srandom() with a seed based on the current time at startup. When the |
247 |
.Fl D |
248 |
option is used, the srandom() call is skipped, which should cause two |
249 |
subsequent invokations of the emulator to be identical, if all other |
250 |
settings are identical. (If this option is used, then |
251 |
.Fl I |
252 |
must also be used.) |
253 |
.It Fl H |
254 |
Display a list of available CPU types, machine types, and userland |
255 |
emulation modes. (Most of these don't work. Please read the documentation |
256 |
included in the |
257 |
.Nm |
258 |
distribution for details on which modes that actually work.) |
259 |
.It Fl h |
260 |
Display a list of all available command line options. |
261 |
.It Fl K |
262 |
Force the single-step debugger to be entered at the end of a simulation. |
263 |
.It Fl q |
264 |
Quiet mode; this suppresses startup messages. |
265 |
.It Fl s |
266 |
Show opcode usage statistics after the simulation. |
267 |
.It Fl V |
268 |
Start up in the single-step debugger, paused. |
269 |
.It Fl v |
270 |
Verbose debug messages. |
271 |
.El |
272 |
.Pp |
273 |
Configuration file startup: |
274 |
.Bl -tag -width Ds |
275 |
.It @ Ar configfile |
276 |
Start an emulation based on the contents of |
277 |
.Ar "configfile". |
278 |
.El |
279 |
.Pp |
280 |
For more information, please read the documentation in the doc/ |
281 |
subdirectory of the |
282 |
.Nm |
283 |
distribution. |
284 |
.Sh EXAMPLES |
285 |
The following command will start NetBSD/pmax on an emulated DECstation |
286 |
5000/200 (3MAX), with the old bintrans system enabled: |
287 |
.Pp |
288 |
.Dl "gxemul -E dec -e 3max -b -d netbsddisk.img" |
289 |
.Pp |
290 |
netbsddisk.img should be a raw disk image containing a bootable |
291 |
NetBSD/pmax filesystem. |
292 |
.Pp |
293 |
The following command will start an emulation session based on settings in |
294 |
the configuration file "mysession". The -v option tells gxemul to be |
295 |
verbose. |
296 |
.Pp |
297 |
.Dl "gxemul -v @mysession" |
298 |
.Pp |
299 |
If you have compiled the small Hello World program mentioned in the |
300 |
.Nm |
301 |
documentation, the following command will start up an |
302 |
emulated test machine in "paused" mode: |
303 |
.Pp |
304 |
.Dl "gxemul -E testmips -V hello_mips" |
305 |
.Pp |
306 |
(Paused mode means that you enter the interactive single-step debugger |
307 |
directly at startup, instead of launching the Hello World program.) |
308 |
.Pp |
309 |
Please read the documentation for more details. |
310 |
.Sh BUGS |
311 |
There are many bugs. Some of the known bugs are listed in the BUGS |
312 |
file in the |
313 |
.Nm |
314 |
source distribution, some are indirectly mentioned in the TODO file. |
315 |
.Pp |
316 |
There is no new bintrans system in this release (0.3.1), so you will |
317 |
need to add |
318 |
.Fl b |
319 |
to select the old bintrans system, if you want speed. |
320 |
.Pp |
321 |
.Nm |
322 |
does not simulate individual pipe-line stages or penalties caused by |
323 |
branch-prediction misses, so it cannot be used for accurate performance |
324 |
measurement. |
325 |
.Sh AUTHOR |
326 |
Anders Gavare <anders@gavare.se> |
327 |
.Pp |
328 |
See http://gavare.se/gxemul/ for more information. |