/[gxemul]/trunk/man/gxemul.1
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /trunk/man/gxemul.1

Parent Directory Parent Directory | Revision Log Revision Log


Revision 28 - (show annotations)
Mon Oct 8 16:20:26 2007 UTC (13 years, 1 month ago) by dpavlin
File size: 17442 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.1298 2006/07/22 11:27:46 debug Exp $
20060626	Continuing on SPARC emulation (beginning on the 'save'
		instruction, register windows, etc).
20060629	Planning statistics gathering (new -s command line option),
		and renaming speed_tricks to allow_instruction_combinations.
20060630	Some minor manual page updates.
		Various cleanups.
		Implementing the -s command line option.
20060701	FINALLY found the bug which prevented Linux and Ultrix from
		running without the ugly hack in the R2000/R3000 cache isol
		code; it was the phystranslation hint array which was buggy.
		Removing the phystranslation hint code completely, for now.
20060702	Minor dyntrans cleanups; invalidation of physpages now only
		invalidate those parts of a page that have actually been
		translated. (32 parts per page.)
		Some MIPS non-R3000 speed fixes.
		Experimenting with MIPS instruction combination for some
		addiu+bne+sw loops, and sw+sw+sw.
		Adding support (again) for larger-than-4KB pages in MIPS tlbw*.
		Continuing on SPARC emulation: adding load/store instructions.
20060704	Fixing a virtual vs physical page shift bug in the new tlbw*
		implementation. Problem noticed by Jakub Jermar. (Many thanks.)
		Moving rfe and eret to cpu_mips_instr.c, since that is the
		only place that uses them nowadays.
20060705	Removing the BSD license from the "testmachine" include files,
		placing them in the public domain instead; this enables the
		testmachine stuff to be used from projects which are
		incompatible with the BSD license for some reason.
20060707	Adding instruction combinations for the R2000/R3000 L1
		I-cache invalidation code used by NetBSD/pmax 3.0, lui+addiu,
		various branches followed by addiu or nop, and jr ra followed
		by addiu. The time it takes to perform a full NetBSD/pmax R3000
		install on the laptop has dropped from 573 seconds to 539. :-)
20060708	Adding a framebuffer controller device (dev_fbctrl), which so
		far can be used to change the fb resolution during runtime, but
		in the future will also be useful for accelerated block fill/
		copy, and possibly also simplified character output.
		Adding an instruction combination for NetBSD/pmax' strlen.
20060709	Minor fixes: reading raw files in src/file.c wasn't memblock
		aligned, removing buggy multi_sw MIPS instruction combination,
		etc.
20060711	Adding a machine_qemu.c, which contains a "qemu_mips" machine.
		(It mimics QEMU's MIPS machine mode, so that a test kernel
		made for QEMU_MIPS also can run in GXemul... at least to some
		extent.)  Adding a short section about how to run this mode to
		doc/guestoses.html.
20060714	Misc. minor code cleanups.
20060715	Applying a patch which adds getchar() to promemul/yamon.c
		(from Oleksandr Tymoshenko).
		Adding yamon.h from NetBSD, and rewriting yamon.c to use it
		(instead of ugly hardcoded numbers) + some cleanup.
20060716	Found and fixed the bug which broke single-stepping of 64-bit
		programs between 0.4.0 and 0.4.0.1 (caused by too quick
		refactoring and no testing). Hopefully this fix will not
		break too many other things.
20060718	Continuing on the 8253 PIT; it now works with Linux/QEMU_MIPS.
		Re-adding the sw+sw+sw instr comb (the problem was that I had
		ignored endian issues); however, it doesn't seem to give any
		big performance gain.
20060720	Adding a dummy Transputer mode (T414, T800 etc) skeleton (only
		the 'j' and 'ldc' instructions are implemented so far). :-}
20060721	Adding gtreg.h from NetBSD, updating dev_gt.c to use it, plus
		misc. other updates to get Linux 2.6 for evbmips/malta working
		(thanks to Alec Voropay for the details).
		FINALLY found and fixed the bug which made tlbw* for non-R3000
		buggy; it was a reference count problem in the dyntrans core.
20060722	Testing stuff; things seem stable enough for a new release.

==============  RELEASE 0.4.1  ==============


1 .\" $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.
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 JULY 2006
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) are emulated using dynamic translation.
58 However, unlike some other dynamically translating emulators, GXemul does
59 not currently 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 two exceptions to the normal invocation usage mentioned above.
93 The first is for DECstation emulation: if you have a bootable
94 DECstation harddisk or CDROM image, then just supplying the diskimage via
95 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 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
112 Machine selection options:
113 .Bl -tag -width Ds
114 .It Fl E Ar t
115 Try to emulate machine type
116 .Ar "t".
117 This option is not always needed, if the
118 .Fl e
119 option uniquely selects a machine.
120 (Use
121 .Fl H
122 to get a list of types.)
123 .It Fl e Ar st
124 Try to emulate machine subtype
125 .Ar "st".
126 Use this together with
127 .Fl E .
128 (This option is not always needed, if a machine type has no subtypes.)
129 .El
130 .Pp
131 Other options:
132 .Bl -tag -width Ds
133 .It Fl C Ar x
134 Try to emulate a specific CPU type,
135 .Ar "x".
136 This overrides the default CPU type for the machine being emulated.
137 (Use
138 .Fl H
139 to get a list of available CPU types.)
140 .It Fl d Ar [modifiers:]filename
141 Add
142 .Ar filename
143 as a disk image. By adding one or more modifier characters and then a
144 colon (":") as a prefix to
145 .Ar filename,
146 you can modify the way the disk image is treated. Available modifiers are:
147 .Bl -tag -width Ds
148 .It b
149 Specifies that this is a boot device.
150 .It c
151 CD-ROM.
152 .It d
153 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
160 IDE. (This is the default for most machine types.)
161 .It r
162 Read-only (don't allow changes to be written to the file).
163 .It s
164 SCSI.
165 .It t
166 Tape.
167 .It 0-7
168 Force a specific ID number.
169 .El
170 .Pp
171 For SCSI devices, the ID number is the SCSI ID. For IDE harddisks, the ID
172 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
201 Emulate clock interrupts at
202 .Ar x
203 Hz. (This affects emulated clock devices only, not actual runtime speed.
204 This disables automatic clock adjustments, which is otherwise turned on.)
205 (This option is probably only valid for DECstation emulation.)
206 .It Fl i
207 Enable instruction trace, i.e. display disassembly of each instruction as
208 it is being executed.
209 .It Fl J
210 Disable instruction combinations in the dynamic translator.
211 .It Fl j Ar n
212 Set the name of the kernel to
213 .Ar "n".
214 When booting from an ISO9660 filesystem, the emulator will try to boot
215 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
219 Emulate
220 .Ar m
221 MBs of physical RAM. This overrides the default amount of RAM for the
222 selected machine type.
223 .It Fl N
224 Display the number of executed instructions per second on average, at
225 regular intervals.
226 .It Fl n Ar nr
227 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
239 Force a "netboot" (tftp instead of disk), even when a disk image is
240 present (for DECstation, SGI, and ARC emulation).
241 .It Fl o Ar arg
242 Set the boot argument (mostly useful for DEC, ARC, or SGI emulation).
243 Default
244 .Ar arg
245 for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A".
246 .It Fl p Ar pc
247 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
252 Disable the built-in (software-only) PROM emulation. This option is useful
253 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
257 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
262 Dump register contents for every executed instruction.
263 .It Fl S
264 Initialize emulated RAM to random data, instead of zeroes. This option
265 is useful when trying to trigger bugs in a program that occur because the
266 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
315 Show a trace tree of all function calls being made.
316 .It Fl U
317 Enable slow_serial_interrupts_hack_for_linux.
318 .It Fl X
319 Use X11. This option enables graphical framebuffers.
320 .It Fl x
321 Open up new xterms for emulated serial ports. The default behaviour is to
322 open up xterms when using configuration files, or if X11 is enabled. When
323 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
332 Scale down framebuffer windows by
333 .Ar n
334 x
335 .Ar n
336 times. This option is useful when emulating a very large framebuffer, and
337 the actual display is of lower resolution. If
338 .Ar n
339 is negative, then there will be no scaledown, but emulation of certain
340 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
348 Set the number of graphics cards, for emulating a dual-head or tripple-head
349 environment. (Only for DECstation emulation so far.)
350 .It Fl z Ar disp
351 Add
352 .Ar disp
353 as an X11 display to use for framebuffers.
354 .El
355 .Pp
356 .\" Userland options:
357 .\" .Bl -tag -width Ds
358 .\" .It Fl u Ar emul-mode
359 .\" Userland-only (syscall) emulation. (Use
360 .\" .Fl H
361 .\" 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
363 .\" userland emulation.
364 .\" .El
365 .\" .Pp
366 General options:
367 .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
376 Guarantee fully deterministic behavior. Normally, the emulator calls
377 srandom() with a seed based on the current time at startup. When the
378 .Fl D
379 option is used, the srandom() call is skipped, which should cause two
380 subsequent invocations of the emulator to be identical, if all other
381 settings are identical and no user input is taking place. (If this option
382 is used, then
383 .Fl I
384 must also be used.)
385 .It Fl H
386 Display a list of available CPU types, machine types, and userland
387 emulation modes. (Most of these don't work. Please read the documentation
388 included in the
389 .Nm
390 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
394 Display a list of all available command line options.
395 .It Fl K
396 Force the single-step debugger to be entered at the end of a simulation.
397 .It Fl q
398 Quiet mode; this suppresses startup messages.
399 .\".It Fl s
400 .\"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
404 Start up in the single-step debugger, paused.
405 .It Fl v
406 Increase verbosity (show more debug messages). This option can be used
407 multiple times.
408 .El
409 .Pp
410 Configuration file startup:
411 .Bl -tag -width Ds
412 .It @ Ar configfile
413 Start an emulation based on the contents of
414 .Ar "configfile".
415 .El
416 .Pp
417 For more information, please read the documentation in the doc/
418 subdirectory of the
419 .Nm
420 distribution.
421 .Sh EXAMPLES
422 The following command will start NetBSD/pmax on an emulated DECstation
423 5000/200 (3MAX):
424 .Pp
425 .Dl "gxemul -e 3max -d nbsd_pmax.img"
426 .Pp
427 nbsd_pmax.img should be a raw disk image containing a bootable
428 NetBSD/pmax filesystem.
429 .Pp
430 The following command will start an emulation session based on settings in
431 the configuration file "mysession". The -v option tells gxemul to be
432 verbose.
433 .Pp
434 .Dl "gxemul -v @mysession"
435 .Pp
436 If you have compiled the small Hello World program mentioned in the
437 .Nm
438 documentation, the following command will start up an
439 emulated test machine in "paused" mode:
440 .Pp
441 .Dl "gxemul -E testmips -V hello_mips"
442 .Pp
443 Paused mode means that you enter the interactive single-step debugger
444 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
461 Please read the documentation for more details.
462 .Sh BUGS
463 There are many bugs. Some of the known bugs are mentioned in the TODO
464 file in the
465 .Nm
466 source distribution, some are marked as TODO in the source code itself.
467 .Pp
468 Userland (syscall-only) emulation doesn't really work yet.
469 .Pp
470 The documentation sometimes only reflects the way things worked with
471 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
480 .Nm
481 is not timing-accurate, i.e. clocks inside the emulator are in general
482 not at all synched with clocks in the real world. There are a few
483 exceptions to this rule (the mc146818 device tries to automagically
484 adjust emulated timer ticks to actual emulation speed).
485 .Sh AUTHOR
486 GXemul is Copyright (C) 2003-2006 Anders Gavare <anders@gavare.se>
487 .Pp
488 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.

  ViewVC Help
Powered by ViewVC 1.1.26