1 |
.\" $Id: gxemul.1,v 1.65 2006/06/22 13:22:40 debug Exp $ |
.\" $Id: gxemul.1,v 1.76 2006/11/04 06:40:20 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 JUNE 2006 |
.Dd NOVEMBER 2006 |
33 |
.Dt GXEMUL 1 |
.Dt GXEMUL 1 |
34 |
.Os |
.Os |
35 |
.Sh NAME |
.Sh NAME |
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 |
Processors (ARM, MIPS, PowerPC) are emulated using a kind of dynamic |
Processors (ARM, MIPS, PowerPC, SuperH) are emulated using dynamic translation. |
58 |
translation system. Performance is somewhere between traditional |
However, unlike some other dynamically translating emulators, GXemul does |
59 |
interpretation and recompilation into native code. However, the dynamic |
not currently generate native code, only a "runnable intermediate |
60 |
translation system used in GXemul does not (currently) generate native |
representation", and will thus run on any host architecture, without the |
61 |
code, and thus does not require platform-specific back-ends. In plain |
need to implement per-architecture backends. |
|
English, this means that the dyntrans system works on any host architecture. |
|
62 |
.Pp |
.Pp |
63 |
The emulator can be invoked in the following ways: |
The emulator can be invoked in the following ways: |
64 |
.Pp |
.Pp |
103 |
option to indicate which file on the CDROM filesystem that should be |
option to indicate which file on the CDROM filesystem that should be |
104 |
loaded into emulated memory. |
loaded into emulated memory. |
105 |
.Pp |
.Pp |
106 |
|
Gzipped kernels are automatically unzipped, by calling the external gunzip |
107 |
|
program, both when specifying a gzipped file directly on the command line |
108 |
|
and when loading such a file using the |
109 |
|
.Fl j |
110 |
|
option. |
111 |
|
.Pp |
112 |
Machine selection options: |
Machine selection options: |
113 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
114 |
.It Fl E Ar t |
.It Fl E Ar t |
130 |
.Pp |
.Pp |
131 |
Other options: |
Other options: |
132 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
|
.\" The -A command line option is DEPRECATED and will be removed soon. |
|
|
.\" .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. (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 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. |
|
133 |
.It Fl C Ar x |
.It Fl C Ar x |
134 |
Try to emulate a specific CPU type, |
Try to emulate a specific CPU type, |
135 |
.Ar "x". |
.Ar "x". |
197 |
.Ar port |
.Ar port |
198 |
for incoming remote GDB connections. The emulator starts up in paused |
for incoming remote GDB connections. The emulator starts up in paused |
199 |
mode, and it is up to the remote GDB instance to start the session. |
mode, and it is up to the remote GDB instance to start the session. |
200 |
.It Fl I Ar x |
.It Fl I Ar hz |
201 |
Emulate clock interrupts at |
Set the main CPUs frequency to |
202 |
.Ar x |
.Ar hz |
203 |
Hz. (This affects emulated clock devices only, not actual runtime speed. |
Hz. This option does not work for all emulated machine modes. It affects |
204 |
This disables automatic clock adjustments, which is otherwise turned on.) |
the way count/compare interrupts are faked to simulate emulated time = |
205 |
(This option is probably only valid for DECstation emulation.) |
real world time. If the guest operating system relies on RTC interrupts |
206 |
|
instead of count/compare interrupts, then this option has no effect. |
207 |
|
.Pp |
208 |
|
Setting the frequency to zero disables automatic synchronization of |
209 |
|
emulated time vs real world time, and the count/compare system runs at a |
210 |
|
fixed rate. |
211 |
.It Fl i |
.It Fl i |
212 |
Display each instruction as it is being executed. |
Enable instruction trace, i.e. display disassembly of each instruction as |
213 |
|
it is being executed. |
214 |
.It Fl J |
.It Fl J |
215 |
Disable some speed tricks. This usually means disabling the use of |
Disable instruction combinations in the dynamic translator. |
|
dyntrans "instruction combinations". |
|
216 |
.It Fl j Ar n |
.It Fl j Ar n |
217 |
Set the name of the kernel to |
Set the name of the kernel to |
218 |
.Ar "n". |
.Ar "n". |
231 |
.It Fl n Ar nr |
.It Fl n Ar nr |
232 |
Set the number of processors in the machine, for SMP experiments. |
Set the number of processors in the machine, for SMP experiments. |
233 |
.Pp |
.Pp |
234 |
Note: The emulator allocates quite a |
Note 1: The emulator allocates quite a lot of virtual memory for |
235 |
lot of virtual memory for per-CPU translation tables. On 64-bit hosts, |
per-CPU translation tables. On 64-bit hosts, this is normally not a |
236 |
this is normally not a problem. On 32-bit hosts, this can use up all |
problem. On 32-bit hosts, this can use up all available virtual userspace |
237 |
available virtual userspace memory. The solution is to either run the |
memory. The solution is to either run the emulator on a 64-bit host, |
238 |
emulator on a 64-bit host, or limit the number of emulated CPUs to a |
or limit the number of emulated CPUs to a reasonably low number. |
|
reasonable number (say, less than 32). |
|
239 |
.Pp |
.Pp |
240 |
Note 2: SMP simulation is not working very well yet; multiple processors |
Note 2: SMP simulation is not working very well yet; multiple processors |
241 |
are simulated, but synchronization between the processors does not map |
are simulated, but synchronization between the processors does not map |
254 |
can be a symbol, or a numeric value. (Remember to use the "0x" prefix for |
can be a symbol, or a numeric value. (Remember to use the "0x" prefix for |
255 |
hexadecimal values.) |
hexadecimal values.) |
256 |
.It Fl Q |
.It Fl Q |
257 |
Disable the built-in PROM emulation. This is useful for |
Disable the built-in (software-only) PROM emulation. This option is useful |
258 |
experimenting with running raw ROM images from real machines. |
for experimenting with running raw ROM images from real machines. The default |
259 |
|
behaviour of the emulator is to "fake" certain PROM calls used by guest |
260 |
|
operating systems (e.g. NetBSD), so that no real PROM image is needed. |
261 |
.It Fl R |
.It Fl R |
262 |
Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.) |
Use a random bootstrap cpu, instead of CPU nr 0. (This option is only |
263 |
|
meaningful together with the |
264 |
|
.Fl n |
265 |
|
option.) |
266 |
.It Fl r |
.It Fl r |
267 |
Dump register contents for every executed instruction. |
Dump register contents for every executed instruction. |
268 |
.It Fl S |
.It Fl S |
270 |
is useful when trying to trigger bugs in a program that occur because the |
is useful when trying to trigger bugs in a program that occur because the |
271 |
program assumed that uninitialized memory contains zeros. (Use with |
program assumed that uninitialized memory contains zeros. (Use with |
272 |
care.) |
care.) |
273 |
|
.It Fl s Ar flags:filename |
274 |
|
Gather statistics based on the current emulated program counter value, |
275 |
|
while the program executes. The statistics is actually just a raw dump of |
276 |
|
all program counter values in sequence, suitable for post-analysis with |
277 |
|
separate tools. Output is appended to |
278 |
|
.Ar filename. |
279 |
|
.Pp |
280 |
|
The |
281 |
|
.Ar flags |
282 |
|
should include one or more of the following type specifiers: |
283 |
|
.Bl -tag -width Ds |
284 |
|
.It v |
285 |
|
Virtual. This means that the program counter value is used. |
286 |
|
.It p |
287 |
|
Physical. This means that the physical address of where the program |
288 |
|
is actually running is used. |
289 |
|
.It i |
290 |
|
Instruction call. This type of statistics gathering is practically only |
291 |
|
useful during development of the emulator itself. The output is a list of |
292 |
|
addresses of instruction call functions (ic->f), which after some |
293 |
|
post-processing can be used as a basis for deciding when to implement |
294 |
|
instruction combinations. |
295 |
|
.El |
296 |
|
.Pp |
297 |
|
The |
298 |
|
.Ar flags |
299 |
|
may also include the following optional modifiers: |
300 |
|
.Bl -tag -width Ds |
301 |
|
.It d |
302 |
|
Disabled at startup. |
303 |
|
.It o |
304 |
|
Overwrite the file, instead of appending to it. |
305 |
|
.El |
306 |
|
.Pp |
307 |
|
.\" Statistics gathering can be enabled/disabled at runtime by using the |
308 |
|
.\" "TODO" debugger command. |
309 |
|
.\" .Pp |
310 |
|
When gathering instruction statistics using the |
311 |
|
.Fl s |
312 |
|
option, instruction combinations are always disabled (i.e. |
313 |
|
an implicit |
314 |
|
.Fl J |
315 |
|
is added to the command line). |
316 |
|
.Pp |
317 |
|
If a value is missing (e.g. the end-of-page slot does not really have a |
318 |
|
known physical address), it is written out as just a dash ("-"). |
319 |
.It Fl t |
.It Fl t |
320 |
Show a trace tree of all function calls being made. |
Show a trace tree of all function calls being made. |
321 |
.It Fl U |
.It Fl U |
378 |
.Fl V |
.Fl V |
379 |
option, and entering the commands manually. |
option, and entering the commands manually. |
380 |
.It Fl D |
.It Fl D |
381 |
Guarantee fully deterministic behavior. Normally, the emulator calls |
Causes the emulator to skip a call to srandom(). This leads to somewhat |
382 |
srandom() with a seed based on the current time at startup. When the |
more deterministic behaviour than running without this option. |
383 |
.Fl D |
However, if the emulated machine has clocks or timer interrupt sources, |
384 |
option is used, the srandom() call is skipped, which should cause two |
or if user interaction is taking place (e.g. keyboard input at irregular |
385 |
subsequent invocations of the emulator to be identical, if all other |
intervals), then this option is meaningless. |
|
settings are identical and no user input is taking place. (If this option |
|
|
is used, then |
|
|
.Fl I |
|
|
must also be used.) |
|
386 |
.It Fl H |
.It Fl H |
387 |
Display a list of available CPU types, machine types, and userland |
Display a list of available CPU types, machine types, and userland |
388 |
emulation modes. (Most of these don't work. Please read the documentation |
emulation modes. (Most of these don't work. Please read the documentation |
466 |
.Nm |
.Nm |
467 |
source distribution, some are marked as TODO in the source code itself. |
source distribution, some are marked as TODO in the source code itself. |
468 |
.Pp |
.Pp |
469 |
Userland (syscall-only) emulation doesn't really work yet. |
Userland (syscall-only) emulation, i.e. running a userland binary directly |
470 |
|
without simulating an entire machine, doesn't really work yet. |
471 |
.Pp |
.Pp |
472 |
The documentation sometimes only reflects the way things worked with |
The documentation sometimes only reflects the way things worked with |
473 |
the old MIPS emulation mode (prior to 0.4.0), and it is incorrect when |
the old MIPS emulation mode (prior to 0.4.0), and it is incorrect when |
480 |
real-world processor. |
real-world processor. |
481 |
.Pp |
.Pp |
482 |
.Nm |
.Nm |
483 |
is not timing-accurate, i.e. clocks inside the emulator are in general |
is in general not timing-accurate. Some emulation modes |
484 |
not at all synched with clocks in the real world. There are a few |
(DECstation, CATS, NetWinder, MobilePro (hpcmips), Malta (evbmips), |
485 |
exceptions to this rule (the mc146818 device tries to automagically |
Cobalt, Algor, and Dreamcast) try to make the guest |
486 |
adjust emulated timer ticks to actual emulation speed). |
operating system's clock run at the same speed as the host clock. |
487 |
|
However, the number of instructions executed per clock tick can |
488 |
|
obviously vary, depending on the current CPU load on the host. |
489 |
.Sh AUTHOR |
.Sh AUTHOR |
490 |
GXemul is Copyright (C) 2003-2006 Anders Gavare <anders@gavare.se> |
GXemul is Copyright (C) 2003-2006 Anders Gavare <anders@gavare.se> |
491 |
.Pp |
.Pp |