1 |
.\" $Id: gxemul.1,v 1.21 2005/06/03 23:14:52 debug Exp $ |
.\" $Id: gxemul.1,v 1.33 2005/10/07 22:45:34 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 JUNE 2005 |
.Dd OCTOBER 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 as if they were running on a real machine. |
54 |
unmodified operating systems (eg. NetBSD) run as if they were running on a |
.Pp |
55 |
real machine. |
The processor architecture best emulated by GXemul is MIPS, but other |
56 |
.Pp |
architectures are also partially emulated. |
57 |
There are three ways to invoke the emulator. When emulating a |
.Pp |
58 |
complete machine, settings can be entered directly on the command line, or |
There are three ways to invoke the emulator: |
59 |
they can be read from a configuration file. When emulating a userland |
.Pp |
60 |
environment (syscall-only emulation, not emulating complete machines), |
1. When emulating a complete machine, configuration options can be entered |
61 |
then the program name and its argument should be given on the command |
directly on the command line. |
62 |
line. |
.Pp |
63 |
|
2. Options can be read from a configuration file. |
64 |
|
.Pp |
65 |
|
3. When emulating a userland environment (syscall-only emulation, not |
66 |
|
emulating complete machines), then the program name and its argument |
67 |
|
should be given on the command line. (This mode doesn't really work yet.) |
68 |
.Pp |
.Pp |
69 |
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 |
70 |
command line. The most important thing you need to supply is the |
command line. The most important thing you need to supply is the |
71 |
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, |
72 |
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 |
73 |
might be an operating system kernel, or perhaps a ROM image file. |
might be an operating system kernel, or perhaps a ROM image file. |
74 |
.Pp |
.Pp |
102 |
.It Fl E Ar t |
.It Fl E Ar t |
103 |
Try to emulate machine type |
Try to emulate machine type |
104 |
.Ar "t". |
.Ar "t". |
105 |
|
This option is not always needed, if the |
106 |
|
.Fl e |
107 |
|
option uniquely selects a machine. |
108 |
(Use |
(Use |
109 |
.Fl H |
.Fl H |
110 |
to get a list of types.) |
to get a list of types.) |
118 |
.Pp |
.Pp |
119 |
Other options: |
Other options: |
120 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
121 |
|
.It Fl A |
122 |
|
Disable load/store alignment checks in some cases. This might give a small |
123 |
|
increase in performance, but the emulator will not run correctly if the |
124 |
|
emulated code actually tries to do unaligned loads or stores. |
125 |
.It Fl B |
.It Fl B |
126 |
Disable dynamic binary translation completely. By default, bintrans |
Disable dynamic binary translation. By default, bintrans |
127 |
will be turned on if the host architecture supports it. |
will be turned on if the host+target architecture combination is |
128 |
However, in this release (0.3.X), there is no new bintrans system. |
supported. |
|
If you want to enable binary translation, use |
|
|
.Fl "b". |
|
|
.It Fl b |
|
|
Use the OLD binary translation subsystem. (Alpha and i386 hosts only.) |
|
129 |
.It Fl C Ar x |
.It Fl C Ar x |
130 |
Try to emulate a specific CPU type, |
Try to emulate a specific CPU type, |
131 |
.Ar "x". |
.Ar "x". |
164 |
Force a specific ID number. |
Force a specific ID number. |
165 |
.El |
.El |
166 |
.Pp |
.Pp |
167 |
Unless otherwise specified, filenames ending with ".iso" are assumed to be |
Unless otherwise specified, filenames ending with ".iso" or ".cdr" are |
168 |
CDROM images. Most others are assumed to be disks. Depending on which |
assumed to be CDROM images. Most others are assumed to be disks. Depending |
169 |
machine is being emulated, the default for disks can be either SCSI or |
on which machine is being emulated, the default for disks can be either |
170 |
IDE. Some disk images that are very small are assumed to be floppy disks. |
SCSI or IDE. Some disk images that are very small are assumed to be floppy |
171 |
(If you are not happy with the way a disk image is detected, then you need |
disks. (If you are not happy with the way a disk image is detected, then |
172 |
to use explicit prefixes to force a specific type.) |
you need to use explicit prefixes to force a specific type.) |
173 |
.Pp |
.Pp |
174 |
For floppies, the gH;S; prefix is ignored. Instead, the number of |
For floppies, the gH;S; prefix is ignored. Instead, the number of |
175 |
heads and cylinders are assumed to be 2 and 80, respectively, and the |
heads and cylinders are assumed to be 2 and 80, respectively, and the |
188 |
.It Fl j Ar n |
.It Fl j Ar n |
189 |
Set the name of the kernel to |
Set the name of the kernel to |
190 |
.Ar "n". |
.Ar "n". |
191 |
When booting from an ISO9660 filesystem, the kernel will try to boot from |
When booting from an ISO9660 filesystem, the emulator will try to boot |
192 |
this file. (In some emulation modes, eg. DECstation, this name is passed |
using this file. (In some emulation modes, eg. DECstation, this name is passed |
193 |
along to the boot program. Useful names are "bsd" for OpenBSD/pmax, |
along to the boot program. Useful names are "bsd" for OpenBSD/pmax, |
194 |
or "vmunix" for Ultrix.) |
or "vmunix" for Ultrix.) |
195 |
.It Fl M Ar m |
.It Fl M Ar m |
310 |
distribution. |
distribution. |
311 |
.Sh EXAMPLES |
.Sh EXAMPLES |
312 |
The following command will start NetBSD/pmax on an emulated DECstation |
The following command will start NetBSD/pmax on an emulated DECstation |
313 |
5000/200 (3MAX), with the old bintrans system enabled: |
5000/200 (3MAX): |
314 |
.Pp |
.Pp |
315 |
.Dl "gxemul -E dec -e 3max -b -d netbsddisk.img" |
.Dl "gxemul -e 3max -d nbsd_pmax.img" |
316 |
.Pp |
.Pp |
317 |
netbsddisk.img should be a raw disk image containing a bootable |
nbsd_pmax.img should be a raw disk image containing a bootable |
318 |
NetBSD/pmax filesystem. |
NetBSD/pmax filesystem. |
319 |
.Pp |
.Pp |
320 |
The following command will start an emulation session based on settings in |
The following command will start an emulation session based on settings in |
338 |
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 |
339 |
file in the |
file in the |
340 |
.Nm |
.Nm |
341 |
source distribution, some are indirectly mentioned in the TODO file. |
source distribution, some are indirectly mentioned in the TODO file, |
342 |
|
and some are mentioned in the source code itself. |
343 |
|
.Pp |
344 |
|
The binary translation subsystem is really terrible, but it is less |
345 |
|
terrible than running without it. |
346 |
.Pp |
.Pp |
347 |
There is no new bintrans system in this release, so you will need to add |
Userland (syscall-only) emulation doesn't really work yet. |
|
.Fl b |
|
|
to select the old bintrans system, if you want speed. |
|
348 |
.Pp |
.Pp |
349 |
.Nm |
.Nm |
350 |
does not simulate individual pipe-line stages or penalties caused by |
does not simulate individual pipe-line stages or penalties caused by |
351 |
branch-prediction misses, so it cannot be used for accurate performance |
branch-prediction misses or cache misses, so it cannot be used for |
352 |
measurement. |
accurate simulation of any actual real-world processor. |
353 |
.Pp |
.Pp |
354 |
.Nm |
.Nm |
355 |
is not timing-accurate. |
is not timing-accurate. |