1 |
.\" $Id: gxemul.1,v 1.35 2005/10/27 14:01:11 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: |
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 OCTOBER 2005 |
.Dd FEBRUARY 2006 |
33 |
.Dt GXEMUL 1 |
.Dt GXEMUL 1 |
34 |
.Os |
.Os |
35 |
.Sh NAME |
.Sh NAME |
50 |
is an experimental instruction-level machine emulator. Several |
is an experimental instruction-level machine emulator. Several |
51 |
emulation modes are available. In some modes, processors and surrounding |
emulation modes are available. In some modes, processors and surrounding |
52 |
hardware components are emulated well enough to let unmodified operating |
hardware components are emulated well enough to let unmodified operating |
53 |
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 |
54 |
|
real machine. |
55 |
.Pp |
.Pp |
56 |
The processor architecture best emulated by GXemul is MIPS, but other |
The processor architecture best emulated by GXemul is MIPS, but other |
57 |
architectures are also partially emulated. |
architectures (ARM and PowerPC) are also partially emulated. |
58 |
.Pp |
.Pp |
59 |
MIPS processors are emulated either using a simple type of binary |
MIPS processors are emulated using either a simple binary translation |
60 |
translator (on Alpha and i386 hosts), or using traditional slow |
layer (recompilation into native code), which is used on Alpha and i386 |
61 |
interpretation (all other hosts, including amd64 machines running in |
hosts, or by traditional interpretation (very very slow, but works on any |
62 |
64-bit mode). |
host platform). |
63 |
.Pp |
.Pp |
64 |
Non-MIPS processors (e.g. ARM) are emulated using a newer dynamic |
Non-MIPS processors are emulated using a newer dynamic translation |
65 |
translation system (called dyntrans in the rest of this man page); |
system (called dyntrans in the rest of this man page). Performance is |
66 |
dyntrans does not require any host-specific code, so it should work on any |
somewhere between traditional interpretation and recompilation into native |
67 |
platform. Performance is somewhere between binary translation and |
code. However, the dynamic translation system used in GXemul does NOT |
68 |
traditional interpretation. |
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 |
.Pp |
72 |
There are three ways to invoke the emulator: |
There are three ways to invoke the emulator: |
73 |
.Pp |
.Pp |
139 |
is only meaningful when emulating MIPS CPUs, when the host architecture is |
is only meaningful when emulating MIPS CPUs, when the host architecture is |
140 |
Alpha or i386, and binary translation is enabled.) |
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. Currently, the only supported target architecture for bintrans |
the only supported host architecture for the old bintrans system (used |
145 |
is MIPS, and the supported host architectures are Alpha and i386. |
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". |
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 |
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. For MIPS emulation, these are mostly |
Disable some speed tricks. For MIPS emulation, these are mostly |
206 |
timing-related. For non-MIPS emulation (i.e. those modes using dyntrans), |
timing-related. For non-MIPS emulation (i.e. modes using dyntrans), |
207 |
this flag disables the use of "instruction combinations". |
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 |
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). |
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 |
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 |
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: |
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 |
Emulation of MIPS CPUs is done differently from other emulation modes; the |
403 |
documentation sometimes only reflect the way things work with MIPS |
documentation sometimes only reflects the way things work with MIPS |
404 |
emulation, and it is incorrect when applied to e.g. ARM emulation. |
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 or cache misses, so it cannot be used for |
pipe-line stages or penalties caused by branch-prediction misses or |
409 |
accurate simulation of any actual real-world processor. |
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. |