1 |
.\" $Id: gxemul.1,v 1.12 2005/04/07 16:00:24 debug Exp $ |
.\" $Id: gxemul.1,v 1.69 2006/08/11 17:43:29 debug Exp $ |
2 |
.\" |
.\" |
3 |
.\" Copyright (C) 2004-2005 Anders Gavare. All rights reserved. |
.\" Copyright (C) 2004-2006 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 APRIL 2005 |
.Dd AUGUST 2006 |
33 |
.Dt GXEMUL 1 |
.Dt GXEMUL 1 |
34 |
.Os |
.Os |
35 |
.Sh NAME |
.Sh NAME |
41 |
.Op file Ar ... |
.Op file Ar ... |
42 |
.Nm |
.Nm |
43 |
.Op general options |
.Op general options |
44 |
.Op Ar @configfile ... |
.Ar @configfile |
45 |
.Nm |
.\" TODO: Reenable this once userland emulation works: |
46 |
.Op userland, other, and general options |
.\" .Nm |
47 |
.Ar file Op Ar args ... |
.\" .Op userland, other, and general options |
48 |
|
.\" .Ar file Op Ar args ... |
49 |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
50 |
.Nm |
.Nm |
51 |
is an experimental instruction-level machine emulator. It can be used |
is an experimental instruction-level machine emulator. Several |
52 |
to run binary code for (among others) MIPS-based machines. |
emulation modes are available. In some modes, processors and surrounding |
53 |
Several emulation modes are available. For some emulation modes, processors |
hardware components are emulated well enough to let unmodified operating |
54 |
and surrounding hardware components are emulated well enough to let |
systems (e.g. NetBSD) run inside the emulator as if they were running on a |
|
unmodified operating systems (eg NetBSD) run as if they were running on a |
|
55 |
real machine. |
real machine. |
56 |
.Pp |
.Pp |
57 |
There are three ways to invoke the emulator. When emulating a |
Processors (ARM, MIPS, PowerPC) are emulated using dynamic translation. |
58 |
complete machine, settings can be entered directly on the command line, or |
However, unlike some other dynamically translating emulators, GXemul does |
59 |
they can be read from a configuration file. When emulating a userland |
not currently generate native code, only a "runnable intermediate |
60 |
environment (syscall-only emulation, not emulating complete machines), |
representation", and will thus run on any host architecture, without the |
61 |
then the program name and its argument should be given on the command |
need to implement per-architecture backends. |
62 |
line. |
.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 |
.Pp |
75 |
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 |
76 |
command line. The most important thing you need to supply is the |
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, 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. |
80 |
.Pp |
.Pp |
89 |
.Fl H |
.Fl H |
90 |
to get a list of available emulation modes. |
to get a list of available emulation modes. |
91 |
.Pp |
.Pp |
92 |
(There is an exception to the normal invocation usage mentioned above; |
There are two exceptions to the normal invocation usage mentioned above. |
93 |
if you want to use the DECstation emulation mode, and have a bootable |
The first is for DECstation emulation: if you have a bootable |
94 |
DECstation harddisk or CDROM image, then just supplying the diskimage via |
DECstation harddisk or CDROM image, then just supplying the diskimage via |
95 |
the |
the |
96 |
.Fl d |
.Fl d |
97 |
option is sufficient. The filename of the kernel can then be |
option is sufficient. (The filename of the kernel can then be |
98 |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
skipped, as the emulator runs the bootblocks from the diskimage directly and |
99 |
doesn't need the kernel as a separate file.) |
doesn't need the kernel as a separate file.) |
100 |
|
The second is if you supply an ISO9660 CDROM disk image. You may then use |
101 |
|
the |
102 |
|
.Fl j |
103 |
|
option to indicate which file on the CDROM filesystem that should be |
104 |
|
loaded into emulated memory. |
105 |
|
.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 |
.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 |
115 |
Try to emulate machine type |
Try to emulate machine type |
116 |
.Ar "t". |
.Ar "t". |
117 |
|
This option is not always needed, if the |
118 |
|
.Fl e |
119 |
|
option uniquely selects a machine. |
120 |
(Use |
(Use |
121 |
.Fl H |
.Fl H |
122 |
to get a list of types.) |
to get a list of types.) |
130 |
.Pp |
.Pp |
131 |
Other options: |
Other options: |
132 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
|
.It Fl B |
|
|
Disable dynamic binary translation completely. By default, bintrans |
|
|
will be turned on if the host architecture supports it. |
|
|
However, in this release (0.3.1), there is no new bintrans system. |
|
|
If you want to enable binary translation, use |
|
|
.Fl "b". |
|
|
.It Fl b |
|
|
Use the OLD binary translation subsystem. (Alpha and i386 hosts only.) |
|
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". |
137 |
(Use |
(Use |
138 |
.Fl H |
.Fl H |
139 |
to get a list of available CPU types.) |
to get a list of available CPU types.) |
140 |
.It Fl d Ar name |
.It Fl d Ar [modifiers:]filename |
141 |
Add |
Add |
142 |
.Ar name |
.Ar filename |
143 |
as a disk image. By adding one or more modifier characters and then a |
as a disk image. By adding one or more modifier characters and then a |
144 |
colon (":") as a prefix to |
colon (":") as a prefix to |
145 |
.Ar "name", |
.Ar filename, |
146 |
you can modify the disk image's behaviour. Available modifiers are: |
you can modify the way the disk image is treated. Available modifiers are: |
147 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
148 |
.It b |
.It b |
149 |
Specifies that this is a boot device. |
Specifies that this is a boot device. |
150 |
.It c |
.It c |
151 |
CD-ROM (instead of a normal SCSI DISK). |
CD-ROM. |
152 |
.It d |
.It d |
153 |
SCSI DISK (this is the default). |
DISK (this is the default). |
154 |
|
.It f |
155 |
|
FLOPPY. |
156 |
|
.It gH;S; |
157 |
|
Override the default geometry; use H heads and S sectors-per-track. |
158 |
|
(The number of cylinders is calculated automatically.) |
159 |
.It i |
.It i |
160 |
IDE (instead of SCSI). |
IDE. (This is the default for most machine types.) |
161 |
.It r |
.It r |
162 |
Read-only (don't allow changes to be written to the file). |
Read-only (don't allow changes to be written to the file). |
163 |
|
.It s |
164 |
|
SCSI. |
165 |
.It t |
.It t |
166 |
SCSI tape. |
Tape. |
167 |
.It 0-7 |
.It 0-7 |
168 |
Force a specific SCSI ID number. |
Force a specific ID number. |
169 |
.El |
.El |
170 |
.Pp |
.Pp |
171 |
Filenames ending with ".iso" are assumed to be CDROM images, all others |
For SCSI devices, the ID number is the SCSI ID. For IDE harddisks, the ID |
172 |
are assumed to be normal SCSI disks. |
number has the following meaning: |
173 |
|
.Bl -tag -width Ds |
174 |
|
.It 0 |
175 |
|
Primary master. |
176 |
|
.It 1 |
177 |
|
Primary slave. |
178 |
|
.It 2 |
179 |
|
Secondary master. |
180 |
|
.It 3 |
181 |
|
Secondary slave. |
182 |
|
.El |
183 |
|
.Pp |
184 |
|
Unless otherwise specified, filenames ending with ".iso" or ".cdr" are |
185 |
|
assumed to be CDROM images. Most others are assumed to be disks. Depending |
186 |
|
on which machine is being emulated, the default for disks can be either |
187 |
|
SCSI or IDE. Some disk images that are very small are assumed to be floppy |
188 |
|
disks. (If you are not happy with the way a disk image is detected, then |
189 |
|
you need to use explicit prefixes to force a specific type.) |
190 |
|
.Pp |
191 |
|
For floppies, the gH;S; prefix is ignored. Instead, the number of |
192 |
|
heads and cylinders are assumed to be 2 and 80, respectively, and the |
193 |
|
number of sectors per track is calculated automatically. (This works for |
194 |
|
720KB, 1.2MB, 1.44MB, and 2.88MB floppies.) |
195 |
|
.It Fl G Ar port |
196 |
|
Pause at startup, and listen to TCP port |
197 |
|
.Ar port |
198 |
|
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. |
200 |
.It Fl I Ar x |
.It Fl I Ar x |
201 |
Emulate clock interrupts at |
Emulate clock interrupts at |
202 |
.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. |
Disable instruction combinations in the dynamic translator. |
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". |
214 |
Useful names are "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix. |
When booting from an ISO9660 filesystem, the emulator will try to boot |
215 |
("netbsd" is usually the default value.) |
using this file. (In some emulation modes, eg. DECstation, this name is passed |
216 |
|
along to the boot program. Useful names are "bsd" for OpenBSD/pmax, |
217 |
|
"vmunix" for Ultrix, or "vmsprite" for Sprite.) |
218 |
.It Fl M Ar m |
.It Fl M Ar m |
219 |
Emulate |
Emulate |
220 |
.Ar m |
.Ar m |
221 |
MBs of physical RAM. This overrides the default amount of RAM for the |
MBs of physical RAM. This overrides the default amount of RAM for the |
222 |
selected machine type. |
selected machine type. |
|
.It Fl m Ar nr |
|
|
Run at most |
|
|
.Ar nr |
|
|
instructions (on any cpu). |
|
223 |
.It Fl N |
.It Fl N |
224 |
Display nr of instructions/second average, at regular intervals. |
Display the number of executed instructions per second on average, at |
225 |
|
regular intervals. |
226 |
.It Fl n Ar nr |
.It Fl n Ar nr |
227 |
Set nr of CPUs (for SMP experiments). |
Set the number of processors in the machine, for SMP experiments. |
228 |
|
.Pp |
229 |
|
Note 1: The emulator allocates quite a lot of virtual memory for |
230 |
|
per-CPU translation tables. On 64-bit hosts, this is normally not a |
231 |
|
problem. On 32-bit hosts, this can use up all available virtual userspace |
232 |
|
memory. The solution is to either run the emulator on a 64-bit host, |
233 |
|
or limit the number of emulated CPUs to a reasonably low number. |
234 |
|
.Pp |
235 |
|
Note 2: SMP simulation is not working very well yet; multiple processors |
236 |
|
are simulated, but synchronization between the processors does not map |
237 |
|
very well to how real-world SMP systems work. |
238 |
.It Fl O |
.It Fl O |
239 |
Force a "netboot" (tftp instead of disk), even when a disk image is |
Force a "netboot" (tftp instead of disk), even when a disk image is |
240 |
present (for DECstation, SGI, and ARC emulation). |
present (for DECstation, SGI, and ARC emulation). |
241 |
.It Fl o Ar arg |
.It Fl o Ar arg |
242 |
Set the boot argument (for DEC, ARC, or SGI emulation). |
Set the boot argument (mostly useful for DEC, ARC, or SGI emulation). |
243 |
Default |
Default |
244 |
.Ar arg |
.Ar arg |
245 |
for DEC is '-a', for ARC '-aN'. |
for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A". |
246 |
.It Fl p Ar pc |
.It Fl p Ar pc |
247 |
Add a breakpoint (remember to use the '0x' prefix for hex). |
Add a breakpoint. |
248 |
|
.Ar pc |
249 |
|
can be a symbol, or a numeric value. (Remember to use the "0x" prefix for |
250 |
|
hexadecimal values.) |
251 |
.It Fl Q |
.It Fl Q |
252 |
Disable the built-in PROM emulation. This is useful for running raw ROM |
Disable the built-in (software-only) PROM emulation. This option is useful |
253 |
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 |
264 |
Initialize the emulated RAM to random data, instead of zeroes. |
Initialize emulated RAM to random data, instead of zeroes. This option |
265 |
.It Fl T |
is useful when trying to trigger bugs in a program that occur because the |
266 |
Enter the single-step debugger on unimplemented memory accesses. |
program assumed that uninitialized memory contains zeros. (Use with |
267 |
|
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 |
317 |
Enable slow_serial_interrupts_hack_for_linux. |
Enable slow_serial_interrupts_hack_for_linux. |
318 |
.It Fl X |
.It Fl X |
319 |
Use X11. |
Use X11. This option enables graphical framebuffers. |
320 |
.It Fl x |
.It Fl x |
321 |
Open up new xterms for emulated serial ports. (Default is to open up |
Open up new xterms for emulated serial ports. The default behaviour is to |
322 |
xterms when using configuration files, but not when starting an |
open up xterms when using configuration files, or if X11 is enabled. When |
323 |
emulation with settings directly on the command line.) |
starting up a simple emulation session with settings directly on the |
324 |
|
command line, and neither |
325 |
|
.Fl X |
326 |
|
nor |
327 |
|
.Fl x |
328 |
|
is used, then all output is confined to the terminal that |
329 |
|
.Nm |
330 |
|
started in. |
331 |
.It Fl Y Ar n |
.It Fl Y Ar n |
332 |
Scale down framebuffer windows by |
Scale down framebuffer windows by |
333 |
.Ar n |
.Ar n |
334 |
x |
x |
335 |
.Ar n |
.Ar n |
336 |
times. |
times. This option is useful when emulating a very large framebuffer, and |
337 |
.It Fl y Ar x |
the actual display is of lower resolution. If |
338 |
Set max_random_cycles_per_chunk to |
.Ar n |
339 |
.Ar x |
is negative, then there will be no scaledown, but emulation of certain |
340 |
(experimental). |
graphic controllers will be scaled up |
341 |
|
by |
342 |
|
.Ar -n |
343 |
|
times instead. E.g. Using |
344 |
|
.Ar -2 |
345 |
|
with VGA text mode emulation will result in 80x25 character cells rendered |
346 |
|
in a 1280x800 window, instead of the normal resolution of 640x400. |
347 |
.It Fl Z Ar n |
.It Fl Z Ar n |
348 |
Set the number of graphics cards, for emulating a dual-head or tripple-head |
Set the number of graphics cards, for emulating a dual-head or tripple-head |
349 |
environment. (Only for DECstation emulation so far.) |
environment. (Only for DECstation emulation so far.) |
353 |
as an X11 display to use for framebuffers. |
as an X11 display to use for framebuffers. |
354 |
.El |
.El |
355 |
.Pp |
.Pp |
356 |
Userland options: |
.\" Userland options: |
357 |
.Bl -tag -width Ds |
.\" .Bl -tag -width Ds |
358 |
.It Fl u Ar emul-mode |
.\" .It Fl u Ar emul-mode |
359 |
Userland-only (syscall) emulation. (Use |
.\" Userland-only (syscall) emulation. (Use |
360 |
.Fl H |
.\" .Fl H |
361 |
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 |
362 |
options listed under Other options above can also be used with userland |
.\" options listed under Other options above can also be used with |
363 |
emulation. |
.\" userland emulation. |
364 |
.El |
.\" .El |
365 |
.Pp |
.\" .Pp |
366 |
General options: |
General options: |
367 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
368 |
|
.It Fl c Ar cmd |
369 |
|
Add |
370 |
|
.Ar cmd |
371 |
|
as a command to run before starting the simulation. A similar effect can |
372 |
|
be achieved by using the |
373 |
|
.Fl V |
374 |
|
option, and entering the commands manually. |
375 |
.It Fl D |
.It Fl D |
376 |
Guarantee fully deterministic behaviour. Normally, the emulator calls |
Guarantee fully deterministic behavior. Normally, the emulator calls |
377 |
srandom() with a seed based on the current time at startup. When the |
srandom() with a seed based on the current time at startup. When the |
378 |
.Fl D |
.Fl D |
379 |
option is used, the srandom() call is skipped, which should cause two |
option is used, the srandom() call is skipped, which should cause two |
380 |
subsequent invokations of the emulator to be identical, if all other |
subsequent invocations of the emulator to be identical, if all other |
381 |
settings are identical. (If this option is used, then |
settings are identical and no user input is taking place. (If this option |
382 |
|
is used, then |
383 |
.Fl I |
.Fl I |
384 |
must also be used.) |
must also be used.) |
385 |
.It Fl H |
.It Fl H |
387 |
emulation modes. (Most of these don't work. Please read the documentation |
emulation modes. (Most of these don't work. Please read the documentation |
388 |
included in the |
included in the |
389 |
.Nm |
.Nm |
390 |
distribution for details on which modes that actually work.) |
distribution for details on which modes that actually work. Userland |
391 |
|
emulation is not included in stable release builds, since it doesn't work |
392 |
|
yet.) |
393 |
.It Fl h |
.It Fl h |
394 |
Display a list of all available command line options. |
Display a list of all available command line options. |
395 |
.It Fl K |
.It Fl K |
396 |
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. |
397 |
.It Fl q |
.It Fl q |
398 |
Quiet mode; this suppresses startup messages. |
Quiet mode; this suppresses startup messages. |
399 |
.It Fl s |
.\".It Fl s |
400 |
Show opcode usage statistics after the simulation. |
.\"For MIPS emulation: Show opcode usage statistics after the simulation. |
401 |
|
.\"For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file |
402 |
|
.\"at regular intervals of which physical addresses that were executed. |
403 |
.It Fl V |
.It Fl V |
404 |
Start up in the single-step debugger, paused. |
Start up in the single-step debugger, paused. |
405 |
.It Fl v |
.It Fl v |
406 |
Verbose debug messages. |
Increase verbosity (show more debug messages). This option can be used |
407 |
|
multiple times. |
408 |
.El |
.El |
409 |
.Pp |
.Pp |
410 |
Configuration file startup: |
Configuration file startup: |
420 |
distribution. |
distribution. |
421 |
.Sh EXAMPLES |
.Sh EXAMPLES |
422 |
The following command will start NetBSD/pmax on an emulated DECstation |
The following command will start NetBSD/pmax on an emulated DECstation |
423 |
5000/200 (3MAX), with the old bintrans system enabled: |
5000/200 (3MAX): |
424 |
.Pp |
.Pp |
425 |
.Dl "gxemul -E dec -e 3max -b -d netbsddisk.img" |
.Dl "gxemul -e 3max -d nbsd_pmax.img" |
426 |
.Pp |
.Pp |
427 |
netbsddisk.img should be a raw disk image containing a bootable |
nbsd_pmax.img should be a raw disk image containing a bootable |
428 |
NetBSD/pmax filesystem. |
NetBSD/pmax filesystem. |
429 |
.Pp |
.Pp |
430 |
The following command will start an emulation session based on settings in |
The following command will start an emulation session based on settings in |
440 |
.Pp |
.Pp |
441 |
.Dl "gxemul -E testmips -V hello_mips" |
.Dl "gxemul -E testmips -V hello_mips" |
442 |
.Pp |
.Pp |
443 |
(Paused mode means that you enter the interactive single-step debugger |
Paused mode means that you enter the interactive single-step debugger |
444 |
directly at startup, instead of launching the Hello World program.) |
directly at startup, instead of launching the Hello World program. |
445 |
|
.Pp |
446 |
|
The paused mode is also what should be used when running "unknown" files |
447 |
|
for the first time in the emulator. E.g. if you have a binary which you |
448 |
|
think is some kind of MIPS ROM image, then you can try the following: |
449 |
|
.Pp |
450 |
|
.Dl "gxemul -vv -E baremips -V 0xbfc00000:image.raw" |
451 |
|
.Pp |
452 |
|
You can then use the single-stepping functionality of the built-in |
453 |
|
debugger to run the code in the ROM image, to see how it behaves. Based on |
454 |
|
that, you can deduce what machine type it was actually from (the |
455 |
|
baremips machine is not a real machine), and perhaps try again with |
456 |
|
another emulation mode. |
457 |
|
.Pp |
458 |
|
In general, however, real ROM images require much more emulation detail |
459 |
|
than GXemul provides, so they can usually not run. |
460 |
.Pp |
.Pp |
461 |
Please read the documentation for more details. |
Please read the documentation for more details. |
462 |
.Sh BUGS |
.Sh BUGS |
463 |
There are many bugs. Some of the known bugs are listed in the BUGS |
There are many bugs. Some of the known bugs are mentioned in the TODO |
464 |
file in the |
file in the |
465 |
.Nm |
.Nm |
466 |
source distribution, some are indirectly mentioned in the TODO file. |
source distribution, some are marked as TODO in the source code itself. |
467 |
.Pp |
.Pp |
468 |
There is no new bintrans system in this release (0.3.1), so you will |
Userland (syscall-only) emulation doesn't really work yet. |
469 |
need to add |
.Pp |
470 |
.Fl b |
The documentation sometimes only reflects the way things worked with |
471 |
to select the old bintrans system, if you want speed. |
the old MIPS emulation mode (prior to 0.4.0), and it is incorrect when |
472 |
|
applied to current releases. |
473 |
|
.Pp |
474 |
|
.Nm |
475 |
|
is in general not cycle-accurate; it does not simulate individual |
476 |
|
pipe-line stages or penalties caused by branch-prediction misses or |
477 |
|
cache misses, so it cannot be used for accurate simulation of any actual |
478 |
|
real-world processor. |
479 |
.Pp |
.Pp |
480 |
.Nm |
.Nm |
481 |
does not simulate individual pipe-line stages or penalties caused by |
is not timing-accurate, i.e. clocks inside the emulator are in general |
482 |
branch-prediction misses, so it cannot be used for accurate performance |
not at all synched with clocks in the real world. There are a few |
483 |
measurement. |
exceptions to this rule (the mc146818 device tries to automagically |
484 |
|
adjust emulated timer ticks to actual emulation speed). |
485 |
.Sh AUTHOR |
.Sh AUTHOR |
486 |
Anders Gavare <anders@gavare.se> |
GXemul is Copyright (C) 2003-2006 Anders Gavare <anders@gavare.se> |
487 |
.Pp |
.Pp |
488 |
See http://gavare.se/gxemul/ for more information. |
See http://gavare.se/gxemul/ for more information. For other Copyright |
489 |
|
messages, see the corresponding parts of the source code and/or |
490 |
|
documentation. |