1 |
.\" $Id: gxemul.1,v 1.14 2005/04/16 02:38:21 debug Exp $ |
.\" $Id: gxemul.1,v 1.39 2005/11/23 22:03:25 debug Exp $ |
2 |
.\" |
.\" |
3 |
.\" Copyright (C) 2004-2005 Anders Gavare. All rights reserved. |
.\" Copyright (C) 2004-2005 Anders Gavare. All rights reserved. |
4 |
.\" |
.\" |
29 |
.\" This is a minimal man page for GXemul. Process this file with |
.\" This is a minimal man page for GXemul. Process this file with |
30 |
.\" groff -man -Tascii gxemul.1 or nroff -man gxemul.1 |
.\" groff -man -Tascii gxemul.1 or nroff -man gxemul.1 |
31 |
.\" |
.\" |
32 |
.Dd APRIL 2005 |
.Dd NOVEMBER 2005 |
33 |
.Dt GXEMUL 1 |
.Dt GXEMUL 1 |
34 |
.Os |
.Os |
35 |
.Sh NAME |
.Sh NAME |
41 |
.Op file Ar ... |
.Op file Ar ... |
42 |
.Nm |
.Nm |
43 |
.Op general options |
.Op general options |
44 |
.Op Ar @configfile ... |
.Ar @configfile |
45 |
.Nm |
.Nm |
46 |
.Op userland, other, and general options |
.Op userland, other, and general options |
47 |
.Ar file Op Ar args ... |
.Ar file Op Ar args ... |
48 |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
49 |
.Nm |
.Nm |
50 |
is an experimental instruction-level machine emulator. It can be used |
is an experimental instruction-level machine emulator. Several |
51 |
to run binary code for (among others) MIPS-based machines. |
emulation modes are available. In some modes, processors and surrounding |
52 |
Several emulation modes are available. For some emulation modes, processors |
hardware components are emulated well enough to let unmodified operating |
53 |
and surrounding hardware components are emulated well enough to let |
systems (e.g. NetBSD) run inside the emulator as if they were running on a |
|
unmodified operating systems (eg NetBSD) run as if they were running on a |
|
54 |
real machine. |
real machine. |
55 |
.Pp |
.Pp |
56 |
There are three ways to invoke the emulator. When emulating a |
The processor architecture best emulated by GXemul is MIPS, but other |
57 |
complete machine, settings can be entered directly on the command line, or |
architectures (ARM and PowerPC) are also partially emulated. |
58 |
they can be read from a configuration file. When emulating a userland |
.Pp |
59 |
environment (syscall-only emulation, not emulating complete machines), |
MIPS processors are emulated either using a simple type of binary |
60 |
then the program name and its argument should be given on the command |
translator (on Alpha and i386 hosts), or using traditional slow |
61 |
line. |
interpretation (all other hosts, including amd64 machines running in |
62 |
|
64-bit mode). |
63 |
|
.Pp |
64 |
|
Non-MIPS processors are emulated using a newer dynamic |
65 |
|
translation system (called dyntrans in the rest of this man page); |
66 |
|
dyntrans does not require any host-specific code, so it should work on any |
67 |
|
platform. Performance is somewhere between binary translation and |
68 |
|
traditional interpretation. |
69 |
|
.Pp |
70 |
|
There are three ways to invoke the emulator: |
71 |
|
.Pp |
72 |
|
1. When emulating a complete machine, configuration options can be entered |
73 |
|
directly on the command line. |
74 |
|
.Pp |
75 |
|
2. Options can be read from a configuration file. |
76 |
|
.Pp |
77 |
|
3. When emulating a userland environment (syscall-only emulation, not |
78 |
|
emulating complete machines), then the program name and its argument |
79 |
|
should be given on the command line. (This mode doesn't really work yet.) |
80 |
.Pp |
.Pp |
81 |
The easiest way to use the emulator is to supply settings directly on the |
The easiest way to use the emulator is to supply settings directly on the |
82 |
command line. The most important thing you need to supply is the |
command line. The most important thing you need to supply is the |
83 |
file argument. This is the name of a binary file (an ELF, a.out, ECOFF, |
file argument. This is the name of a binary file (an ELF, a.out, COFF/ECOFF, |
84 |
SREC, or a raw binary image) which you wish to run in the emulator. This file |
SREC, or a raw binary image) which you wish to run in the emulator. This file |
85 |
might be an operating system kernel, or perhaps a ROM image file. |
might be an operating system kernel, or perhaps a ROM image file. |
86 |
.Pp |
.Pp |
95 |
.Fl H |
.Fl H |
96 |
to get a list of available emulation modes. |
to get a list of available emulation modes. |
97 |
.Pp |
.Pp |
98 |
(There is an exception to the normal invocation usage mentioned above; |
There are two exceptions to the normal invocation usage mentioned above. |
99 |
if you want to use the DECstation emulation mode, and have a bootable |
The first is for DECstation emulation: if you have a bootable |
100 |
DECstation harddisk or CDROM image, then just supplying the diskimage via |
DECstation harddisk or CDROM image, then just supplying the diskimage via |
101 |
the |
the |
102 |
.Fl d |
.Fl d |
103 |
option is sufficient. The filename of the kernel can then be |
option is sufficient. (The filename of the kernel can then be |
104 |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
105 |
doesn't need the kernel as a separate file.) |
doesn't need the kernel as a separate file.) |
106 |
|
The second is if you supply an ISO9660 CDROM disk image. You may then use |
107 |
|
the |
108 |
|
.Fl j |
109 |
|
option to indicate which file on the CDROM filesystem that should be |
110 |
|
loaded into emulated memory. |
111 |
.Pp |
.Pp |
112 |
Machine selection options: |
Machine selection options: |
113 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
114 |
.It Fl E Ar t |
.It Fl E Ar t |
115 |
Try to emulate machine type |
Try to emulate machine type |
116 |
.Ar "t". |
.Ar "t". |
117 |
|
This option is not always needed, if the |
118 |
|
.Fl e |
119 |
|
option uniquely selects a machine. |
120 |
(Use |
(Use |
121 |
.Fl H |
.Fl H |
122 |
to get a list of types.) |
to get a list of types.) |
130 |
.Pp |
.Pp |
131 |
Other options: |
Other options: |
132 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
133 |
|
.It Fl A |
134 |
|
Disable load/store alignment checks in some cases. This might give a small |
135 |
|
increase in performance, but the emulator will not run correctly if the |
136 |
|
emulated code actually tries to do unaligned loads or stores. (This option |
137 |
|
is only meaningful when emulating MIPS CPUs, when the host architecture is |
138 |
|
Alpha or i386, and binary translation is enabled.) |
139 |
.It Fl B |
.It Fl B |
140 |
Disable dynamic binary translation completely. By default, bintrans |
Disable dynamic binary translation. By default, bintrans |
141 |
will be turned on if the host architecture supports it. |
will be turned on if the host+target architecture combination is |
142 |
However, in this release (0.3.1), there is no new bintrans system. |
supported. Currently, the only supported target architecture for bintrans |
143 |
If you want to enable binary translation, use |
is MIPS, and the supported host architectures are Alpha and i386. |
|
.Fl "b". |
|
|
.It Fl b |
|
|
Use the OLD binary translation subsystem. (Alpha and i386 hosts only.) |
|
144 |
.It Fl C Ar x |
.It Fl C Ar x |
145 |
Try to emulate a specific CPU type, |
Try to emulate a specific CPU type, |
146 |
.Ar "x". |
.Ar "x". |
154 |
as a disk image. By adding one or more modifier characters and then a |
as a disk image. By adding one or more modifier characters and then a |
155 |
colon (":") as a prefix to |
colon (":") as a prefix to |
156 |
.Ar "name", |
.Ar "name", |
157 |
you can modify the disk image's behaviour. Available modifiers are: |
you can modify the way the disk image is treated. Available modifiers are: |
158 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
159 |
.It b |
.It b |
160 |
Specifies that this is a boot device. |
Specifies that this is a boot device. |
164 |
DISK (this is the default). |
DISK (this is the default). |
165 |
.It f |
.It f |
166 |
FLOPPY. |
FLOPPY. |
167 |
|
.It gH;S; |
168 |
|
Override the default geometry; use H heads and S sectors-per-track. |
169 |
|
(The number of cylinders is calculated automatically.) |
170 |
.It i |
.It i |
171 |
IDE. |
IDE. |
172 |
.It r |
.It r |
176 |
.It t |
.It t |
177 |
Tape. |
Tape. |
178 |
.It 0-7 |
.It 0-7 |
179 |
Force a specific SCSI ID number. |
Force a specific ID number. |
180 |
.El |
.El |
181 |
.Pp |
.Pp |
182 |
Filenames ending with ".iso" are assumed to be CDROM images. Files with a |
Unless otherwise specified, filenames ending with ".iso" or ".cdr" are |
183 |
size of exactly 1.44 MB are assumed to be floppy images. All others |
assumed to be CDROM images. Most others are assumed to be disks. Depending |
184 |
are assumed to be disks. |
on which machine is being emulated, the default for disks can be either |
185 |
|
SCSI or IDE. Some disk images that are very small are assumed to be floppy |
186 |
|
disks. (If you are not happy with the way a disk image is detected, then |
187 |
|
you need to use explicit prefixes to force a specific type.) |
188 |
|
.Pp |
189 |
|
For floppies, the gH;S; prefix is ignored. Instead, the number of |
190 |
|
heads and cylinders are assumed to be 2 and 80, respectively, and the |
191 |
|
number of sectors per track is calculated automatically. (This works for |
192 |
|
720KB, 1.2MB, 1.44MB, and 2.88MB floppies.) |
193 |
.It Fl I Ar x |
.It Fl I Ar x |
194 |
Emulate clock interrupts at |
Emulate clock interrupts at |
195 |
.Ar x |
.Ar x |
199 |
.It Fl i |
.It Fl i |
200 |
Display each instruction as it is being executed. |
Display each instruction as it is being executed. |
201 |
.It Fl J |
.It Fl J |
202 |
Disable some speed tricks. |
Disable some speed tricks. For MIPS emulation, these are mostly |
203 |
|
timing-related. For non-MIPS emulation (i.e. those modes using dyntrans), |
204 |
|
this flag disables the use of "instruction combinations". |
205 |
.It Fl j Ar n |
.It Fl j Ar n |
206 |
Set the name of the kernel to |
Set the name of the kernel to |
207 |
.Ar "n". |
.Ar "n". |
208 |
Useful names are "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix. |
When booting from an ISO9660 filesystem, the emulator will try to boot |
209 |
("netbsd" is usually the default value.) |
using this file. (In some emulation modes, eg. DECstation, this name is passed |
210 |
|
along to the boot program. Useful names are "bsd" for OpenBSD/pmax, |
211 |
|
or "vmunix" for Ultrix.) |
212 |
.It Fl M Ar m |
.It Fl M Ar m |
213 |
Emulate |
Emulate |
214 |
.Ar m |
.Ar m |
226 |
Force a "netboot" (tftp instead of disk), even when a disk image is |
Force a "netboot" (tftp instead of disk), even when a disk image is |
227 |
present (for DECstation, SGI, and ARC emulation). |
present (for DECstation, SGI, and ARC emulation). |
228 |
.It Fl o Ar arg |
.It Fl o Ar arg |
229 |
Set the boot argument (for DEC, ARC, or SGI emulation). |
Set the boot argument (mostly useful for DEC, ARC, or SGI emulation). |
230 |
Default |
Default |
231 |
.Ar arg |
.Ar arg |
232 |
for DEC is '-a', for ARC '-aN'. |
for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A". |
233 |
.It Fl p Ar pc |
.It Fl p Ar pc |
234 |
Add a breakpoint (remember to use the '0x' prefix for hex). |
Add a breakpoint. (Remember to use the "0x" prefix for hex.) |
235 |
.It Fl Q |
.It Fl Q |
236 |
Disable the built-in PROM emulation. This is useful for running raw ROM |
Disable the built-in PROM emulation. This is useful for running raw ROM |
237 |
images from real machines. |
images from real machines. |
258 |
.Ar n |
.Ar n |
259 |
x |
x |
260 |
.Ar n |
.Ar n |
261 |
times. |
times. This option is useful when emulating a very large framebuffer, and |
262 |
|
the actual display is of lower resolution. If |
263 |
|
.Ar n |
264 |
|
is negative, then there will be no scaledown, but emulation of certain |
265 |
|
graphic controllers will be scaled up |
266 |
|
by |
267 |
|
.Ar -n |
268 |
|
times instead. E.g. Using |
269 |
|
.Ar -2 |
270 |
|
with VGA text mode emulation will result in 80x25 character cells rendered |
271 |
|
in a 1280x800 window, instead of the normal resolution of 640x400. |
272 |
.It Fl y Ar x |
.It Fl y Ar x |
273 |
Set max_random_cycles_per_chunk to |
Set max_random_cycles_per_chunk to |
274 |
.Ar x |
.Ar x |
295 |
General options: |
General options: |
296 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
297 |
.It Fl D |
.It Fl D |
298 |
Guarantee fully deterministic behaviour. Normally, the emulator calls |
Guarantee fully deterministic behavior. Normally, the emulator calls |
299 |
srandom() with a seed based on the current time at startup. When the |
srandom() with a seed based on the current time at startup. When the |
300 |
.Fl D |
.Fl D |
301 |
option is used, the srandom() call is skipped, which should cause two |
option is used, the srandom() call is skipped, which should cause two |
302 |
subsequent invokations of the emulator to be identical, if all other |
subsequent invocations of the emulator to be identical, if all other |
303 |
settings are identical. (If this option is used, then |
settings are identical and no user input is taking place. (If this option |
304 |
|
is used, then |
305 |
.Fl I |
.Fl I |
306 |
must also be used.) |
must also be used.) |
307 |
.It Fl H |
.It Fl H |
317 |
.It Fl q |
.It Fl q |
318 |
Quiet mode; this suppresses startup messages. |
Quiet mode; this suppresses startup messages. |
319 |
.It Fl s |
.It Fl s |
320 |
Show opcode usage statistics after the simulation. |
For MIPS emulation: Show opcode usage statistics after the simulation. |
321 |
|
For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file at |
322 |
|
regular intervals of which physical addresses that were executed. |
323 |
.It Fl V |
.It Fl V |
324 |
Start up in the single-step debugger, paused. |
Start up in the single-step debugger, paused. |
325 |
.It Fl v |
.It Fl v |
339 |
distribution. |
distribution. |
340 |
.Sh EXAMPLES |
.Sh EXAMPLES |
341 |
The following command will start NetBSD/pmax on an emulated DECstation |
The following command will start NetBSD/pmax on an emulated DECstation |
342 |
5000/200 (3MAX), with the old bintrans system enabled: |
5000/200 (3MAX): |
343 |
.Pp |
.Pp |
344 |
.Dl "gxemul -E dec -e 3max -b -d netbsddisk.img" |
.Dl "gxemul -e 3max -d nbsd_pmax.img" |
345 |
.Pp |
.Pp |
346 |
netbsddisk.img should be a raw disk image containing a bootable |
nbsd_pmax.img should be a raw disk image containing a bootable |
347 |
NetBSD/pmax filesystem. |
NetBSD/pmax filesystem. |
348 |
.Pp |
.Pp |
349 |
The following command will start an emulation session based on settings in |
The following command will start an emulation session based on settings in |
367 |
There are many bugs. Some of the known bugs are listed in the BUGS |
There are many bugs. Some of the known bugs are listed in the BUGS |
368 |
file in the |
file in the |
369 |
.Nm |
.Nm |
370 |
source distribution, some are indirectly mentioned in the TODO file. |
source distribution, some are indirectly mentioned in the TODO file, |
371 |
|
and some are mentioned in the source code itself. |
372 |
|
.Pp |
373 |
|
The binary translation subsystem is really terrible, but it is less |
374 |
|
terrible than running without it. |
375 |
.Pp |
.Pp |
376 |
There is no new bintrans system in this release (0.3.1), so you will |
Userland (syscall-only) emulation doesn't really work yet. |
377 |
need to add |
.Pp |
378 |
.Fl b |
Emulation of MIPS CPUs is done differently from other emulation modes; the |
379 |
to select the old bintrans system, if you want speed. |
documentation sometimes only reflects the way things work with MIPS |
380 |
|
emulation, and it is incorrect when applied to e.g. ARM emulation. |
381 |
.Pp |
.Pp |
382 |
.Nm |
.Nm |
383 |
does not simulate individual pipe-line stages or penalties caused by |
does not simulate individual pipe-line stages or penalties caused by |
384 |
branch-prediction misses, so it cannot be used for accurate performance |
branch-prediction misses or cache misses, so it cannot be used for |
385 |
measurement. |
accurate simulation of any actual real-world processor. |
386 |
|
.Pp |
387 |
|
.Nm |
388 |
|
is not timing-accurate. |
389 |
.Sh AUTHOR |
.Sh AUTHOR |
390 |
Anders Gavare <anders@gavare.se> |
Anders Gavare <anders@gavare.se> |
391 |
.Pp |
.Pp |