--- trunk/man/gxemul.1 2007/10/08 16:19:28 21 +++ trunk/man/gxemul.1 2007/10/08 16:19:37 22 @@ -1,6 +1,6 @@ -.\" $Id: gxemul.1,v 1.39 2005/11/23 22:03:25 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 NOVEMBER 2005 +.Dd FEBRUARY 2006 .Dt GXEMUL 1 .Os .Sh NAME @@ -56,16 +56,18 @@ The processor architecture best emulated by GXemul is MIPS, but other architectures (ARM and PowerPC) are also partially emulated. .Pp -MIPS processors are emulated either using a simple type of binary -translator (on Alpha and i386 hosts), or using traditional slow -interpretation (all other hosts, including amd64 machines running in -64-bit mode). -.Pp -Non-MIPS processors are emulated using a newer dynamic -translation system (called dyntrans in the rest of this man page); -dyntrans does not require any host-specific code, so it should work on any -platform. Performance is somewhere between binary translation and -traditional interpretation. +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 @@ -137,10 +139,11 @@ 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. Currently, the only supported target architecture for bintrans -is MIPS, and the supported host architectures are Alpha and i386. +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". @@ -168,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 @@ -200,7 +203,7 @@ Display each instruction as it is being executed. .It Fl J Disable some speed tricks. For MIPS emulation, these are mostly -timing-related. For non-MIPS emulation (i.e. those modes using dyntrans), +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 @@ -221,7 +224,12 @@ .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). @@ -248,11 +256,18 @@ .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 @@ -294,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 @@ -323,7 +345,8 @@ .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: @@ -370,8 +393,9 @@ 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 @@ -380,13 +404,19 @@ 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.