1 |
.\" $Id: gxemul.1,v 1.89 2007/04/10 15:37:00 debug Exp $ |
2 |
.\" |
3 |
.\" Copyright (C) 2004-2007 Anders Gavare. All rights reserved. |
4 |
.\" |
5 |
.\" Redistribution and use in source and binary forms, with or without |
6 |
.\" modification, are permitted provided that the following conditions are met: |
7 |
.\" |
8 |
.\" 1. Redistributions of source code must retain the above copyright |
9 |
.\" notice, this list of conditions and the following disclaimer. |
10 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
11 |
.\" notice, this list of conditions and the following disclaimer in the |
12 |
.\" documentation and/or other materials provided with the distribution. |
13 |
.\" 3. The name of the author may not be used to endorse or promote products |
14 |
.\" derived from this software without specific prior written permission. |
15 |
.\" |
16 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
17 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
18 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
19 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
20 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
21 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
22 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
23 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
24 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
25 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
26 |
.\" SUCH DAMAGE. |
27 |
.\" |
28 |
.\" |
29 |
.\" This is a minimal man page for GXemul. Process this file with |
30 |
.\" groff -man -Tascii gxemul.1 or nroff -man gxemul.1 |
31 |
.\" |
32 |
.Dd APRIL 2007 |
33 |
.Dt GXEMUL 1 |
34 |
.Os |
35 |
.Sh NAME |
36 |
.Nm gxemul |
37 |
.Nd an experimental machine emulator |
38 |
.Sh SYNOPSIS |
39 |
.Nm |
40 |
.Op machine, other, and general options |
41 |
.Op file Ar ... |
42 |
.Nm |
43 |
.Op general options |
44 |
.Ar @configfile |
45 |
.\" TODO: Reenable this once userland emulation works: |
46 |
.\" .Nm |
47 |
.\" .Op userland, other, and general options |
48 |
.\" .Ar file Op Ar args ... |
49 |
.Sh DESCRIPTION |
50 |
.Nm |
51 |
is an experimental instruction-level machine emulator. Several |
52 |
emulation modes are available. In some modes, processors and surrounding |
53 |
hardware components are emulated well enough to let unmodified operating |
54 |
systems (e.g. NetBSD) run inside the emulator as if they were running on a |
55 |
real machine. |
56 |
.Pp |
57 |
Processors (ARM, MIPS, PowerPC, SuperH) are emulated using dynamic translation. |
58 |
However, unlike some other dynamically translating emulators, GXemul does |
59 |
not need to generate native code, only a "runnable intermediate |
60 |
representation", and will thus run on any host architecture, without the |
61 |
need to implement per-architecture backends. |
62 |
.Pp |
63 |
The emulator can be invoked in the following ways: |
64 |
.Pp |
65 |
1. When emulating a complete machine, configuration options can be entered |
66 |
directly on the command line. |
67 |
.Pp |
68 |
2. Options can be read from a configuration file. |
69 |
.\" .Pp |
70 |
.\" 3. When emulating a userland environment (syscall-only emulation, not |
71 |
.\" emulating complete machines), then the program name and its argument |
72 |
.\" should be given on the command line. (This mode doesn't really work yet, |
73 |
.\" and is disabled for stable release builds.) |
74 |
.Pp |
75 |
The easiest way to use the emulator is to supply settings directly on the |
76 |
command line. 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, |
78 |
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. |
80 |
.Pp |
81 |
If more than one filename is supplied, all files are loaded into memory, |
82 |
and the entry point (if available) is taken from the last file. |
83 |
.Pp |
84 |
Apart from the name of a binary file, it is also necessary to select |
85 |
which specific emulation mode to use. For example, a MIPS-based machine |
86 |
from DEC (a DECstation) is very different from a MIPS-based machine |
87 |
from SGI. Use |
88 |
.Nm |
89 |
.Fl H |
90 |
to get a list of available emulation modes. |
91 |
.Pp |
92 |
There are three exceptions to the normal invocation usage mentioned above. |
93 |
.Pp |
94 |
1. For DECstation emulation, if you have a bootable DECstation harddisk or |
95 |
CDROM image, then just supplying the diskimage via the |
96 |
.Fl d |
97 |
option is sufficient. The filename of the kernel can then be |
98 |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
99 |
doesn't need the kernel as a separate file. |
100 |
.Pp |
101 |
2. If you supply an ISO9660 CDROM disk image, then using the |
102 |
.Fl j |
103 |
option to indicate a file on the CDROM filesystem to load is sufficient; |
104 |
no additional kernel filename needs to be supplied on the command line. |
105 |
.Pp |
106 |
3. For Dreamcast emulation, when booting e.g. a NetBSD/dreamcast CDROM |
107 |
image, it is enough to supply the disk image (with the correct ISO |
108 |
partition start offset). Bootblocks will be read directly from the CDROM |
109 |
image, and there is no need to supply the name of an external kernel on |
110 |
the command line. |
111 |
.Pp |
112 |
Gzipped kernels are automatically unzipped, by calling the external gunzip |
113 |
program, both when specifying a gzipped file directly on the command line |
114 |
and when loading such a file using the |
115 |
.Fl j |
116 |
option. |
117 |
.Pp |
118 |
Machine selection options: |
119 |
.Bl -tag -width Ds |
120 |
.It Fl E Ar t |
121 |
Try to emulate machine type |
122 |
.Ar "t". |
123 |
This option is not always needed, if the |
124 |
.Fl e |
125 |
option uniquely selects a machine. |
126 |
(Use |
127 |
.Fl H |
128 |
to get a list of types.) |
129 |
.It Fl e Ar st |
130 |
Try to emulate machine subtype |
131 |
.Ar "st". |
132 |
Use this together with |
133 |
.Fl E . |
134 |
(This option is not always needed, if a machine type has no subtypes.) |
135 |
.El |
136 |
.Pp |
137 |
Other options: |
138 |
.Bl -tag -width Ds |
139 |
.It Fl C Ar x |
140 |
Try to emulate a specific CPU type, |
141 |
.Ar "x". |
142 |
This overrides the default CPU type for the machine being emulated. |
143 |
(Use |
144 |
.Fl H |
145 |
to get a list of available CPU types.) |
146 |
.It Fl d Ar [modifiers:]filename |
147 |
Add |
148 |
.Ar filename |
149 |
as a disk image. By adding one or more modifier characters and then a |
150 |
colon (":") as a prefix to |
151 |
.Ar filename, |
152 |
you can modify the way the disk image is treated. Available modifiers are: |
153 |
.Bl -tag -width Ds |
154 |
.It b |
155 |
Specifies that this is a boot device. |
156 |
.It c |
157 |
CD-ROM. |
158 |
.It d |
159 |
DISK (this is the default). |
160 |
.It f |
161 |
FLOPPY. |
162 |
.It gH;S; |
163 |
Override the default geometry; use H heads and S sectors-per-track. |
164 |
(The number of cylinders is calculated automatically.) |
165 |
.It i |
166 |
IDE. (This is the default for most machine types.) |
167 |
.It oOFS; |
168 |
Set the base offset for an ISO9660 filesystem on a disk image. The default |
169 |
is 0. A suitable offset when booting from Dreamcast ISO9660 filesystem |
170 |
images, which are offset by 11702 sectors, is 23965696. |
171 |
.It r |
172 |
Read-only (don't allow changes to be written to the file). |
173 |
.It s |
174 |
SCSI. |
175 |
.It t |
176 |
Tape. |
177 |
.It V |
178 |
Add an overlay filename to an already defined disk image. |
179 |
(A ID number must also be specified when this flag is used. See the |
180 |
documentation for an example of how to use overlays.) |
181 |
.It 0-7 |
182 |
Force a specific ID number. |
183 |
.El |
184 |
.Pp |
185 |
For SCSI devices, the ID number is the SCSI ID. For IDE harddisks, the ID |
186 |
number has the following meaning: |
187 |
.Bl -tag -width Ds |
188 |
.It 0 |
189 |
Primary master. |
190 |
.It 1 |
191 |
Primary slave. |
192 |
.It 2 |
193 |
Secondary master. |
194 |
.It 3 |
195 |
Secondary slave. |
196 |
.El |
197 |
.Pp |
198 |
Unless otherwise specified, filenames ending with ".iso" or ".cdr" are |
199 |
assumed to be CDROM images. Most others are assumed to be disks. Depending |
200 |
on which machine is being emulated, the default for disks can be either |
201 |
SCSI or IDE. Some disk images that are very small are assumed to be floppy |
202 |
disks. (If you are not happy with the way a disk image is detected, then |
203 |
you need to use explicit prefixes to force a specific type.) |
204 |
.Pp |
205 |
For floppies, the gH;S; prefix is ignored. Instead, the number of |
206 |
heads and cylinders are assumed to be 2 and 80, respectively, and the |
207 |
number of sectors per track is calculated automatically. (This works for |
208 |
720KB, 1.2MB, 1.44MB, and 2.88MB floppies.) |
209 |
.It Fl I Ar hz |
210 |
Set the main CPUs frequency to |
211 |
.Ar hz |
212 |
Hz. This option does not work for all emulated machine modes. It affects |
213 |
the way count/compare interrupts are faked to simulate emulated time = |
214 |
real world time. If the guest operating system relies on RTC interrupts |
215 |
instead of count/compare interrupts, then this option has no effect. |
216 |
.Pp |
217 |
Setting the frequency to zero disables automatic synchronization of |
218 |
emulated time vs real world time, and the count/compare system runs at a |
219 |
fixed rate. |
220 |
.It Fl i |
221 |
Enable instruction trace, i.e. display disassembly of each instruction as |
222 |
it is being executed. |
223 |
.It Fl J |
224 |
Disable instruction combinations in the dynamic translator. |
225 |
.It Fl j Ar n |
226 |
Set the name of the kernel to |
227 |
.Ar "n". |
228 |
When booting from an ISO9660 filesystem, the emulator will try to boot |
229 |
using this file. (In some emulation modes, eg. DECstation, this name is passed |
230 |
along to the boot program. Useful names are "bsd" for OpenBSD/pmax, |
231 |
"vmunix" for Ultrix, or "vmsprite" for Sprite.) |
232 |
.It Fl M Ar m |
233 |
Emulate |
234 |
.Ar m |
235 |
MBs of physical RAM. This overrides the default amount of RAM for the |
236 |
selected machine type. |
237 |
.It Fl N |
238 |
Display the number of executed instructions per second on average, at |
239 |
regular intervals. |
240 |
.It Fl n Ar nr |
241 |
Set the number of processors in the machine, for SMP experiments. |
242 |
.Pp |
243 |
Note 1: The emulator allocates quite a lot of virtual memory for |
244 |
per-CPU translation tables. On 64-bit hosts, this is normally not a |
245 |
problem. On 32-bit hosts, this can use up all available virtual userspace |
246 |
memory. The solution is to either run the emulator on a 64-bit host, |
247 |
or limit the number of emulated CPUs to a reasonably low number. |
248 |
.Pp |
249 |
Note 2: SMP simulation is not working very well yet; multiple processors |
250 |
are simulated, but synchronization between the processors does not map |
251 |
very well to how real-world SMP systems work. |
252 |
.It Fl O |
253 |
Force a "netboot" (tftp instead of disk), even when a disk image is |
254 |
present (for DECstation, SGI, and ARC emulation). |
255 |
.It Fl o Ar arg |
256 |
Set the boot argument (mostly useful for DEC, ARC, or SGI emulation). |
257 |
Default |
258 |
.Ar arg |
259 |
for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A". |
260 |
.It Fl p Ar pc |
261 |
Add a breakpoint. |
262 |
.Ar pc |
263 |
can be a symbol, or a numeric value. (Remember to use the "0x" prefix for |
264 |
hexadecimal values.) |
265 |
.It Fl Q |
266 |
Disable the built-in (software-only) PROM emulation. This option is useful |
267 |
for experimenting with running raw ROM images from real machines. The default |
268 |
behaviour of the emulator is to "fake" certain PROM calls used by guest |
269 |
operating systems (e.g. NetBSD), so that no real PROM image is needed. |
270 |
.It Fl R |
271 |
Use a random bootstrap cpu, instead of CPU nr 0. (This option is only |
272 |
meaningful together with the |
273 |
.Fl n |
274 |
option.) |
275 |
.It Fl r |
276 |
Dump register contents for every executed instruction. |
277 |
.It Fl S |
278 |
Initialize emulated RAM to random data, instead of zeroes. This option |
279 |
is useful when trying to trigger bugs in a program that occur because the |
280 |
program assumed that uninitialized memory contains zeros. (Use with |
281 |
care.) |
282 |
.It Fl s Ar flags:filename |
283 |
Gather statistics based on the current emulated program counter value, |
284 |
while the program executes. The statistics is actually just a raw dump of |
285 |
all program counter values in sequence, suitable for post-analysis with |
286 |
separate tools. Output is appended to |
287 |
.Ar filename. |
288 |
.Pp |
289 |
The |
290 |
.Ar flags |
291 |
should include one or more of the following type specifiers: |
292 |
.Bl -tag -width Ds |
293 |
.It v |
294 |
Virtual. This means that the program counter value is used. |
295 |
.It p |
296 |
Physical. This means that the physical address of where the program |
297 |
is actually running is used. |
298 |
.It i |
299 |
Instruction call. This type of statistics gathering is practically only |
300 |
useful during development of the emulator itself. The output is a list of |
301 |
addresses of instruction call functions (ic->f), which after some |
302 |
post-processing can be used as a basis for deciding when to implement |
303 |
instruction combinations. |
304 |
.El |
305 |
.Pp |
306 |
The |
307 |
.Ar flags |
308 |
may also include the following optional modifiers: |
309 |
.Bl -tag -width Ds |
310 |
.It d |
311 |
Disabled at startup. |
312 |
.It o |
313 |
Overwrite the file, instead of appending to it. |
314 |
.El |
315 |
.Pp |
316 |
Statistics gathering can be enabled/disabled at runtime by using the |
317 |
"statistics_enabled = yes" and "statistics_enabled = no" debugger |
318 |
commands. |
319 |
.Pp |
320 |
When gathering instruction statistics using the |
321 |
.Fl s |
322 |
option, instruction combinations and native code generation |
323 |
are always disabled (i.e. implicit |
324 |
.Fl J |
325 |
and |
326 |
.Fl B |
327 |
flags are added to the command line). |
328 |
.Pp |
329 |
If a value is missing (e.g. the end-of-page slot does not really have a |
330 |
known physical address), it is written out as just a dash ("-"). |
331 |
.It Fl T |
332 |
Halt if the emulated program attempts to access non-existing memory. |
333 |
.It Fl t |
334 |
Show a trace tree of all function calls being made. |
335 |
.It Fl U |
336 |
Enable slow_serial_interrupts_hack_for_linux. |
337 |
.It Fl X |
338 |
Use X11. This option enables graphical framebuffers. |
339 |
.It Fl x |
340 |
Open up new xterms for emulated serial ports. The default behaviour is to |
341 |
open up xterms when using configuration files, or if X11 is enabled. When |
342 |
starting up a simple emulation session with settings directly on the |
343 |
command line, and neither |
344 |
.Fl X |
345 |
nor |
346 |
.Fl x |
347 |
is used, then all output is confined to the terminal that |
348 |
.Nm |
349 |
started in. |
350 |
.It Fl Y Ar n |
351 |
Scale down framebuffer windows by |
352 |
.Ar n |
353 |
x |
354 |
.Ar n |
355 |
times. This option is useful when emulating a very large framebuffer, and |
356 |
the actual display is of lower resolution. If |
357 |
.Ar n |
358 |
is negative, then there will be no scaledown, but emulation of certain |
359 |
graphic controllers will be scaled up |
360 |
by |
361 |
.Ar -n |
362 |
times instead. E.g. Using |
363 |
.Ar -2 |
364 |
with VGA text mode emulation will result in 80x25 character cells rendered |
365 |
in a 1280x800 window, instead of the normal resolution of 640x400. |
366 |
.It Fl Z Ar n |
367 |
Set the number of graphics cards, for emulating a dual-head or tripple-head |
368 |
environment. (Only for DECstation emulation so far.) |
369 |
.It Fl z Ar disp |
370 |
Add |
371 |
.Ar disp |
372 |
as an X11 display to use for framebuffers. |
373 |
.El |
374 |
.Pp |
375 |
.\" Userland options: |
376 |
.\" .Bl -tag -width Ds |
377 |
.\" .It Fl u Ar emul-mode |
378 |
.\" Userland-only (syscall) emulation. (Use |
379 |
.\" .Fl H |
380 |
.\" 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 |
382 |
.\" userland emulation. |
383 |
.\" .El |
384 |
.\" .Pp |
385 |
General options: |
386 |
.Bl -tag -width Ds |
387 |
.It Fl b |
388 |
Enable native code generation at runtime. This is not really implemented |
389 |
yet. Don't use it unless you know what you are doing. It will most |
390 |
likely not work. |
391 |
.It Fl B |
392 |
Disable native code generation at runtime. (This is the default in |
393 |
GXemul 0.4.4; there are no implemented native code generation backends.) |
394 |
.It Fl c Ar cmd |
395 |
Add |
396 |
.Ar cmd |
397 |
as a command to run before starting the simulation. A similar effect can |
398 |
be achieved by using the |
399 |
.Fl V |
400 |
option, and entering the commands manually. |
401 |
.It Fl D |
402 |
Causes the emulator to skip a call to srandom(). This leads to somewhat |
403 |
more deterministic behaviour than running without this option. |
404 |
However, if the emulated machine has clocks or timer interrupt sources, |
405 |
or if user interaction is taking place (e.g. keyboard input at irregular |
406 |
intervals), then this option is meaningless. |
407 |
.It Fl H |
408 |
Display a list of available CPU types, machine types, and userland |
409 |
emulation modes. (Most of these don't work. Please read the documentation |
410 |
included in the |
411 |
.Nm |
412 |
distribution for details on which modes that actually work. Userland |
413 |
emulation is not included in stable release builds, since it doesn't work |
414 |
yet.) |
415 |
.It Fl h |
416 |
Display a list of all available command line options. |
417 |
.It Fl k Ar n |
418 |
Set the size of the dyntrans cache (per emulated CPU) to |
419 |
.Ar n |
420 |
MB. The default size is 32 MB. |
421 |
.It Fl K |
422 |
Force the single-step debugger to be entered at the end of a simulation. |
423 |
.It Fl q |
424 |
Quiet mode; this suppresses startup messages. |
425 |
.\".It Fl s |
426 |
.\"For MIPS emulation: Show opcode usage statistics after the simulation. |
427 |
.\"For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file |
428 |
.\"at regular intervals of which physical addresses that were executed. |
429 |
.It Fl V |
430 |
Start up in the single-step debugger, paused. |
431 |
.It Fl v |
432 |
Increase verbosity (show more debug messages). This option can be used |
433 |
multiple times. |
434 |
.El |
435 |
.Pp |
436 |
Configuration file startup: |
437 |
.Bl -tag -width Ds |
438 |
.It @ Ar configfile |
439 |
Start an emulation based on the contents of |
440 |
.Ar "configfile". |
441 |
.El |
442 |
.Pp |
443 |
For more information, please read the documentation in the doc/ |
444 |
subdirectory of the |
445 |
.Nm |
446 |
distribution. |
447 |
.Sh EXAMPLES |
448 |
The following command will start NetBSD/pmax on an emulated DECstation |
449 |
5000/200 (3MAX): |
450 |
.Pp |
451 |
.Dl "gxemul -e 3max -d nbsd_pmax.img" |
452 |
.Pp |
453 |
nbsd_pmax.img should be a raw disk image containing a bootable |
454 |
NetBSD/pmax filesystem. |
455 |
.Pp |
456 |
The following command will start an emulation session based on settings in |
457 |
the configuration file "mysession". The -v option tells gxemul to be |
458 |
verbose. |
459 |
.Pp |
460 |
.Dl "gxemul -v @mysession" |
461 |
.Pp |
462 |
If you have compiled the small Hello World program mentioned in the |
463 |
.Nm |
464 |
documentation, the following command will start up an |
465 |
emulated test machine in "paused" mode: |
466 |
.Pp |
467 |
.Dl "gxemul -E testmips -V hello_mips" |
468 |
.Pp |
469 |
Paused mode means that you enter the interactive single-step debugger |
470 |
directly at startup, instead of launching the Hello World program. |
471 |
.Pp |
472 |
The paused mode is also what should be used when running "unknown" files |
473 |
for the first time in the emulator. E.g. if you have a binary which you |
474 |
think is some kind of MIPS ROM image, then you can try the following: |
475 |
.Pp |
476 |
.Dl "gxemul -vv -E baremips -V 0xbfc00000:image.raw" |
477 |
.Pp |
478 |
You can then use the single-stepping functionality of the built-in |
479 |
debugger to run the code in the ROM image, to see how it behaves. Based on |
480 |
that, you can deduce what machine type it was actually from (the |
481 |
baremips machine is not a real machine), and perhaps try again with |
482 |
another emulation mode. |
483 |
.Pp |
484 |
In general, however, real ROM images require much more emulation detail |
485 |
than GXemul provides, so they can usually not run. |
486 |
.Pp |
487 |
Please read the documentation for more details. |
488 |
.Sh BUGS |
489 |
There are many bugs. Some of the known bugs are mentioned in the TODO |
490 |
file in the |
491 |
.Nm |
492 |
source distribution, some are marked as TODO in the source code itself. |
493 |
.Pp |
494 |
Userland (syscall-only) emulation, i.e. running a userland binary directly |
495 |
without simulating an entire machine, doesn't really work yet. |
496 |
.Pp |
497 |
.Nm |
498 |
is in general not cycle-accurate; it does not simulate individual |
499 |
pipe-line stages or penalties caused by branch-prediction misses or |
500 |
cache misses, so it cannot be used for accurate simulation of any actual |
501 |
real-world processor. |
502 |
.Pp |
503 |
.Nm |
504 |
is in general not timing-accurate. Some emulation modes |
505 |
(DECstation, CATS, NetWinder, MobilePro (hpcmips), Malta (evbmips), |
506 |
Cobalt, Algor, Dreamcast, PICA-61, and IQ80321) try to make the guest |
507 |
operating system's clock run at the same speed as the host clock. |
508 |
However, the number of instructions executed per clock tick can |
509 |
obviously vary, depending on the current CPU load on the host. |
510 |
.Sh AUTHOR |
511 |
GXemul is Copyright (C) 2003-2007 Anders Gavare <anders@gavare.se> |
512 |
.Pp |
513 |
See http://gavare.se/gxemul/ for more information. For other Copyright |
514 |
messages, see the corresponding parts of the source code and/or |
515 |
documentation. |