/[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 4 by dpavlin, Mon Oct 8 16:18:00 2007 UTC revision 22 by dpavlin, Mon Oct 8 16:19:37 2007 UTC
# Line 1  Line 1 
1  .\" $Id: gxemul.1,v 1.14 2005/04/16 02:38:21 debug Exp $  .\" $Id: gxemul.1,v 1.49 2006/02/18 14:02:20 debug Exp $
2  .\"  .\"
3  .\" Copyright (C) 2004-2005  Anders Gavare.  All rights reserved.  .\" Copyright (C) 2004-2006  Anders Gavare.  All rights reserved.
4  .\"  .\"
5  .\" Redistribution and use in source and binary forms, with or without  .\" Redistribution and use in source and binary forms, with or without
6  .\" modification, are permitted provided that the following conditions are met:  .\" modification, are permitted provided that the following conditions are met:
# 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 FEBRUARY 2006
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 using either a simple binary translation
60  then the program name and its argument should be given on the command  layer (recompilation into native code), which is used on Alpha and i386
61  line.  hosts, or by traditional interpretation (very very slow, but works on any
62    host platform).
63    .Pp
64    Non-MIPS processors are emulated using a newer dynamic translation
65    system (called dyntrans in the rest of this man page). Performance is
66    somewhere between traditional interpretation and recompilation into native
67    code. However, the dynamic translation system used in GXemul does NOT
68    generate native code, and thus doesn't require platform-specific
69    back-ends. In plain English, this means that the dyntrans system works on
70    any host platform.
71    .Pp
72    There are three ways to invoke the emulator:
73    .Pp
74    1. When emulating a complete machine, configuration options can be entered
75    directly on the command line.
76    .Pp
77    2. Options can be read from a configuration file.
78    .Pp
79    3. When emulating a userland environment (syscall-only emulation, not
80    emulating complete machines), then the program name and its argument
81    should be given on the command line. (This mode doesn't really work yet.)
82  .Pp  .Pp
83  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
84  command line. The most important thing you need to supply is the  command line. The most important thing you need to supply is the
85  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,
86  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
87  might be an operating system kernel, or perhaps a ROM image file.  might be an operating system kernel, or perhaps a ROM image file.
88  .Pp  .Pp
# Line 78  from SGI. Use Line 97  from SGI. Use
97  .Fl H  .Fl H
98  to get a list of available emulation modes.  to get a list of available emulation modes.
99  .Pp  .Pp
100  (There is an exception to the normal invocation usage mentioned above;  There are two exceptions to the normal invocation usage mentioned above.
101  if you want to use the DECstation emulation mode, and have a bootable  The first is for DECstation emulation: if you have a bootable
102  DECstation harddisk or CDROM image, then just supplying the diskimage via  DECstation harddisk or CDROM image, then just supplying the diskimage via
103  the  the
104  .Fl d  .Fl d
105  option is sufficient. The filename of the kernel can then be  option is sufficient. (The filename of the kernel can then be
106  skipped, as the emulator runs the bootblocks from the diskimage directly and  skipped, as the emulator runs the bootblocks from the diskimage directly and
107  doesn't need the kernel as a separate file.)  doesn't need the kernel as a separate file.)
108    The second is if you supply an ISO9660 CDROM disk image. You may then use
109    the
110    .Fl j
111    option to indicate which file on the CDROM filesystem that should be
112    loaded into emulated memory.
113  .Pp  .Pp
114  Machine selection options:  Machine selection options:
115  .Bl -tag -width Ds  .Bl -tag -width Ds
116  .It Fl E Ar t  .It Fl E Ar t
117  Try to emulate machine type  Try to emulate machine type
118  .Ar "t".  .Ar "t".
119    This option is not always needed, if the
120    .Fl e
121    option uniquely selects a machine.
122  (Use  (Use
123  .Fl H  .Fl H
124  to get a list of types.)  to get a list of types.)
# Line 105  Use this together with Line 132  Use this together with
132  .Pp  .Pp
133  Other options:  Other options:
134  .Bl -tag -width Ds  .Bl -tag -width Ds
135    .It Fl A
136    Disable load/store alignment checks in some cases. This might give a small
137    increase in performance, but the emulator will not run correctly if the
138    emulated code actually tries to do unaligned loads or stores. (This option
139    is only meaningful when emulating MIPS CPUs, when the host architecture is
140    Alpha or i386, and binary translation is enabled.)
141  .It Fl B  .It Fl B
142  Disable dynamic binary translation completely. By default, bintrans  Disable native translation backends. By default, translation backends are
143  will be turned on if the host architecture supports it.  used if the host+target architecture combination is supported. Currently,
144  However, in this release (0.3.1), there is no new bintrans system.  the only supported host architecture for the old bintrans system (used
145  If you want to enable binary translation, use  when emulating MIPS processors) are Alpha and i386. The old bintrans
146  .Fl "b".  system will hopefully be removed some day.
 .It Fl b  
 Use the OLD binary translation subsystem. (Alpha and i386 hosts only.)  
147  .It Fl C Ar x  .It Fl C Ar x
148  Try to emulate a specific CPU type,  Try to emulate a specific CPU type,
149  .Ar "x".  .Ar "x".
# Line 126  Add Line 157  Add
157  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
158  colon (":") as a prefix to  colon (":") as a prefix to
159  .Ar "name",  .Ar "name",
160  you can modify the disk image's behaviour. Available modifiers are:  you can modify the way the disk image is treated. Available modifiers are:
161  .Bl -tag -width Ds  .Bl -tag -width Ds
162  .It b  .It b
163  Specifies that this is a boot device.  Specifies that this is a boot device.
# Line 136  CD-ROM. Line 167  CD-ROM.
167  DISK (this is the default).  DISK (this is the default).
168  .It f  .It f
169  FLOPPY.  FLOPPY.
170    .It gH;S;
171    Override the default geometry; use H heads and S sectors-per-track.
172    (The number of cylinders is calculated automatically.)
173  .It i  .It i
174  IDE.  IDE. (This is the default for most machine types.)
175  .It r  .It r
176  Read-only (don't allow changes to be written to the file).  Read-only (don't allow changes to be written to the file).
177  .It s  .It s
178  SCSI (this is the default for most machine types).  SCSI.
179  .It t  .It t
180  Tape.  Tape.
181  .It 0-7  .It 0-7
182  Force a specific SCSI ID number.  Force a specific ID number.
183  .El  .El
184  .Pp  .Pp
185  Filenames ending with ".iso" are assumed to be CDROM images. Files with a  Unless otherwise specified, filenames ending with ".iso" or ".cdr" are
186  size of exactly 1.44 MB are assumed to be floppy images. All others  assumed to be CDROM images. Most others are assumed to be disks. Depending
187  are assumed to be disks.  on which machine is being emulated, the default for disks can be either
188    SCSI or IDE. Some disk images that are very small are assumed to be floppy
189    disks. (If you are not happy with the way a disk image is detected, then
190    you need to use explicit prefixes to force a specific type.)
191    .Pp
192    For floppies, the gH;S; prefix is ignored. Instead, the number of
193    heads and cylinders are assumed to be 2 and 80, respectively, and the
194    number of sectors per track is calculated automatically. (This works for
195    720KB, 1.2MB, 1.44MB, and 2.88MB floppies.)
196  .It Fl I Ar x  .It Fl I Ar x
197  Emulate clock interrupts at  Emulate clock interrupts at
198  .Ar x  .Ar x
# Line 160  This disables automatic clock adjustment Line 202  This disables automatic clock adjustment
202  .It Fl i  .It Fl i
203  Display each instruction as it is being executed.  Display each instruction as it is being executed.
204  .It Fl J  .It Fl J
205  Disable some speed tricks.  Disable some speed tricks. For MIPS emulation, these are mostly
206    timing-related. For non-MIPS emulation (i.e. modes using dyntrans),
207    this flag disables the use of "instruction combinations".
208  .It Fl j Ar n  .It Fl j Ar n
209  Set the name of the kernel to  Set the name of the kernel to
210  .Ar "n".  .Ar "n".
211  Useful names are "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix.  When booting from an ISO9660 filesystem, the emulator will try to boot
212  ("netbsd" is usually the default value.)  using this file. (In some emulation modes, eg. DECstation, this name is passed
213    along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
214    or "vmunix" for Ultrix.)
215  .It Fl M Ar m  .It Fl M Ar m
216  Emulate  Emulate
217  .Ar m  .Ar m
# Line 178  instructions (on any cpu). Line 224  instructions (on any cpu).
224  .It Fl N  .It Fl N
225  Display nr of instructions/second average, at regular intervals.  Display nr of instructions/second average, at regular intervals.
226  .It Fl n Ar nr  .It Fl n Ar nr
227  Set nr of CPUs (for SMP experiments).  Set nr of CPUs (for SMP experiments). Note: The emulator allocates quite a
228    lot of virtual memory for per-CPU translation tables. On 64-bit hosts,
229    this is normally not a problem. On 32-bit hosts, this can use up all
230    available virtual userspace memory. The solution is to either run the
231    emulator on a 64-bit host, or limit the number of emulated CPUs to a
232    reasonable number (say, less than 32).
233  .It Fl O  .It Fl O
234  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
235  present (for DECstation, SGI, and ARC emulation).  present (for DECstation, SGI, and ARC emulation).
236  .It Fl o Ar arg  .It Fl o Ar arg
237  Set the boot argument (for DEC, ARC, or SGI emulation).  Set the boot argument (mostly useful for DEC, ARC, or SGI emulation).
238  Default  Default
239  .Ar arg  .Ar arg
240  for DEC is '-a', for ARC '-aN'.  for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A".
241  .It Fl p Ar pc  .It Fl p Ar pc
242  Add a breakpoint (remember to use the '0x' prefix for hex).  Add a breakpoint. (Remember to use the "0x" prefix for hex.)
243  .It Fl Q  .It Fl Q
244  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
245  images from real machines.  images from real machines.
# Line 205  Show a trace tree of all function calls Line 256  Show a trace tree of all function calls
256  .It Fl U  .It Fl U
257  Enable slow_serial_interrupts_hack_for_linux.  Enable slow_serial_interrupts_hack_for_linux.
258  .It Fl X  .It Fl X
259  Use X11.  Use X11. This option enables graphical framebuffers.
260  .It Fl x  .It Fl x
261  Open up new xterms for emulated serial ports. (Default is to open up  Open up new xterms for emulated serial ports. The default behaviour is to
262  xterms when using configuration files, but not when starting an  open up xterms when using configuration files, or if X11 is enabled. When
263  emulation with settings directly on the command line.)  starting up a simple emulation session with settings directly on the
264    command line, and neither
265    .Fl X
266    nor
267    .Fl x
268    is used, then all output is confined to the terminal that
269    .Nm
270    started in.
271  .It Fl Y Ar n  .It Fl Y Ar n
272  Scale down framebuffer windows by  Scale down framebuffer windows by
273  .Ar n  .Ar n
274  x  x
275  .Ar n  .Ar n
276  times.  times. This option is useful when emulating a very large framebuffer, and
277    the actual display is of lower resolution. If
278    .Ar n
279    is negative, then there will be no scaledown, but emulation of certain
280    graphic controllers will be scaled up
281    by
282    .Ar -n
283    times instead. E.g. Using
284    .Ar -2
285    with VGA text mode emulation will result in 80x25 character cells rendered
286    in a 1280x800 window, instead of the normal resolution of 640x400.
287  .It Fl y Ar x  .It Fl y Ar x
288  Set max_random_cycles_per_chunk to  Set max_random_cycles_per_chunk to
289  .Ar x  .Ar x
# Line 241  emulation. Line 309  emulation.
309  .Pp  .Pp
310  General options:  General options:
311  .Bl -tag -width Ds  .Bl -tag -width Ds
312    .It Fl c Ar cmd
313    Add
314    .Ar cmd
315    as a command to run before starting the simulation. A similar effect can
316    be achieved by using the
317    .Fl V
318    option, and entering the commands manually.
319  .It Fl D  .It Fl D
320  Guarantee fully deterministic behaviour. Normally, the emulator calls  Guarantee fully deterministic behavior. Normally, the emulator calls
321  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
322  .Fl D  .Fl D
323  option is used, the srandom() call is skipped, which should cause two  option is used, the srandom() call is skipped, which should cause two
324  subsequent invokations of the emulator to be identical, if all other  subsequent invocations of the emulator to be identical, if all other
325  settings are identical. (If this option is used, then  settings are identical and no user input is taking place. (If this option
326    is used, then
327  .Fl I  .Fl I
328  must also be used.)  must also be used.)
329  .It Fl H  .It Fl H
# Line 263  Force the single-step debugger to be ent Line 339  Force the single-step debugger to be ent
339  .It Fl q  .It Fl q
340  Quiet mode; this suppresses startup messages.  Quiet mode; this suppresses startup messages.
341  .It Fl s  .It Fl s
342  Show opcode usage statistics after the simulation.  For MIPS emulation: Show opcode usage statistics after the simulation.
343    For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file at
344    regular intervals of which physical addresses that were executed.
345  .It Fl V  .It Fl V
346  Start up in the single-step debugger, paused.  Start up in the single-step debugger, paused.
347  .It Fl v  .It Fl v
348  Verbose debug messages.  Increase verbosity (show more debug messages). This option can be used
349    multiple times.
350  .El  .El
351  .Pp  .Pp
352  Configuration file startup:  Configuration file startup:
# Line 283  subdirectory of the Line 362  subdirectory of the
362  distribution.  distribution.
363  .Sh EXAMPLES  .Sh EXAMPLES
364  The following command will start NetBSD/pmax on an emulated DECstation  The following command will start NetBSD/pmax on an emulated DECstation
365  5000/200 (3MAX), with the old bintrans system enabled:  5000/200 (3MAX):
366  .Pp  .Pp
367  .Dl "gxemul -E dec -e 3max -b -d netbsddisk.img"  .Dl "gxemul -e 3max -d nbsd_pmax.img"
368  .Pp  .Pp
369  netbsddisk.img should be a raw disk image containing a bootable  nbsd_pmax.img should be a raw disk image containing a bootable
370  NetBSD/pmax filesystem.  NetBSD/pmax filesystem.
371  .Pp  .Pp
372  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 311  Please read the documentation for more d Line 390  Please read the documentation for more d
390  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
391  file in the  file in the
392  .Nm  .Nm
393  source distribution, some are indirectly mentioned in the TODO file.  source distribution, some are indirectly mentioned in the TODO file,
394    and some are mentioned in the source code itself.
395    .Pp
396    The binary translation subsystem used for emulating MIPS processors is
397    really terrible, but it is less terrible than running without it. It will
398    be removed once the newer MIPS dyntrans emulation mode works well enough.
399    .Pp
400    Userland (syscall-only) emulation doesn't really work yet.
401    .Pp
402    Emulation of MIPS CPUs is done differently from other emulation modes; the
403    documentation sometimes only reflects the way things work with MIPS
404    emulation, and it is incorrect when applied to e.g. ARM emulation.
405  .Pp  .Pp
406  There is no new bintrans system in this release (0.3.1), so you will  .Nm
407  need to add  is in general not cycle-accurate; it does not simulate individual
408  .Fl b  pipe-line stages or penalties caused by branch-prediction misses or
409  to select the old bintrans system, if you want speed.  cache misses, so it cannot be used for accurate simulation of any actual
410    real-world processor.
411  .Pp  .Pp
412  .Nm  .Nm
413  does not simulate individual pipe-line stages or penalties caused by  is not timing-accurate, i.e. clocks inside the emulator are in general
414  branch-prediction misses, so it cannot be used for accurate performance  not at all synched with clocks in the real world. There are a few
415  measurement.  exceptions to this rule (the mc146818 device tries to automagically
416    adjust emulated timer ticks to actual emulation speed).
417  .Sh AUTHOR  .Sh AUTHOR
418  Anders Gavare <anders@gavare.se>  GXemul is Copyright (C) 2003-2006 Anders Gavare <anders@gavare.se>
419  .Pp  .Pp
420  See http://gavare.se/gxemul/ for more information.  See http://gavare.se/gxemul/ for more information. For other Copyright
421    messages, see the corresponding parts of the source code and/or
422    documentation.
Legend:
Removed from v.4  
changed lines
  Added in v.22
  ViewVC Help
Powered by ViewVC 1.1.26