/[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 10 by dpavlin, Mon Oct 8 16:18:27 2007 UTC revision 16 by dpavlin, Mon Oct 8 16:19:01 2007 UTC
# Line 1  Line 1 
1  .\" $Id: gxemul.1,v 1.24 2005/06/26 10:05:02 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 JUNE 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 to  is an experimental instruction-level machine emulator. Several
51  run binary code for (among others) MIPS-based machines, regardless of host  emulation modes are available. In some modes, processors and surrounding
52  platform. Several emulation modes are available. For some modes,  hardware components are emulated well enough to let unmodified operating
53  processors and surrounding hardware components are emulated well enough to  systems (e.g. NetBSD) run as if they were running on a real machine.
54  let unmodified operating systems (e.g. NetBSD) run as if they were running  .Pp
55  on a 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 97  Machine selection options: Line 102  Machine selection options:
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 110  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. By default, bintrans  Disable dynamic binary translation. By default, bintrans
129  will be turned on if the host+target architecture combination is  will be turned on if the host+target architecture combination is
130  supported.  supported. Currently, the only supported target architecture for bintrans
131    is MIPS, and the supported host architectures are Alpha and i386.
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 152  Tape. Line 167  Tape.
167  Force a specific ID number.  Force a specific ID number.
168  .El  .El
169  .Pp  .Pp
170  Unless otherwise specified, filenames ending with ".iso" are assumed to be  Unless otherwise specified, filenames ending with ".iso" or ".cdr" are
171  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
172  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
173  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
174  (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
175  to use explicit prefixes to force a specific type.)  you need to use explicit prefixes to force a specific type.)
176  .Pp  .Pp
177  For floppies, the gH;S; prefix is ignored. Instead, the number of  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  heads and cylinders are assumed to be 2 and 80, respectively, and the
# Line 197  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
# Line 300  distribution. Line 315  distribution.
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):  5000/200 (3MAX):
317  .Pp  .Pp
318  .Dl "gxemul -E dec -e 3max -d nbsd_pmax.img"  .Dl "gxemul -e 3max -d nbsd_pmax.img"
319  .Pp  .Pp
320  nbsd_pmax.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.
# Line 326  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  .Pp
347  The binary translation subsystem is really terrible, but it is less  The binary translation subsystem is really terrible, but it is less
348  terrible than running without it.  terrible than running without it.
349  .Pp  .Pp
350    Userland (syscall-only) emulation doesn't really work yet.
351    .Pp
352    Emulation of MIPS CPUs is done differently from other emulation modes; the
353    documentation sometimes only reflect the way things work with MIPS
354    emulation, and it is incorrect when applied to e.g. ARM emulation.
355    .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 or cache misses, so it cannot be used for  branch-prediction misses or cache misses, so it cannot be used for
359  accurate performance measurement.  accurate simulation of any actual real-world processor.
360  .Pp  .Pp
361  .Nm  .Nm
362  is not timing-accurate.  is not timing-accurate.
Legend:
Removed from v.10  
changed lines
  Added in v.16
  ViewVC Help
Powered by ViewVC 1.1.26