1 |
.\" $Id: gxemul.1,v 1.65 2006/06/22 13:22:40 debug Exp $ |
.\" $Id: gxemul.1,v 1.68 2006/07/16 13:32:24 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 JULY 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) 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". |
204 |
This disables automatic clock adjustments, which is otherwise turned on.) |
This disables automatic clock adjustments, which is otherwise turned on.) |
205 |
(This option is probably only valid for DECstation emulation.) |
(This option is probably only valid for DECstation emulation.) |
206 |
.It Fl i |
.It Fl i |
207 |
Display each instruction as it is being executed. |
Enable instruction trace, i.e. display disassembly of each instruction as |
208 |
|
it is being executed. |
209 |
.It Fl J |
.It Fl J |
210 |
Disable some speed tricks. This usually means disabling the use of |
Disable instruction combinations in the dynamic translator. |
|
dyntrans "instruction combinations". |
|
211 |
.It Fl j Ar n |
.It Fl j Ar n |
212 |
Set the name of the kernel to |
Set the name of the kernel to |
213 |
.Ar "n". |
.Ar "n". |
226 |
.It Fl n Ar nr |
.It Fl n Ar nr |
227 |
Set the number of processors in the machine, for SMP experiments. |
Set the number of processors in the machine, for SMP experiments. |
228 |
.Pp |
.Pp |
229 |
Note: The emulator allocates quite a |
Note 1: The emulator allocates quite a lot of virtual memory for |
230 |
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 |
231 |
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 |
232 |
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, |
233 |
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). |
|
234 |
.Pp |
.Pp |
235 |
Note 2: SMP simulation is not working very well yet; multiple processors |
Note 2: SMP simulation is not working very well yet; multiple processors |
236 |
are simulated, but synchronization between the processors does not map |
are simulated, but synchronization between the processors does not map |
249 |
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 |
250 |
hexadecimal values.) |
hexadecimal values.) |
251 |
.It Fl Q |
.It Fl Q |
252 |
Disable the built-in PROM emulation. This is useful for |
Disable the built-in (software-only) PROM emulation. This option is useful |
253 |
experimenting with running raw ROM images from real machines. |
for experimenting with running raw ROM images from real machines. The default |
254 |
|
behaviour of the emulator is to "fake" certain PROM calls used by guest |
255 |
|
operating systems (e.g. NetBSD), so that no real PROM image is needed. |
256 |
.It Fl R |
.It Fl R |
257 |
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 |
258 |
|
meaningful together with the |
259 |
|
.Fl n |
260 |
|
option.) |
261 |
.It Fl r |
.It Fl r |
262 |
Dump register contents for every executed instruction. |
Dump register contents for every executed instruction. |
263 |
.It Fl S |
.It Fl S |
265 |
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 |
266 |
program assumed that uninitialized memory contains zeros. (Use with |
program assumed that uninitialized memory contains zeros. (Use with |
267 |
care.) |
care.) |
268 |
|
.It Fl s Ar flags:filename |
269 |
|
Gather statistics based on the current emulated program counter value, |
270 |
|
while the program executes. The statistics is actually just a raw dump of |
271 |
|
all program counter values in sequence, suitable for post-analysis with |
272 |
|
separate tools. Output is appended to |
273 |
|
.Ar filename. |
274 |
|
.Pp |
275 |
|
The |
276 |
|
.Ar flags |
277 |
|
should include one or more of the following type specifiers: |
278 |
|
.Bl -tag -width Ds |
279 |
|
.It v |
280 |
|
Virtual. This means that the program counter value is used. |
281 |
|
.It p |
282 |
|
Physical. This means that the physical address of where the program |
283 |
|
is actually running is used. |
284 |
|
.It i |
285 |
|
Instruction call. This type of statistics gathering is practically only |
286 |
|
useful during development of the emulator itself. The output is a list of |
287 |
|
addresses of instruction call functions (ic->f), which after some |
288 |
|
post-processing can be used as a basis for deciding when to implement |
289 |
|
instruction combinations. |
290 |
|
.El |
291 |
|
.Pp |
292 |
|
The |
293 |
|
.Ar flags |
294 |
|
may also include the following optional modifiers: |
295 |
|
.Bl -tag -width Ds |
296 |
|
.It d |
297 |
|
Disabled at startup. |
298 |
|
.It o |
299 |
|
Overwrite the file, instead of appending to it. |
300 |
|
.El |
301 |
|
.Pp |
302 |
|
.\" Statistics gathering can be enabled/disabled at runtime by using the |
303 |
|
.\" "TODO" debugger command. |
304 |
|
.\" .Pp |
305 |
|
When gathering instruction statistics using the |
306 |
|
.Fl s |
307 |
|
option, instruction combinations are always disabled (i.e. |
308 |
|
an implicit |
309 |
|
.Fl J |
310 |
|
is added to the command line). |
311 |
|
.Pp |
312 |
|
If a value is missing (e.g. the end-of-page slot does not really have a |
313 |
|
known physical address), it is written out as just a dash ("-"). |
314 |
.It Fl t |
.It Fl t |
315 |
Show a trace tree of all function calls being made. |
Show a trace tree of all function calls being made. |
316 |
.It Fl U |
.It Fl U |