/[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 12 by dpavlin, Mon Oct 8 16:18:38 2007 UTC revision 22 by dpavlin, Mon Oct 8 16:19:37 2007 UTC
# Line 1  Line 1 
1  .\" $Id: gxemul.1,v 1.29 2005/08/10 15:51:09 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 AUGUST 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 to  is an experimental instruction-level machine emulator. Several
51  run binary code for 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 inside the emulator as if they were running on a
54  let unmodified operating systems (e.g. NetBSD) run as if they were running  real machine.
55  on a real machine.  .Pp
56  .Pp  The processor architecture best emulated by GXemul is MIPS, but other
57  (Non-MIPS emulation modes are also under development, but so far none of  architectures (ARM and PowerPC) are also partially emulated.
58  those modes has reached the completeness required to run unmodified  .Pp
59  operating systems.)  MIPS processors are emulated using either a simple binary translation
60  .Pp  layer (recompilation into native code), which is used on Alpha and i386
61  There are three ways to invoke the emulator. When emulating a  hosts, or by traditional interpretation (very very slow, but works on any
62  complete machine, settings can be entered directly on the command line, or  host platform).
63  they can be read from a configuration file. When emulating a userland  .Pp
64  environment (syscall-only emulation, not emulating complete machines),  Non-MIPS processors are emulated using a newer dynamic translation
65  then the program name and its argument should be given on the command  system (called dyntrans in the rest of this man page). Performance is
66  line.  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 120  Other options: Line 135  Other options:
135  .It Fl A  .It Fl A
136  Disable load/store alignment checks in some cases. This might give a small  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  increase in performance, but the emulator will not run correctly if the
138  emulated code actually tries to do unaligned loads or stores.  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. By default, bintrans  Disable native translation backends. By default, translation backends are
143  will be turned on if the host+target architecture combination is  used if the host+target architecture combination is supported. Currently,
144  supported.  the only supported host architecture for the old bintrans system (used
145    when emulating MIPS processors) are Alpha and i386. The old bintrans
146    system will hopefully be removed some day.
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 152  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 183  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".
# Line 203  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 230  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 266  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 289  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 340  file in the Line 393  file in the
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.  and some are mentioned in the source code itself.
395  .Pp  .Pp
396  The binary translation subsystem is really terrible, but it is less  The binary translation subsystem used for emulating MIPS processors is
397  terrible than running without it.  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  .Pp
400  Userland (syscall-only) emulation doesn't really work yet.  Userland (syscall-only) emulation doesn't really work yet.
401  .Pp  .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
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 or cache misses, so it cannot be used for  pipe-line stages or penalties caused by branch-prediction misses or
409  accurate performance 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.12  
changed lines
  Added in v.22
  ViewVC Help
Powered by ViewVC 1.1.26