--- trunk/man/gxemul.1 2007/10/08 16:18:51 14 +++ trunk/man/gxemul.1 2007/10/08 16:19:37 22 @@ -1,6 +1,6 @@ -.\" $Id: gxemul.1,v 1.33 2005/10/07 22:45:34 debug Exp $ +.\" $Id: gxemul.1,v 1.49 2006/02/18 14:02:20 debug Exp $ .\" -.\" Copyright (C) 2004-2005 Anders Gavare. All rights reserved. +.\" Copyright (C) 2004-2006 Anders Gavare. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: @@ -29,7 +29,7 @@ .\" This is a minimal man page for GXemul. Process this file with .\" groff -man -Tascii gxemul.1 or nroff -man gxemul.1 .\" -.Dd OCTOBER 2005 +.Dd FEBRUARY 2006 .Dt GXEMUL 1 .Os .Sh NAME @@ -50,10 +50,24 @@ is an experimental instruction-level machine emulator. Several emulation modes are available. In some modes, processors and surrounding hardware components are emulated well enough to let unmodified operating -systems (e.g. NetBSD) run as if they were running on a real machine. +systems (e.g. NetBSD) run inside the emulator as if they were running on a +real machine. .Pp The processor architecture best emulated by GXemul is MIPS, but other -architectures are also partially emulated. +architectures (ARM and PowerPC) are also partially emulated. +.Pp +MIPS processors are emulated using either a simple binary translation +layer (recompilation into native code), which is used on Alpha and i386 +hosts, or by traditional interpretation (very very slow, but works on any +host platform). +.Pp +Non-MIPS processors are emulated using a newer dynamic translation +system (called dyntrans in the rest of this man page). Performance is +somewhere between traditional interpretation and recompilation into native +code. However, the dynamic translation system used in GXemul does NOT +generate native code, and thus doesn't require platform-specific +back-ends. In plain English, this means that the dyntrans system works on +any host platform. .Pp There are three ways to invoke the emulator: .Pp @@ -121,11 +135,15 @@ .It Fl A Disable load/store alignment checks in some cases. This might give a small increase in performance, but the emulator will not run correctly if the -emulated code actually tries to do unaligned loads or stores. +emulated code actually tries to do unaligned loads or stores. (This option +is only meaningful when emulating MIPS CPUs, when the host architecture is +Alpha or i386, and binary translation is enabled.) .It Fl B -Disable dynamic binary translation. By default, bintrans -will be turned on if the host+target architecture combination is -supported. +Disable native translation backends. By default, translation backends are +used if the host+target architecture combination is supported. Currently, +the only supported host architecture for the old bintrans system (used +when emulating MIPS processors) are Alpha and i386. The old bintrans +system will hopefully be removed some day. .It Fl C Ar x Try to emulate a specific CPU type, .Ar "x". @@ -153,11 +171,11 @@ Override the default geometry; use H heads and S sectors-per-track. (The number of cylinders is calculated automatically.) .It i -IDE. +IDE. (This is the default for most machine types.) .It r Read-only (don't allow changes to be written to the file). .It s -SCSI (this is the default for most machine types). +SCSI. .It t Tape. .It 0-7 @@ -184,7 +202,9 @@ .It Fl i Display each instruction as it is being executed. .It Fl J -Disable some speed tricks. +Disable some speed tricks. For MIPS emulation, these are mostly +timing-related. For non-MIPS emulation (i.e. modes using dyntrans), +this flag disables the use of "instruction combinations". .It Fl j Ar n Set the name of the kernel to .Ar "n". @@ -204,15 +224,20 @@ .It Fl N Display nr of instructions/second average, at regular intervals. .It Fl n Ar nr -Set nr of CPUs (for SMP experiments). +Set nr of CPUs (for SMP experiments). Note: The emulator allocates quite a +lot of virtual memory for per-CPU translation tables. On 64-bit hosts, +this is normally not a problem. On 32-bit hosts, this can use up all +available virtual userspace memory. The solution is to either run the +emulator on a 64-bit host, or limit the number of emulated CPUs to a +reasonable number (say, less than 32). .It Fl O Force a "netboot" (tftp instead of disk), even when a disk image is present (for DECstation, SGI, and ARC emulation). .It Fl o Ar arg -Set the boot argument (for DEC, ARC, or SGI emulation). +Set the boot argument (mostly useful for DEC, ARC, or SGI emulation). Default .Ar arg -for DEC is "-a", for ARC "-aN". +for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A". .It Fl p Ar pc Add a breakpoint. (Remember to use the "0x" prefix for hex.) .It Fl Q @@ -231,17 +256,34 @@ .It Fl U Enable slow_serial_interrupts_hack_for_linux. .It Fl X -Use X11. +Use X11. This option enables graphical framebuffers. .It Fl x -Open up new xterms for emulated serial ports. (Default is to open up -xterms when using configuration files, but not when starting an -emulation with settings directly on the command line.) +Open up new xterms for emulated serial ports. The default behaviour is to +open up xterms when using configuration files, or if X11 is enabled. When +starting up a simple emulation session with settings directly on the +command line, and neither +.Fl X +nor +.Fl x +is used, then all output is confined to the terminal that +.Nm +started in. .It Fl Y Ar n Scale down framebuffer windows by .Ar n x .Ar n -times. +times. This option is useful when emulating a very large framebuffer, and +the actual display is of lower resolution. If +.Ar n +is negative, then there will be no scaledown, but emulation of certain +graphic controllers will be scaled up +by +.Ar -n +times instead. E.g. Using +.Ar -2 +with VGA text mode emulation will result in 80x25 character cells rendered +in a 1280x800 window, instead of the normal resolution of 640x400. .It Fl y Ar x Set max_random_cycles_per_chunk to .Ar x @@ -267,6 +309,13 @@ .Pp General options: .Bl -tag -width Ds +.It Fl c Ar cmd +Add +.Ar cmd +as a command to run before starting the simulation. A similar effect can +be achieved by using the +.Fl V +option, and entering the commands manually. .It Fl D Guarantee fully deterministic behavior. Normally, the emulator calls srandom() with a seed based on the current time at startup. When the @@ -290,11 +339,14 @@ .It Fl q Quiet mode; this suppresses startup messages. .It Fl s -Show opcode usage statistics after the simulation. +For MIPS emulation: Show opcode usage statistics after the simulation. +For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file at +regular intervals of which physical addresses that were executed. .It Fl V Start up in the single-step debugger, paused. .It Fl v -Verbose debug messages. +Increase verbosity (show more debug messages). This option can be used +multiple times. .El .Pp Configuration file startup: @@ -341,19 +393,30 @@ source distribution, some are indirectly mentioned in the TODO file, and some are mentioned in the source code itself. .Pp -The binary translation subsystem is really terrible, but it is less -terrible than running without it. +The binary translation subsystem used for emulating MIPS processors is +really terrible, but it is less terrible than running without it. It will +be removed once the newer MIPS dyntrans emulation mode works well enough. .Pp Userland (syscall-only) emulation doesn't really work yet. .Pp +Emulation of MIPS CPUs is done differently from other emulation modes; the +documentation sometimes only reflects the way things work with MIPS +emulation, and it is incorrect when applied to e.g. ARM emulation. +.Pp .Nm -does not simulate individual pipe-line stages or penalties caused by -branch-prediction misses or cache misses, so it cannot be used for -accurate simulation of any actual real-world processor. +is in general not cycle-accurate; it does not simulate individual +pipe-line stages or penalties caused by branch-prediction misses or +cache misses, so it cannot be used for accurate simulation of any actual +real-world processor. .Pp .Nm -is not timing-accurate. +is not timing-accurate, i.e. clocks inside the emulator are in general +not at all synched with clocks in the real world. There are a few +exceptions to this rule (the mc146818 device tries to automagically +adjust emulated timer ticks to actual emulation speed). .Sh AUTHOR -Anders Gavare +GXemul is Copyright (C) 2003-2006 Anders Gavare .Pp -See http://gavare.se/gxemul/ for more information. +See http://gavare.se/gxemul/ for more information. For other Copyright +messages, see the corresponding parts of the source code and/or +documentation.