/[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 6 by dpavlin, Mon Oct 8 16:18:11 2007 UTC revision 20 by dpavlin, Mon Oct 8 16:19:23 2007 UTC
# Line 1  Line 1 
1  .\" $Id: gxemul.1,v 1.21 2005/06/03 23:14:52 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  .\"  .\"
# 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 JUNE 2005  .Dd NOVEMBER 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 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
# Line 97  Machine selection options: Line 114  Machine selection options:
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.)
# Line 110  Use this together with Line 130  Use this together with
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.X), 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".
# Line 156  Tape. Line 179  Tape.
179  Force a specific ID number.  Force a specific ID number.
180  .El  .El
181  .Pp  .Pp
182  Unless otherwise specified, filenames ending with ".iso" are assumed to be  Unless otherwise specified, filenames ending with ".iso" or ".cdr" are
183  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
184  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
185  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
186  (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
187  to use explicit prefixes to force a specific type.)  you need to use explicit prefixes to force a specific type.)
188  .Pp  .Pp
189  For floppies, the gH;S; prefix is ignored. Instead, the number of  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  heads and cylinders are assumed to be 2 and 80, respectively, and the
# Line 176  This disables automatic clock adjustment Line 199  This disables automatic clock adjustment
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  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
209  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
210  along to the boot program. Useful names are "bsd" for OpenBSD/pmax,  along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
211  or "vmunix" for Ultrix.)  or "vmunix" for Ultrix.)
212  .It Fl M Ar m  .It Fl M Ar m
# Line 201  Set nr of CPUs (for SMP experiments). Line 226  Set nr of CPUs (for SMP experiments).
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
# Line 233  Scale down framebuffer windows by Line 258  Scale down framebuffer windows by
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
# Line 282  Force the single-step debugger to be ent Line 317  Force the single-step debugger to be ent
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
# Line 302  subdirectory of the Line 339  subdirectory of the
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
# Line 330  Please read the documentation for more d Line 367  Please read the documentation for more d
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
376    Userland (syscall-only) emulation doesn't really work yet.
377  .Pp  .Pp
378  There is no new bintrans system in this release, so you will need to add  Emulation of MIPS CPUs is done differently from other emulation modes; the
379  .Fl b  documentation sometimes only reflects the way things work with MIPS
380  to select the old bintrans system, if you want speed.  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  .Pp
387  .Nm  .Nm
388  is not timing-accurate.  is not timing-accurate.
Legend:
Removed from v.6  
changed lines
  Added in v.20
  ViewVC Help
Powered by ViewVC 1.1.26