/[gxemul]/trunk/man/gxemul.1
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Diff of /trunk/man/gxemul.1

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2 by dpavlin, Mon Oct 8 16:17:48 2007 UTC revision 18 by dpavlin, Mon Oct 8 16:19:11 2007 UTC
# Line 1  Line 1 
1  .\" $Id: gxemul.1,v 1.12 2005/04/07 16:00:24 debug Exp $  .\" $Id: gxemul.1,v 1.35 2005/10/27 14:01:11 debug Exp $
2  .\"  .\"
3  .\" Copyright (C) 2004-2005  Anders Gavare.  All rights reserved.  .\" Copyright (C) 2004-2005  Anders Gavare.  All rights reserved.
4  .\"  .\"
# Line 29  Line 29 
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 OCTOBER 2005
33  .Dt GXEMUL 1  .Dt GXEMUL 1
34  .Os  .Os
35  .Sh NAME  .Sh NAME
# Line 41  Line 41 
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  MIPS processors are emulated either using a simple type of binary
59  they can be read from a configuration file. When emulating a userland  translator (on Alpha and i386 hosts), or using traditional slow
60  environment (syscall-only emulation, not emulating complete machines),  interpretation (all other hosts, including amd64 machines running in
61  then the program name and its argument should be given on the command  64-bit mode).
62  line.  .Pp
63    Non-MIPS processors (e.g. ARM) are emulated using a newer dynamic
64    translation system (called dyntrans in the rest of this man page);
65    dyntrans does not require any host-specific code, so it should work on any
66    platform. Performance is somewhere between binary translation and
67    traditional interpretation.
68    .Pp
69    There are three ways to invoke the emulator:
70    .Pp
71    1. When emulating a complete machine, configuration options can be entered
72    directly on the command line.
73    .Pp
74    2. Options can be read from a configuration file.
75    .Pp
76    3. When emulating a userland environment (syscall-only emulation, not
77    emulating complete machines), then the program name and its argument
78    should be given on the command line. (This mode doesn't really work yet.)
79  .Pp  .Pp
80  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
81  command line. The most important thing you need to supply is the  command line. The most important thing you need to supply is the
82  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,
83  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
84  might be an operating system kernel, or perhaps a ROM image file.  might be an operating system kernel, or perhaps a ROM image file.
85  .Pp  .Pp
# Line 78  from SGI. Use Line 94  from SGI. Use
94  .Fl H  .Fl H
95  to get a list of available emulation modes.  to get a list of available emulation modes.
96  .Pp  .Pp
97  (There is an exception to the normal invocation usage mentioned above;  There are two exceptions to the normal invocation usage mentioned above.
98  if you want to use the DECstation emulation mode, and have a bootable  The first is for DECstation emulation: if you have a bootable
99  DECstation harddisk or CDROM image, then just supplying the diskimage via  DECstation harddisk or CDROM image, then just supplying the diskimage via
100  the  the
101  .Fl d  .Fl d
102  option is sufficient. The filename of the kernel can then be  option is sufficient. (The filename of the kernel can then be
103  skipped, as the emulator runs the bootblocks from the diskimage directly and  skipped, as the emulator runs the bootblocks from the diskimage directly and
104  doesn't need the kernel as a separate file.)  doesn't need the kernel as a separate file.)
105    The second is if you supply an ISO9660 CDROM disk image. You may then use
106    the
107    .Fl j
108    option to indicate which file on the CDROM filesystem that should be
109    loaded into emulated memory.
110  .Pp  .Pp
111  Machine selection options:  Machine selection options:
112  .Bl -tag -width Ds  .Bl -tag -width Ds
113  .It Fl E Ar t  .It Fl E Ar t
114  Try to emulate machine type  Try to emulate machine type
115  .Ar "t".  .Ar "t".
116    This option is not always needed, if the
117    .Fl e
118    option uniquely selects a machine.
119  (Use  (Use
120  .Fl H  .Fl H
121  to get a list of types.)  to get a list of types.)
# Line 105  Use this together with Line 129  Use this together with
129  .Pp  .Pp
130  Other options:  Other options:
131  .Bl -tag -width Ds  .Bl -tag -width Ds
132    .It Fl A
133    Disable load/store alignment checks in some cases. This might give a small
134    increase in performance, but the emulator will not run correctly if the
135    emulated code actually tries to do unaligned loads or stores. (This option
136    is only meaningful when emulating MIPS CPUs, when the host architecture is
137    Alpha or i386, and binary translation is enabled.)
138  .It Fl B  .It Fl B
139  Disable dynamic binary translation completely. By default, bintrans  Disable dynamic binary translation. By default, bintrans
140  will be turned on if the host architecture supports it.  will be turned on if the host+target architecture combination is
141  However, in this release (0.3.1), there is no new bintrans system.  supported. Currently, the only supported target architecture for bintrans
142  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.)  
143  .It Fl C Ar x  .It Fl C Ar x
144  Try to emulate a specific CPU type,  Try to emulate a specific CPU type,
145  .Ar "x".  .Ar "x".
# Line 126  Add Line 153  Add
153  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
154  colon (":") as a prefix to  colon (":") as a prefix to
155  .Ar "name",  .Ar "name",
156  you can modify the disk image's behaviour. Available modifiers are:  you can modify the way the disk image is treated. Available modifiers are:
157  .Bl -tag -width Ds  .Bl -tag -width Ds
158  .It b  .It b
159  Specifies that this is a boot device.  Specifies that this is a boot device.
160  .It c  .It c
161  CD-ROM (instead of a normal SCSI DISK).  CD-ROM.
162  .It d  .It d
163  SCSI DISK (this is the default).  DISK (this is the default).
164    .It f
165    FLOPPY.
166    .It gH;S;
167    Override the default geometry; use H heads and S sectors-per-track.
168    (The number of cylinders is calculated automatically.)
169  .It i  .It i
170  IDE (instead of SCSI).  IDE.
171  .It r  .It r
172  Read-only (don't allow changes to be written to the file).  Read-only (don't allow changes to be written to the file).
173    .It s
174    SCSI (this is the default for most machine types).
175  .It t  .It t
176  SCSI tape.  Tape.
177  .It 0-7  .It 0-7
178  Force a specific SCSI ID number.  Force a specific ID number.
179  .El  .El
180  .Pp  .Pp
181  Filenames ending with ".iso" are assumed to be CDROM images, all others  Unless otherwise specified, filenames ending with ".iso" or ".cdr" are
182  are assumed to be normal SCSI disks.  assumed to be CDROM images. Most others are assumed to be disks. Depending
183    on which machine is being emulated, the default for disks can be either
184    SCSI or IDE. Some disk images that are very small are assumed to be floppy
185    disks. (If you are not happy with the way a disk image is detected, then
186    you need to use explicit prefixes to force a specific type.)
187    .Pp
188    For floppies, the gH;S; prefix is ignored. Instead, the number of
189    heads and cylinders are assumed to be 2 and 80, respectively, and the
190    number of sectors per track is calculated automatically. (This works for
191    720KB, 1.2MB, 1.44MB, and 2.88MB floppies.)
192  .It Fl I Ar x  .It Fl I Ar x
193  Emulate clock interrupts at  Emulate clock interrupts at
194  .Ar x  .Ar x
# Line 155  This disables automatic clock adjustment Line 198  This disables automatic clock adjustment
198  .It Fl i  .It Fl i
199  Display each instruction as it is being executed.  Display each instruction as it is being executed.
200  .It Fl J  .It Fl J
201  Disable some speed tricks.  Disable some speed tricks. For MIPS emulation, these are mostly
202    timing-related. For non-MIPS emulation (i.e. those modes using dyntrans),
203    this flag disables the use of "instruction combinations".
204  .It Fl j Ar n  .It Fl j Ar n
205  Set the name of the kernel to  Set the name of the kernel to
206  .Ar "n".  .Ar "n".
207  Useful names are "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix.  When booting from an ISO9660 filesystem, the emulator will try to boot
208  ("netbsd" is usually the default value.)  using this file. (In some emulation modes, eg. DECstation, this name is passed
209    along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
210    or "vmunix" for Ultrix.)
211  .It Fl M Ar m  .It Fl M Ar m
212  Emulate  Emulate
213  .Ar m  .Ar m
# Line 178  Set nr of CPUs (for SMP experiments). Line 225  Set nr of CPUs (for SMP experiments).
225  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
226  present (for DECstation, SGI, and ARC emulation).  present (for DECstation, SGI, and ARC emulation).
227  .It Fl o Ar arg  .It Fl o Ar arg
228  Set the boot argument (for DEC, ARC, or SGI emulation).  Set the boot argument (mostly useful for DEC, ARC, or SGI emulation).
229  Default  Default
230  .Ar arg  .Ar arg
231  for DEC is '-a', for ARC '-aN'.  for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A".
232  .It Fl p Ar pc  .It Fl p Ar pc
233  Add a breakpoint (remember to use the '0x' prefix for hex).  Add a breakpoint. (Remember to use the "0x" prefix for hex.)
234  .It Fl Q  .It Fl Q
235  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
236  images from real machines.  images from real machines.
# Line 237  emulation. Line 284  emulation.
284  General options:  General options:
285  .Bl -tag -width Ds  .Bl -tag -width Ds
286  .It Fl D  .It Fl D
287  Guarantee fully deterministic behaviour. Normally, the emulator calls  Guarantee fully deterministic behavior. Normally, the emulator calls
288  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
289  .Fl D  .Fl D
290  option is used, the srandom() call is skipped, which should cause two  option is used, the srandom() call is skipped, which should cause two
291  subsequent invokations of the emulator to be identical, if all other  subsequent invocations of the emulator to be identical, if all other
292  settings are identical. (If this option is used, then  settings are identical and no user input is taking place. (If this option
293    is used, then
294  .Fl I  .Fl I
295  must also be used.)  must also be used.)
296  .It Fl H  .It Fl H
# Line 258  Force the single-step debugger to be ent Line 306  Force the single-step debugger to be ent
306  .It Fl q  .It Fl q
307  Quiet mode; this suppresses startup messages.  Quiet mode; this suppresses startup messages.
308  .It Fl s  .It Fl s
309  Show opcode usage statistics after the simulation.  For MIPS emulation: Show opcode usage statistics after the simulation.
310    For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file at
311    regular intervals of which physical addresses that were executed.
312  .It Fl V  .It Fl V
313  Start up in the single-step debugger, paused.  Start up in the single-step debugger, paused.
314  .It Fl v  .It Fl v
# Line 278  subdirectory of the Line 328  subdirectory of the
328  distribution.  distribution.
329  .Sh EXAMPLES  .Sh EXAMPLES
330  The following command will start NetBSD/pmax on an emulated DECstation  The following command will start NetBSD/pmax on an emulated DECstation
331  5000/200 (3MAX), with the old bintrans system enabled:  5000/200 (3MAX):
332  .Pp  .Pp
333  .Dl "gxemul -E dec -e 3max -b -d netbsddisk.img"  .Dl "gxemul -e 3max -d nbsd_pmax.img"
334  .Pp  .Pp
335  netbsddisk.img should be a raw disk image containing a bootable  nbsd_pmax.img should be a raw disk image containing a bootable
336  NetBSD/pmax filesystem.  NetBSD/pmax filesystem.
337  .Pp  .Pp
338  The following command will start an emulation session based on settings in  The following command will start an emulation session based on settings in
# Line 306  Please read the documentation for more d Line 356  Please read the documentation for more d
356  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
357  file in the  file in the
358  .Nm  .Nm
359  source distribution, some are indirectly mentioned in the TODO file.  source distribution, some are indirectly mentioned in the TODO file,
360    and some are mentioned in the source code itself.
361    .Pp
362    The binary translation subsystem is really terrible, but it is less
363    terrible than running without it.
364    .Pp
365    Userland (syscall-only) emulation doesn't really work yet.
366  .Pp  .Pp
367  There is no new bintrans system in this release (0.3.1), so you will  Emulation of MIPS CPUs is done differently from other emulation modes; the
368  need to add  documentation sometimes only reflect the way things work with MIPS
369  .Fl b  emulation, and it is incorrect when applied to e.g. ARM emulation.
 to select the old bintrans system, if you want speed.  
370  .Pp  .Pp
371  .Nm  .Nm
372  does not simulate individual pipe-line stages or penalties caused by  does not simulate individual pipe-line stages or penalties caused by
373  branch-prediction misses, so it cannot be used for accurate performance  branch-prediction misses or cache misses, so it cannot be used for
374  measurement.  accurate simulation of any actual real-world processor.
375    .Pp
376    .Nm
377    is not timing-accurate.
378  .Sh AUTHOR  .Sh AUTHOR
379  Anders Gavare <anders@gavare.se>  Anders Gavare <anders@gavare.se>
380  .Pp  .Pp
Legend:
Removed from v.2  
changed lines
  Added in v.18
  ViewVC Help
Powered by ViewVC 1.1.26