1 |
.\" $Id: gxemul.1,v 1.89 2007/04/10 15:37:00 debug Exp $ |
.\" $Id: gxemul.1,v 1.96 2007/06/15 21:43:53 debug Exp $ |
2 |
.\" |
.\" |
3 |
.\" Copyright (C) 2004-2007 Anders Gavare. All rights reserved. |
.\" Copyright (C) 2004-2007 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 APRIL 2007 |
.Dd JUNE 2007 |
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 |
.\" TODO: Reenable this once userland emulation works: |
.Nm |
46 |
.\" .Nm |
.Op userland, other, and general options |
47 |
.\" .Op userland, other, and general options |
.Ar file Op Ar args ... |
|
.\" .Ar file Op Ar args ... |
|
48 |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
49 |
.Nm |
.Nm |
50 |
is an experimental instruction-level machine emulator. Several |
is an experimental instruction-level machine emulator. Several |
53 |
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 |
54 |
real machine. |
real machine. |
55 |
.Pp |
.Pp |
56 |
Processors (ARM, MIPS, PowerPC, SuperH) are emulated using dynamic translation. |
Processors (ARM, MIPS, PowerPC, and SuperH) are emulated using dynamic |
57 |
However, unlike some other dynamically translating emulators, GXemul does |
translation. However, unlike some other dynamically translating emulators, |
58 |
not need to generate native code, only a "runnable intermediate |
GXemul does not need to generate native code, only a "runnable |
59 |
representation", and will thus run on any host architecture, without the |
intermediate representation", and will thus run on any host architecture, |
60 |
need to implement per-architecture backends. |
without the need to implement per-architecture backends. |
61 |
.Pp |
.Pp |
62 |
The emulator can be invoked in the following ways: |
The emulator can be invoked in the following ways: |
63 |
.Pp |
.Pp |
64 |
1. When emulating a complete machine, configuration options can be entered |
1. When emulating a complete machine, configuration options can be |
65 |
directly on the command line. |
supplied directly on the command line. |
66 |
.Pp |
.Pp |
67 |
2. Options can be read from a configuration file. |
2. Options can be read from a configuration file. |
68 |
.\" .Pp |
.Pp |
69 |
.\" 3. When emulating a userland environment (syscall-only emulation, not |
3. When emulating a userland environment (syscall-only emulation, not |
70 |
.\" emulating complete machines), then the program name and its argument |
emulating complete machines), then the program name and its argument |
71 |
.\" should be given on the command line. (This mode doesn't really work yet, |
should be given on the command line. (This mode is not really usable yet.) |
|
.\" and is disabled for stable release builds.) |
|
72 |
.Pp |
.Pp |
73 |
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 |
74 |
command line. The most important thing you need to supply is the |
command line. |
75 |
|
.Pp |
76 |
|
The most important thing you need to supply is the |
77 |
file argument. This is the name of a binary file (an ELF, a.out, COFF/ECOFF, |
file argument. This is the name of a binary file (an ELF, a.out, COFF/ECOFF, |
78 |
SREC, or a raw binary image) which you wish to run in the emulator. This file |
SREC, or a raw binary image) which you wish to run in the emulator. This file |
79 |
might be an operating system kernel, or perhaps a ROM image file. |
might be an operating system kernel, or perhaps a ROM image file. |
|
.Pp |
|
80 |
If more than one filename is supplied, all files are loaded into memory, |
If more than one filename is supplied, all files are loaded into memory, |
81 |
and the entry point (if available) is taken from the last file. |
and the entry point (if available) is taken from the last file. |
82 |
.Pp |
.Pp |
83 |
Apart from the name of a binary file, it is also necessary to select |
Apart from the name of a binary file, you must also use the |
84 |
which specific emulation mode to use. For example, a MIPS-based machine |
.Fl E |
85 |
from DEC (a DECstation) is very different from a MIPS-based machine |
and/or |
86 |
from SGI. Use |
.Fl e |
87 |
|
options to select which emulation mode to use. This is necessary because |
88 |
|
the emulator cannot in general deduce this from the file being executed. |
89 |
|
For example, a MIPS-based machine from DEC (a DECstation) is very different |
90 |
|
from a MIPS-based machine from SGI. Use |
91 |
.Nm |
.Nm |
92 |
.Fl H |
.Fl H |
93 |
to get a list of available emulation modes. |
to get a list of available emulation modes. |
210 |
number of sectors per track is calculated automatically. (This works for |
number of sectors per track is calculated automatically. (This works for |
211 |
720KB, 1.2MB, 1.44MB, and 2.88MB floppies.) |
720KB, 1.2MB, 1.44MB, and 2.88MB floppies.) |
212 |
.It Fl I Ar hz |
.It Fl I Ar hz |
213 |
Set the main CPUs frequency to |
Set the main CPU's frequency to |
214 |
.Ar hz |
.Ar hz |
215 |
Hz. This option does not work for all emulated machine modes. It affects |
Hz. This option does not work for all emulated machine modes. It affects |
216 |
the way count/compare interrupts are faked to simulate emulated time = |
the way count/compare interrupts are faked to simulate emulated time = |
328 |
and |
and |
329 |
.Fl B |
.Fl B |
330 |
flags are added to the command line). |
flags are added to the command line). |
|
.Pp |
|
|
If a value is missing (e.g. the end-of-page slot does not really have a |
|
|
known physical address), it is written out as just a dash ("-"). |
|
331 |
.It Fl T |
.It Fl T |
332 |
Halt if the emulated program attempts to access non-existing memory. |
Halt if the emulated program attempts to access non-existing memory. |
333 |
.It Fl t |
.It Fl t |
372 |
as an X11 display to use for framebuffers. |
as an X11 display to use for framebuffers. |
373 |
.El |
.El |
374 |
.Pp |
.Pp |
375 |
.\" Userland options: |
Userland options: |
376 |
.\" .Bl -tag -width Ds |
.Bl -tag -width Ds |
377 |
.\" .It Fl u Ar emul-mode |
.It Fl u Ar emul-mode |
378 |
.\" Userland-only (syscall) emulation. (Use |
Userland-only (syscall) emulation. (Use |
379 |
.\" .Fl H |
.Fl H |
380 |
.\" 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 |
381 |
.\" options listed under Other options above can also be used with |
options listed under Other options above can also be used with |
382 |
.\" userland emulation. |
userland emulation. |
383 |
.\" .El |
.Pp |
384 |
.\" .Pp |
Note: Userland (syscall) emulation does not really work yet. |
385 |
|
.El |
386 |
|
.Pp |
387 |
General options: |
General options: |
388 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
389 |
.It Fl b |
.It Fl b |
391 |
yet. Don't use it unless you know what you are doing. It will most |
yet. Don't use it unless you know what you are doing. It will most |
392 |
likely not work. |
likely not work. |
393 |
.It Fl B |
.It Fl B |
394 |
Disable native code generation at runtime. (This is the default in |
Disable native code generation at runtime. This is the default in this |
395 |
GXemul 0.4.4; there are no implemented native code generation backends.) |
release of GXemul. |
396 |
.It Fl c Ar cmd |
.It Fl c Ar cmd |
397 |
Add |
Add |
398 |
.Ar cmd |
.Ar cmd |
419 |
.It Fl k Ar n |
.It Fl k Ar n |
420 |
Set the size of the dyntrans cache (per emulated CPU) to |
Set the size of the dyntrans cache (per emulated CPU) to |
421 |
.Ar n |
.Ar n |
422 |
MB. The default size is 32 MB. |
MB. The default size is 48 MB. |
423 |
.It Fl K |
.It Fl K |
424 |
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. |
425 |
.It Fl q |
.It Fl q |
426 |
Quiet mode; this suppresses startup messages. |
Quiet mode; this suppresses startup messages. |
|
.\".It Fl s |
|
|
.\"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. |
|
427 |
.It Fl V |
.It Fl V |
428 |
Start up in the single-step debugger, paused. |
Start up in the single-step debugger, paused. |
429 |
.It Fl v |
.It Fl v |
499 |
real-world processor. |
real-world processor. |
500 |
.Pp |
.Pp |
501 |
.Nm |
.Nm |
502 |
is in general not timing-accurate. Some emulation modes |
is in general not timing-accurate. Many emulation modes try to make the |
503 |
(DECstation, CATS, NetWinder, MobilePro (hpcmips), Malta (evbmips), |
guest operating system's clock run at the same speed as the host clock. |
|
Cobalt, Algor, Dreamcast, PICA-61, and IQ80321) try to make the guest |
|
|
operating system's clock run at the same speed as the host clock. |
|
504 |
However, the number of instructions executed per clock tick can |
However, the number of instructions executed per clock tick can |
505 |
obviously vary, depending on the current CPU load on the host. |
obviously vary, depending on the current CPU load on the host. |
506 |
.Sh AUTHOR |
.Sh AUTHOR |