/[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 16 by dpavlin, Mon Oct 8 16:19:01 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.34 2005/10/11 03:53:58 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  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
# Line 78  from SGI. Use Line 83  from SGI. Use
83  .Fl H  .Fl H
84  to get a list of available emulation modes.  to get a list of available emulation modes.
85  .Pp  .Pp
86  (There is an exception to the normal invocation usage mentioned above;  There are two exceptions to the normal invocation usage mentioned above.
87  if you want to use the DECstation emulation mode, and have a bootable  The first is for DECstation emulation: if you have a bootable
88  DECstation harddisk or CDROM image, then just supplying the diskimage via  DECstation harddisk or CDROM image, then just supplying the diskimage via
89  the  the
90  .Fl d  .Fl d
91  option is sufficient. The filename of the kernel can then be  option is sufficient. (The filename of the kernel can then be
92  skipped, as the emulator runs the bootblocks from the diskimage directly and  skipped, as the emulator runs the bootblocks from the diskimage directly and
93  doesn't need the kernel as a separate file.)  doesn't need the kernel as a separate file.)
94    The second is if you supply an ISO9660 CDROM disk image. You may then use
95    the
96    .Fl j
97    option to indicate which file on the CDROM filesystem that should be
98    loaded into emulated memory.
99  .Pp  .Pp
100  Machine selection options:  Machine selection options:
101  .Bl -tag -width Ds  .Bl -tag -width Ds
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.)
# Line 105  Use this together with Line 118  Use this together with
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. (This option
125    is only meaningful when emulating MIPS CPUs, when the host architecture is
126    Alpha or i386, and binary translation is enabled.)
127  .It Fl B  .It Fl B
128  Disable dynamic binary translation completely. By default, bintrans  Disable dynamic binary translation. By default, bintrans
129  will be turned on if the host architecture supports it.  will be turned on if the host+target architecture combination is
130  However, in this release (0.3.1), there is no new bintrans system.  supported. Currently, the only supported target architecture for bintrans
131  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.)  
132  .It Fl C Ar x  .It Fl C Ar x
133  Try to emulate a specific CPU type,  Try to emulate a specific CPU type,
134  .Ar "x".  .Ar "x".
# Line 126  Add Line 142  Add
142  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
143  colon (":") as a prefix to  colon (":") as a prefix to
144  .Ar "name",  .Ar "name",
145  you can modify the disk image's behaviour. Available modifiers are:  you can modify the way the disk image is treated. Available modifiers are:
146  .Bl -tag -width Ds  .Bl -tag -width Ds
147  .It b  .It b
148  Specifies that this is a boot device.  Specifies that this is a boot device.
149  .It c  .It c
150  CD-ROM (instead of a normal SCSI DISK).  CD-ROM.
151  .It d  .It d
152  SCSI DISK (this is the default).  DISK (this is the default).
153    .It f
154    FLOPPY.
155    .It gH;S;
156    Override the default geometry; use H heads and S sectors-per-track.
157    (The number of cylinders is calculated automatically.)
158  .It i  .It i
159  IDE (instead of SCSI).  IDE.
160  .It r  .It r
161  Read-only (don't allow changes to be written to the file).  Read-only (don't allow changes to be written to the file).
162    .It s
163    SCSI (this is the default for most machine types).
164  .It t  .It t
165  SCSI tape.  Tape.
166  .It 0-7  .It 0-7
167  Force a specific SCSI ID number.  Force a specific ID number.
168  .El  .El
169  .Pp  .Pp
170  Filenames ending with ".iso" are assumed to be CDROM images, all others  Unless otherwise specified, filenames ending with ".iso" or ".cdr" are
171  are assumed to be normal SCSI disks.  assumed to be CDROM images. Most others are assumed to be disks. Depending
172    on which machine is being emulated, the default for disks can be either
173    SCSI or IDE. Some disk images that are very small are assumed to be floppy
174    disks. (If you are not happy with the way a disk image is detected, then
175    you need to use explicit prefixes to force a specific type.)
176    .Pp
177    For floppies, the gH;S; prefix is ignored. Instead, the number of
178    heads and cylinders are assumed to be 2 and 80, respectively, and the
179    number of sectors per track is calculated automatically. (This works for
180    720KB, 1.2MB, 1.44MB, and 2.88MB floppies.)
181  .It Fl I Ar x  .It Fl I Ar x
182  Emulate clock interrupts at  Emulate clock interrupts at
183  .Ar x  .Ar x
# Line 159  Disable some speed tricks. Line 191  Disable some speed tricks.
191  .It Fl j Ar n  .It Fl j Ar n
192  Set the name of the kernel to  Set the name of the kernel to
193  .Ar "n".  .Ar "n".
194  Useful names are "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix.  When booting from an ISO9660 filesystem, the emulator will try to boot
195  ("netbsd" is usually the default value.)  using this file. (In some emulation modes, eg. DECstation, this name is passed
196    along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
197    or "vmunix" for Ultrix.)
198  .It Fl M Ar m  .It Fl M Ar m
199  Emulate  Emulate
200  .Ar m  .Ar m
# Line 178  Set nr of CPUs (for SMP experiments). Line 212  Set nr of CPUs (for SMP experiments).
212  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
213  present (for DECstation, SGI, and ARC emulation).  present (for DECstation, SGI, and ARC emulation).
214  .It Fl o Ar arg  .It Fl o Ar arg
215  Set the boot argument (for DEC, ARC, or SGI emulation).  Set the boot argument (mostly useful for DEC, ARC, or SGI emulation).
216  Default  Default
217  .Ar arg  .Ar arg
218  for DEC is '-a', for ARC '-aN'.  for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A".
219  .It Fl p Ar pc  .It Fl p Ar pc
220  Add a breakpoint (remember to use the '0x' prefix for hex).  Add a breakpoint. (Remember to use the "0x" prefix for hex.)
221  .It Fl Q  .It Fl Q
222  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
223  images from real machines.  images from real machines.
# Line 237  emulation. Line 271  emulation.
271  General options:  General options:
272  .Bl -tag -width Ds  .Bl -tag -width Ds
273  .It Fl D  .It Fl D
274  Guarantee fully deterministic behaviour. Normally, the emulator calls  Guarantee fully deterministic behavior. Normally, the emulator calls
275  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
276  .Fl D  .Fl D
277  option is used, the srandom() call is skipped, which should cause two  option is used, the srandom() call is skipped, which should cause two
278  subsequent invokations of the emulator to be identical, if all other  subsequent invocations of the emulator to be identical, if all other
279  settings are identical. (If this option is used, then  settings are identical and no user input is taking place. (If this option
280    is used, then
281  .Fl I  .Fl I
282  must also be used.)  must also be used.)
283  .It Fl H  .It Fl H
# Line 278  subdirectory of the Line 313  subdirectory of the
313  distribution.  distribution.
314  .Sh EXAMPLES  .Sh EXAMPLES
315  The following command will start NetBSD/pmax on an emulated DECstation  The following command will start NetBSD/pmax on an emulated DECstation
316  5000/200 (3MAX), with the old bintrans system enabled:  5000/200 (3MAX):
317  .Pp  .Pp
318  .Dl "gxemul -E dec -e 3max -b -d netbsddisk.img"  .Dl "gxemul -e 3max -d nbsd_pmax.img"
319  .Pp  .Pp
320  netbsddisk.img should be a raw disk image containing a bootable  nbsd_pmax.img should be a raw disk image containing a bootable
321  NetBSD/pmax filesystem.  NetBSD/pmax filesystem.
322  .Pp  .Pp
323  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 341  Please read the documentation for more d
341  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
342  file in the  file in the
343  .Nm  .Nm
344  source distribution, some are indirectly mentioned in the TODO file.  source distribution, some are indirectly mentioned in the TODO file,
345    and some are mentioned in the source code itself.
346    .Pp
347    The binary translation subsystem is really terrible, but it is less
348    terrible than running without it.
349    .Pp
350    Userland (syscall-only) emulation doesn't really work yet.
351  .Pp  .Pp
352  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
353  need to add  documentation sometimes only reflect the way things work with MIPS
354  .Fl b  emulation, and it is incorrect when applied to e.g. ARM emulation.
 to select the old bintrans system, if you want speed.  
355  .Pp  .Pp
356  .Nm  .Nm
357  does not simulate individual pipe-line stages or penalties caused by  does not simulate individual pipe-line stages or penalties caused by
358  branch-prediction misses, so it cannot be used for accurate performance  branch-prediction misses or cache misses, so it cannot be used for
359  measurement.  accurate simulation of any actual real-world processor.
360    .Pp
361    .Nm
362    is not timing-accurate.
363  .Sh AUTHOR  .Sh AUTHOR
364  Anders Gavare <anders@gavare.se>  Anders Gavare <anders@gavare.se>
365  .Pp  .Pp
Legend:
Removed from v.2  
changed lines
  Added in v.16
  ViewVC Help
Powered by ViewVC 1.1.26