1 |
.\" $Id: gxemul.1,v 1.49 2006/02/18 14:02:20 debug Exp $ |
.\" $Id: gxemul.1,v 1.65 2006/06/22 13:22:40 debug Exp $ |
2 |
.\" |
.\" |
3 |
.\" Copyright (C) 2004-2006 Anders Gavare. All rights reserved. |
.\" Copyright (C) 2004-2006 Anders Gavare. All rights reserved. |
4 |
.\" |
.\" |
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 FEBRUARY 2006 |
.Dd JUNE 2006 |
33 |
.Dt GXEMUL 1 |
.Dt GXEMUL 1 |
34 |
.Os |
.Os |
35 |
.Sh NAME |
.Sh NAME |
42 |
.Nm |
.Nm |
43 |
.Op general options |
.Op general options |
44 |
.Ar @configfile |
.Ar @configfile |
45 |
.Nm |
.\" TODO: Reenable this once userland emulation works: |
46 |
.Op userland, other, and general options |
.\" .Nm |
47 |
.Ar file Op Ar args ... |
.\" .Op userland, other, and general options |
48 |
|
.\" .Ar file Op Ar args ... |
49 |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
50 |
.Nm |
.Nm |
51 |
is an experimental instruction-level machine emulator. Several |
is an experimental instruction-level machine emulator. Several |
54 |
systems (e.g. NetBSD) run inside the emulator as if they were running on a |
systems (e.g. NetBSD) run inside the emulator as if they were running on a |
55 |
real machine. |
real machine. |
56 |
.Pp |
.Pp |
57 |
The processor architecture best emulated by GXemul is MIPS, but other |
Processors (ARM, MIPS, PowerPC) are emulated using a kind of dynamic |
58 |
architectures (ARM and PowerPC) are also partially emulated. |
translation system. Performance is somewhere between traditional |
59 |
.Pp |
interpretation and recompilation into native code. However, the dynamic |
60 |
MIPS processors are emulated using either a simple binary translation |
translation system used in GXemul does not (currently) generate native |
61 |
layer (recompilation into native code), which is used on Alpha and i386 |
code, and thus does not require platform-specific back-ends. In plain |
62 |
hosts, or by traditional interpretation (very very slow, but works on any |
English, this means that the dyntrans system works on any host architecture. |
|
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. |
|
63 |
.Pp |
.Pp |
64 |
There are three ways to invoke the emulator: |
The emulator can be invoked in the following ways: |
65 |
.Pp |
.Pp |
66 |
1. When emulating a complete machine, configuration options can be entered |
1. When emulating a complete machine, configuration options can be entered |
67 |
directly on the command line. |
directly on the command line. |
68 |
.Pp |
.Pp |
69 |
2. Options can be read from a configuration file. |
2. Options can be read from a configuration file. |
70 |
.Pp |
.\" .Pp |
71 |
3. When emulating a userland environment (syscall-only emulation, not |
.\" 3. When emulating a userland environment (syscall-only emulation, not |
72 |
emulating complete machines), then the program name and its argument |
.\" emulating complete machines), then the program name and its argument |
73 |
should be given on the command line. (This mode doesn't really work yet.) |
.\" should be given on the command line. (This mode doesn't really work yet, |
74 |
|
.\" and is disabled for stable release builds.) |
75 |
.Pp |
.Pp |
76 |
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 |
77 |
command line. The most important thing you need to supply is the |
command line. The most important thing you need to supply is the |
125 |
.Pp |
.Pp |
126 |
Other options: |
Other options: |
127 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
128 |
.It Fl A |
.\" The -A command line option is DEPRECATED and will be removed soon. |
129 |
Disable load/store alignment checks in some cases. This might give a small |
.\" .It Fl A |
130 |
increase in performance, but the emulator will not run correctly if the |
.\" Disable load/store alignment checks in some cases. This might give a small |
131 |
emulated code actually tries to do unaligned loads or stores. (This option |
.\" increase in performance, but the emulator will not run correctly if the |
132 |
is only meaningful when emulating MIPS CPUs, when the host architecture is |
.\" emulated code actually tries to do unaligned loads or stores. (This option |
133 |
Alpha or i386, and binary translation is enabled.) |
.\" is only meaningful when emulating MIPS CPUs, when the host architecture is |
134 |
.It Fl B |
.\" Alpha or i386, and binary translation is enabled.) |
135 |
Disable native translation backends. By default, translation backends are |
.\" .It Fl B |
136 |
used if the host+target architecture combination is supported. Currently, |
.\" Disable native translation backends. By default, translation backends are |
137 |
the only supported host architecture for the old bintrans system (used |
.\" used if the host+target architecture combination is supported. Currently, |
138 |
when emulating MIPS processors) are Alpha and i386. The old bintrans |
.\" the only supported host architecture for the old bintrans system (used |
139 |
system will hopefully be removed some day. |
.\" when emulating MIPS processors) are Alpha and i386. The old bintrans |
140 |
|
.\" system will hopefully be removed some day. |
141 |
.It Fl C Ar x |
.It Fl C Ar x |
142 |
Try to emulate a specific CPU type, |
Try to emulate a specific CPU type, |
143 |
.Ar "x". |
.Ar "x". |
145 |
(Use |
(Use |
146 |
.Fl H |
.Fl H |
147 |
to get a list of available CPU types.) |
to get a list of available CPU types.) |
148 |
.It Fl d Ar name |
.It Fl d Ar [modifiers:]filename |
149 |
Add |
Add |
150 |
.Ar name |
.Ar filename |
151 |
as a disk image. By adding one or more modifier characters and then a |
as a disk image. By adding one or more modifier characters and then a |
152 |
colon (":") as a prefix to |
colon (":") as a prefix to |
153 |
.Ar "name", |
.Ar filename, |
154 |
you can modify the way the disk image is treated. Available modifiers are: |
you can modify the way the disk image is treated. Available modifiers are: |
155 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
156 |
.It b |
.It b |
176 |
Force a specific ID number. |
Force a specific ID number. |
177 |
.El |
.El |
178 |
.Pp |
.Pp |
179 |
|
For SCSI devices, the ID number is the SCSI ID. For IDE harddisks, the ID |
180 |
|
number has the following meaning: |
181 |
|
.Bl -tag -width Ds |
182 |
|
.It 0 |
183 |
|
Primary master. |
184 |
|
.It 1 |
185 |
|
Primary slave. |
186 |
|
.It 2 |
187 |
|
Secondary master. |
188 |
|
.It 3 |
189 |
|
Secondary slave. |
190 |
|
.El |
191 |
|
.Pp |
192 |
Unless otherwise specified, filenames ending with ".iso" or ".cdr" are |
Unless otherwise specified, filenames ending with ".iso" or ".cdr" are |
193 |
assumed to be CDROM images. Most others are assumed to be disks. Depending |
assumed to be CDROM images. Most others are assumed to be disks. Depending |
194 |
on which machine is being emulated, the default for disks can be either |
on which machine is being emulated, the default for disks can be either |
200 |
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 |
201 |
number of sectors per track is calculated automatically. (This works for |
number of sectors per track is calculated automatically. (This works for |
202 |
720KB, 1.2MB, 1.44MB, and 2.88MB floppies.) |
720KB, 1.2MB, 1.44MB, and 2.88MB floppies.) |
203 |
|
.It Fl G Ar port |
204 |
|
Pause at startup, and listen to TCP port |
205 |
|
.Ar port |
206 |
|
for incoming remote GDB connections. The emulator starts up in paused |
207 |
|
mode, and it is up to the remote GDB instance to start the session. |
208 |
.It Fl I Ar x |
.It Fl I Ar x |
209 |
Emulate clock interrupts at |
Emulate clock interrupts at |
210 |
.Ar x |
.Ar x |
214 |
.It Fl i |
.It Fl i |
215 |
Display each instruction as it is being executed. |
Display each instruction as it is being executed. |
216 |
.It Fl J |
.It Fl J |
217 |
Disable some speed tricks. For MIPS emulation, these are mostly |
Disable some speed tricks. This usually means disabling the use of |
218 |
timing-related. For non-MIPS emulation (i.e. modes using dyntrans), |
dyntrans "instruction combinations". |
|
this flag disables the use of "instruction combinations". |
|
219 |
.It Fl j Ar n |
.It Fl j Ar n |
220 |
Set the name of the kernel to |
Set the name of the kernel to |
221 |
.Ar "n". |
.Ar "n". |
222 |
When booting from an ISO9660 filesystem, the emulator will try to boot |
When booting from an ISO9660 filesystem, the emulator will try to boot |
223 |
using 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 |
224 |
along to the boot program. Useful names are "bsd" for OpenBSD/pmax, |
along to the boot program. Useful names are "bsd" for OpenBSD/pmax, |
225 |
or "vmunix" for Ultrix.) |
"vmunix" for Ultrix, or "vmsprite" for Sprite.) |
226 |
.It Fl M Ar m |
.It Fl M Ar m |
227 |
Emulate |
Emulate |
228 |
.Ar m |
.Ar m |
229 |
MBs of physical RAM. This overrides the default amount of RAM for the |
MBs of physical RAM. This overrides the default amount of RAM for the |
230 |
selected machine type. |
selected machine type. |
|
.It Fl m Ar nr |
|
|
Run at most |
|
|
.Ar nr |
|
|
instructions (on any cpu). |
|
231 |
.It Fl N |
.It Fl N |
232 |
Display nr of instructions/second average, at regular intervals. |
Display the number of executed instructions per second on average, at |
233 |
|
regular intervals. |
234 |
.It Fl n Ar nr |
.It Fl n Ar nr |
235 |
Set nr of CPUs (for SMP experiments). Note: The emulator allocates quite a |
Set the number of processors in the machine, for SMP experiments. |
236 |
|
.Pp |
237 |
|
Note: The emulator allocates quite a |
238 |
lot of virtual memory for per-CPU translation tables. On 64-bit hosts, |
lot of virtual memory for per-CPU translation tables. On 64-bit hosts, |
239 |
this is normally not a problem. On 32-bit hosts, this can use up all |
this is normally not a problem. On 32-bit hosts, this can use up all |
240 |
available virtual userspace memory. The solution is to either run the |
available virtual userspace memory. The solution is to either run the |
241 |
emulator on a 64-bit host, or limit the number of emulated CPUs to a |
emulator on a 64-bit host, or limit the number of emulated CPUs to a |
242 |
reasonable number (say, less than 32). |
reasonable number (say, less than 32). |
243 |
|
.Pp |
244 |
|
Note 2: SMP simulation is not working very well yet; multiple processors |
245 |
|
are simulated, but synchronization between the processors does not map |
246 |
|
very well to how real-world SMP systems work. |
247 |
.It Fl O |
.It Fl O |
248 |
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 |
249 |
present (for DECstation, SGI, and ARC emulation). |
present (for DECstation, SGI, and ARC emulation). |
253 |
.Ar arg |
.Ar arg |
254 |
for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A". |
for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A". |
255 |
.It Fl p Ar pc |
.It Fl p Ar pc |
256 |
Add a breakpoint. (Remember to use the "0x" prefix for hex.) |
Add a breakpoint. |
257 |
|
.Ar pc |
258 |
|
can be a symbol, or a numeric value. (Remember to use the "0x" prefix for |
259 |
|
hexadecimal values.) |
260 |
.It Fl Q |
.It Fl Q |
261 |
Disable the built-in PROM emulation. This is useful for running raw ROM |
Disable the built-in PROM emulation. This is useful for |
262 |
images from real machines. |
experimenting with running raw ROM images from real machines. |
263 |
.It Fl R |
.It Fl R |
264 |
Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.) |
Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.) |
265 |
.It Fl r |
.It Fl r |
266 |
Dump register contents for every executed instruction. |
Dump register contents for every executed instruction. |
267 |
.It Fl S |
.It Fl S |
268 |
Initialize the emulated RAM to random data, instead of zeroes. |
Initialize emulated RAM to random data, instead of zeroes. This option |
269 |
.It Fl T |
is useful when trying to trigger bugs in a program that occur because the |
270 |
Enter the single-step debugger on unimplemented memory accesses. |
program assumed that uninitialized memory contains zeros. (Use with |
271 |
|
care.) |
272 |
.It Fl t |
.It Fl t |
273 |
Show a trace tree of all function calls being made. |
Show a trace tree of all function calls being made. |
274 |
.It Fl U |
.It Fl U |
302 |
.Ar -2 |
.Ar -2 |
303 |
with VGA text mode emulation will result in 80x25 character cells rendered |
with VGA text mode emulation will result in 80x25 character cells rendered |
304 |
in a 1280x800 window, instead of the normal resolution of 640x400. |
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 |
|
|
(experimental). |
|
305 |
.It Fl Z Ar n |
.It Fl Z Ar n |
306 |
Set the number of graphics cards, for emulating a dual-head or tripple-head |
Set the number of graphics cards, for emulating a dual-head or tripple-head |
307 |
environment. (Only for DECstation emulation so far.) |
environment. (Only for DECstation emulation so far.) |
311 |
as an X11 display to use for framebuffers. |
as an X11 display to use for framebuffers. |
312 |
.El |
.El |
313 |
.Pp |
.Pp |
314 |
Userland options: |
.\" Userland options: |
315 |
.Bl -tag -width Ds |
.\" .Bl -tag -width Ds |
316 |
.It Fl u Ar emul-mode |
.\" .It Fl u Ar emul-mode |
317 |
Userland-only (syscall) emulation. (Use |
.\" Userland-only (syscall) emulation. (Use |
318 |
.Fl H |
.\" .Fl H |
319 |
to get a list of available emulation modes.) Some (but not all) of the |
.\" to get a list of available emulation modes.) Some (but not all) of the |
320 |
options listed under Other options above can also be used with userland |
.\" options listed under Other options above can also be used with |
321 |
emulation. |
.\" userland emulation. |
322 |
.El |
.\" .El |
323 |
.Pp |
.\" .Pp |
324 |
General options: |
General options: |
325 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
326 |
.It Fl c Ar cmd |
.It Fl c Ar cmd |
345 |
emulation modes. (Most of these don't work. Please read the documentation |
emulation modes. (Most of these don't work. Please read the documentation |
346 |
included in the |
included in the |
347 |
.Nm |
.Nm |
348 |
distribution for details on which modes that actually work.) |
distribution for details on which modes that actually work. Userland |
349 |
|
emulation is not included in stable release builds, since it doesn't work |
350 |
|
yet.) |
351 |
.It Fl h |
.It Fl h |
352 |
Display a list of all available command line options. |
Display a list of all available command line options. |
353 |
.It Fl K |
.It Fl K |
354 |
Force the single-step debugger to be entered at the end of a simulation. |
Force the single-step debugger to be entered at the end of a simulation. |
355 |
.It Fl q |
.It Fl q |
356 |
Quiet mode; this suppresses startup messages. |
Quiet mode; this suppresses startup messages. |
357 |
.It Fl s |
.\".It Fl s |
358 |
For MIPS emulation: Show opcode usage statistics after the simulation. |
.\"For MIPS emulation: Show opcode usage statistics after the simulation. |
359 |
For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file at |
.\"For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file |
360 |
regular intervals of which physical addresses that were executed. |
.\"at regular intervals of which physical addresses that were executed. |
361 |
.It Fl V |
.It Fl V |
362 |
Start up in the single-step debugger, paused. |
Start up in the single-step debugger, paused. |
363 |
.It Fl v |
.It Fl v |
398 |
.Pp |
.Pp |
399 |
.Dl "gxemul -E testmips -V hello_mips" |
.Dl "gxemul -E testmips -V hello_mips" |
400 |
.Pp |
.Pp |
401 |
(Paused mode means that you enter the interactive single-step debugger |
Paused mode means that you enter the interactive single-step debugger |
402 |
directly at startup, instead of launching the Hello World program.) |
directly at startup, instead of launching the Hello World program. |
403 |
|
.Pp |
404 |
|
The paused mode is also what should be used when running "unknown" files |
405 |
|
for the first time in the emulator. E.g. if you have a binary which you |
406 |
|
think is some kind of MIPS ROM image, then you can try the following: |
407 |
|
.Pp |
408 |
|
.Dl "gxemul -vv -E baremips -V 0xbfc00000:image.raw" |
409 |
|
.Pp |
410 |
|
You can then use the single-stepping functionality of the built-in |
411 |
|
debugger to run the code in the ROM image, to see how it behaves. Based on |
412 |
|
that, you can deduce what machine type it was actually from (the |
413 |
|
baremips machine is not a real machine), and perhaps try again with |
414 |
|
another emulation mode. |
415 |
|
.Pp |
416 |
|
In general, however, real ROM images require much more emulation detail |
417 |
|
than GXemul provides, so they can usually not run. |
418 |
.Pp |
.Pp |
419 |
Please read the documentation for more details. |
Please read the documentation for more details. |
420 |
.Sh BUGS |
.Sh BUGS |
421 |
There are many bugs. Some of the known bugs are listed in the BUGS |
There are many bugs. Some of the known bugs are mentioned in the TODO |
422 |
file in the |
file in the |
423 |
.Nm |
.Nm |
424 |
source distribution, some are indirectly mentioned in the TODO file, |
source distribution, some are marked as TODO in the source code itself. |
|
and some are mentioned in the source code itself. |
|
|
.Pp |
|
|
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. |
|
425 |
.Pp |
.Pp |
426 |
Userland (syscall-only) emulation doesn't really work yet. |
Userland (syscall-only) emulation doesn't really work yet. |
427 |
.Pp |
.Pp |
428 |
Emulation of MIPS CPUs is done differently from other emulation modes; the |
The documentation sometimes only reflects the way things worked with |
429 |
documentation sometimes only reflects the way things work with MIPS |
the old MIPS emulation mode (prior to 0.4.0), and it is incorrect when |
430 |
emulation, and it is incorrect when applied to e.g. ARM emulation. |
applied to current releases. |
431 |
.Pp |
.Pp |
432 |
.Nm |
.Nm |
433 |
is in general not cycle-accurate; it does not simulate individual |
is in general not cycle-accurate; it does not simulate individual |