1 |
.\" $Id: gxemul.1,v 1.68 2006/07/16 13:32:24 debug Exp $ |
.\" $Id: gxemul.1,v 1.96 2007/06/15 21:43:53 debug Exp $ |
2 |
.\" |
.\" |
3 |
.\" Copyright (C) 2004-2006 Anders Gavare. All rights reserved. |
.\" Copyright (C) 2004-2007 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 JULY 2006 |
.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) 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 currently 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. |
94 |
.Pp |
.Pp |
95 |
There are two exceptions to the normal invocation usage mentioned above. |
There are three exceptions to the normal invocation usage mentioned above. |
96 |
The first is for DECstation emulation: if you have a bootable |
.Pp |
97 |
DECstation harddisk or CDROM image, then just supplying the diskimage via |
1. For DECstation emulation, if you have a bootable DECstation harddisk or |
98 |
the |
CDROM image, then just supplying the diskimage via the |
99 |
.Fl d |
.Fl d |
100 |
option is sufficient. (The filename of the kernel can then be |
option is sufficient. The filename of the kernel can then be |
101 |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
102 |
doesn't need the kernel as a separate file.) |
doesn't need the kernel as a separate file. |
103 |
The second is if you supply an ISO9660 CDROM disk image. You may then use |
.Pp |
104 |
the |
2. If you supply an ISO9660 CDROM disk image, then using the |
105 |
.Fl j |
.Fl j |
106 |
option to indicate which file on the CDROM filesystem that should be |
option to indicate a file on the CDROM filesystem to load is sufficient; |
107 |
loaded into emulated memory. |
no additional kernel filename needs to be supplied on the command line. |
108 |
|
.Pp |
109 |
|
3. For Dreamcast emulation, when booting e.g. a NetBSD/dreamcast CDROM |
110 |
|
image, it is enough to supply the disk image (with the correct ISO |
111 |
|
partition start offset). Bootblocks will be read directly from the CDROM |
112 |
|
image, and there is no need to supply the name of an external kernel on |
113 |
|
the command line. |
114 |
.Pp |
.Pp |
115 |
Gzipped kernels are automatically unzipped, by calling the external gunzip |
Gzipped kernels are automatically unzipped, by calling the external gunzip |
116 |
program, both when specifying a gzipped file directly on the command line |
program, both when specifying a gzipped file directly on the command line |
167 |
(The number of cylinders is calculated automatically.) |
(The number of cylinders is calculated automatically.) |
168 |
.It i |
.It i |
169 |
IDE. (This is the default for most machine types.) |
IDE. (This is the default for most machine types.) |
170 |
|
.It oOFS; |
171 |
|
Set the base offset for an ISO9660 filesystem on a disk image. The default |
172 |
|
is 0. A suitable offset when booting from Dreamcast ISO9660 filesystem |
173 |
|
images, which are offset by 11702 sectors, is 23965696. |
174 |
.It r |
.It r |
175 |
Read-only (don't allow changes to be written to the file). |
Read-only (don't allow changes to be written to the file). |
176 |
.It s |
.It s |
177 |
SCSI. |
SCSI. |
178 |
.It t |
.It t |
179 |
Tape. |
Tape. |
180 |
|
.It V |
181 |
|
Add an overlay filename to an already defined disk image. |
182 |
|
(A ID number must also be specified when this flag is used. See the |
183 |
|
documentation for an example of how to use overlays.) |
184 |
.It 0-7 |
.It 0-7 |
185 |
Force a specific ID number. |
Force a specific ID number. |
186 |
.El |
.El |
209 |
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 |
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 G Ar port |
.It Fl I Ar hz |
213 |
Pause at startup, and listen to TCP port |
Set the main CPU's frequency to |
214 |
.Ar port |
.Ar hz |
215 |
for incoming remote GDB connections. The emulator starts up in paused |
Hz. This option does not work for all emulated machine modes. It affects |
216 |
mode, and it is up to the remote GDB instance to start the session. |
the way count/compare interrupts are faked to simulate emulated time = |
217 |
.It Fl I Ar x |
real world time. If the guest operating system relies on RTC interrupts |
218 |
Emulate clock interrupts at |
instead of count/compare interrupts, then this option has no effect. |
219 |
.Ar x |
.Pp |
220 |
Hz. (This affects emulated clock devices only, not actual runtime speed. |
Setting the frequency to zero disables automatic synchronization of |
221 |
This disables automatic clock adjustments, which is otherwise turned on.) |
emulated time vs real world time, and the count/compare system runs at a |
222 |
(This option is probably only valid for DECstation emulation.) |
fixed rate. |
223 |
.It Fl i |
.It Fl i |
224 |
Enable instruction trace, i.e. display disassembly of each instruction as |
Enable instruction trace, i.e. display disassembly of each instruction as |
225 |
it is being executed. |
it is being executed. |
316 |
Overwrite the file, instead of appending to it. |
Overwrite the file, instead of appending to it. |
317 |
.El |
.El |
318 |
.Pp |
.Pp |
319 |
.\" Statistics gathering can be enabled/disabled at runtime by using the |
Statistics gathering can be enabled/disabled at runtime by using the |
320 |
.\" "TODO" debugger command. |
"statistics_enabled = yes" and "statistics_enabled = no" debugger |
321 |
.\" .Pp |
commands. |
322 |
|
.Pp |
323 |
When gathering instruction statistics using the |
When gathering instruction statistics using the |
324 |
.Fl s |
.Fl s |
325 |
option, instruction combinations are always disabled (i.e. |
option, instruction combinations and native code generation |
326 |
an implicit |
are always disabled (i.e. implicit |
327 |
.Fl J |
.Fl J |
328 |
is added to the command line). |
and |
329 |
.Pp |
.Fl B |
330 |
If a value is missing (e.g. the end-of-page slot does not really have a |
flags are added to the command line). |
331 |
known physical address), it is written out as just a dash ("-"). |
.It Fl T |
332 |
|
Halt if the emulated program attempts to access non-existing memory. |
333 |
.It Fl t |
.It Fl t |
334 |
Show a trace tree of all function calls being made. |
Show a trace tree of all function calls being made. |
335 |
.It Fl U |
.It Fl U |
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 |
390 |
|
Enable native code generation at runtime. This is not really implemented |
391 |
|
yet. Don't use it unless you know what you are doing. It will most |
392 |
|
likely not work. |
393 |
|
.It Fl B |
394 |
|
Disable native code generation at runtime. This is the default in this |
395 |
|
release of GXemul. |
396 |
.It Fl c Ar cmd |
.It Fl c Ar cmd |
397 |
Add |
Add |
398 |
.Ar cmd |
.Ar cmd |
401 |
.Fl V |
.Fl V |
402 |
option, and entering the commands manually. |
option, and entering the commands manually. |
403 |
.It Fl D |
.It Fl D |
404 |
Guarantee fully deterministic behavior. Normally, the emulator calls |
Causes the emulator to skip a call to srandom(). This leads to somewhat |
405 |
srandom() with a seed based on the current time at startup. When the |
more deterministic behaviour than running without this option. |
406 |
.Fl D |
However, if the emulated machine has clocks or timer interrupt sources, |
407 |
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 |
408 |
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.) |
|
409 |
.It Fl H |
.It Fl H |
410 |
Display a list of available CPU types, machine types, and userland |
Display a list of available CPU types, machine types, and userland |
411 |
emulation modes. (Most of these don't work. Please read the documentation |
emulation modes. (Most of these don't work. Please read the documentation |
416 |
yet.) |
yet.) |
417 |
.It Fl h |
.It Fl h |
418 |
Display a list of all available command line options. |
Display a list of all available command line options. |
419 |
|
.It Fl k Ar n |
420 |
|
Set the size of the dyntrans cache (per emulated CPU) to |
421 |
|
.Ar n |
422 |
|
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 |
489 |
.Nm |
.Nm |
490 |
source distribution, some are marked as TODO in the source code itself. |
source distribution, some are marked as TODO in the source code itself. |
491 |
.Pp |
.Pp |
492 |
Userland (syscall-only) emulation doesn't really work yet. |
Userland (syscall-only) emulation, i.e. running a userland binary directly |
493 |
.Pp |
without simulating an entire machine, doesn't really work yet. |
|
The documentation sometimes only reflects the way things worked with |
|
|
the old MIPS emulation mode (prior to 0.4.0), and it is incorrect when |
|
|
applied to current releases. |
|
494 |
.Pp |
.Pp |
495 |
.Nm |
.Nm |
496 |
is in general not cycle-accurate; it does not simulate individual |
is in general not cycle-accurate; it does not simulate individual |
499 |
real-world processor. |
real-world processor. |
500 |
.Pp |
.Pp |
501 |
.Nm |
.Nm |
502 |
is not timing-accurate, i.e. clocks inside the emulator are in general |
is in general not timing-accurate. Many emulation modes try to make the |
503 |
not at all synched with clocks in the real world. There are a few |
guest operating system's clock run at the same speed as the host clock. |
504 |
exceptions to this rule (the mc146818 device tries to automagically |
However, the number of instructions executed per clock tick can |
505 |
adjust emulated timer ticks to actual emulation speed). |
obviously vary, depending on the current CPU load on the host. |
506 |
.Sh AUTHOR |
.Sh AUTHOR |
507 |
GXemul is Copyright (C) 2003-2006 Anders Gavare <anders@gavare.se> |
GXemul is Copyright (C) 2003-2007 Anders Gavare <anders@gavare.se> |
508 |
.Pp |
.Pp |
509 |
See http://gavare.se/gxemul/ for more information. For other Copyright |
See http://gavare.se/gxemul/ for more information. For other Copyright |
510 |
messages, see the corresponding parts of the source code and/or |
messages, see the corresponding parts of the source code and/or |