/[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 22 by dpavlin, Mon Oct 8 16:19:37 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.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 JUNE 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 97  Machine selection options: Line 116  Machine selection options:
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 110  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.X), 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 145  FLOPPY. Line 171  FLOPPY.
171  Override the default geometry; use H heads and S sectors-per-track.  Override the default geometry; use H heads and S sectors-per-track.
172  (The number of cylinders is calculated automatically.)  (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 ID number.  Force a specific ID number.
183  .El  .El
184  .Pp  .Pp
185  Unless otherwise specified, filenames ending with ".iso" are assumed to be  Unless otherwise specified, filenames ending with ".iso" or ".cdr" are
186  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
187  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
188  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
189  (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
190  to use explicit prefixes to force a specific type.)  you need to use explicit prefixes to force a specific type.)
191  .Pp  .Pp
192  For floppies, the gH;S; prefix is ignored. Instead, the number of  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  heads and cylinders are assumed to be 2 and 80, respectively, and the
# Line 176  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  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
212  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
213  along to the boot program. Useful names are "bsd" for OpenBSD/pmax,  along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
214  or "vmunix" for Ultrix.)  or "vmunix" for Ultrix.)
215  .It Fl M Ar m  .It Fl M Ar m
# Line 196  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
# Line 223  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 259  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 behavior. 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
# Line 282  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 302  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 330  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  .Pp
402  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
403  .Fl b  documentation sometimes only reflects the way things work with MIPS
404  to select the old bintrans system, if you want speed.  emulation, and it is incorrect when applied to e.g. ARM emulation.
405  .Pp  .Pp
406  .Nm  .Nm
407  does not simulate individual pipe-line stages or penalties caused by  is in general not cycle-accurate; it does not simulate individual
408  branch-prediction misses, so it cannot be used for accurate performance  pipe-line stages or penalties caused by branch-prediction misses or
409  measurement.  cache misses, so it cannot be used for accurate simulation of any actual
410    real-world processor.
411  .Pp  .Pp
412  .Nm  .Nm
413  is not timing-accurate.  is not timing-accurate, i.e. clocks inside the emulator are in general
414    not at all synched with clocks in the real world. There are a few
415    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.6  
changed lines
  Added in v.22
  ViewVC Help
Powered by ViewVC 1.1.26