/[gxemul]/upstream/0.3.5/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

Annotation of /upstream/0.3.5/man/gxemul.1

Parent Directory Parent Directory | Revision Log Revision Log

Revision 4 - (hide annotations)
Mon Oct 8 16:18:00 2007 UTC (16 years, 6 months ago) by dpavlin
Original Path: trunk/man/gxemul.1
File size: 10692 byte(s) 
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.707 2005/04/27 16:37:33 debug Exp $
20050408	Some minor updates to the wdc. Linux now doesn't complain
		anymore if a disk is non-present.
20050409	Various minor fixes (a bintrans bug, and some other things).
		The wdc seems to work with Playstation2 emulation, but there
		is a _long_ annoying delay when disks are detected.
		Fixing a really important bintrans bug (when devices and RAM
		are mixed within 4KB pages), which was triggered with
		NetBSD/playstation2 kernels.
20050410	Adding a dummy dev_ps2_ether (just so that NetBSD doesn't
		complain as much during bootup).
		Symbols starting with '$' are now ignored.
		Renaming dev_ps2_ohci.c to dev_ohci.c, etc.
20050411	Moving the bintrans-cache-isolation check from cpu_mips.c to
		cpu_mips_coproc.c. (I thought this would give a speedup, but
		it's not noticable.)
		Better playstation2 sbus interrupt code.
		Skip ahead many ticks if the count register is read manually.
		(This increases the speed of delay-loops that simply read
		the count register.)
20050412	Updates to the playstation2 timer/interrupt code.
		Some other minor updates.
20050413	NetBSD/cobalt runs from a disk image :-) including userland;
		updating the documentation on how to install NetBSD/cobalt
		using NetBSD/pmax (!).
		Some minor bintrans updates (no real speed improvement) and
		other minor updates (playstation2 now uses the -o options).
20050414	Adding a dummy x86 (and AMD64) mode.
20050415	Adding some (32-bit and 16-bit) x86 instructions.
		Adding some initial support for non-SCSI, non-IDE floppy
		images. (The x86 mode can boot from these, more or less.)
		Moving the devices/ and include/ directories to src/devices/
		and src/include/, respectively.
20050416	Continuing on the x86 stuff. (Adding pc_bios.c and some simple
		support for software interrupts in 16-bit mode.)
20050417	Ripping out most of the x86 instruction decoding stuff, trying
		to rewrite it in a cleaner way.
		Disabling some of the least working CPU families in the
		configure script (sparc, x86, alpha, hppa), so that they are
		not enabled by default.
20050418	Trying to fix the bug which caused problems when turning on
		and off bintrans interactively, by flushing the bintrans cache
		whenever bintrans is manually (re)enabled.
20050419	Adding the 'lswi' ppc instruction.
		Minor updates to the x86 instruction decoding.
20050420	Renaming x86 register name indices from R_xx to X86_R_xx (this
		makes building on Tru64 nicer).
20050422	Adding a check for duplicate MIPS TLB entries on tlbwr/tlbwi.
20050427	Adding screenshots to guestoses.html.
		Some minor fixes and testing for the next release.

==============  RELEASE 0.3.2  ==============
1 dpavlin 4 .\" $Id: gxemul.1,v 1.14 2005/04/16 02:38:21 debug Exp $
2 dpavlin 2 .\"
3     .\" Copyright (C) 2004-2005 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 2005
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     .Op Ar @configfile ...
45     .Nm
46     .Op userland, other, and general options
47     .Ar file Op Ar args ...
48     .Sh DESCRIPTION
49     .Nm
50     is an experimental instruction-level machine emulator. It can be used
51     to run binary code for (among others) MIPS-based machines.
52     Several emulation modes are available. For some emulation modes, processors
53     and surrounding hardware components are emulated well enough to let
54     unmodified operating systems (eg NetBSD) run as if they were running on a
55     real machine.
56     .Pp
57     There are three ways to invoke the emulator. When emulating a
58     complete machine, settings can be entered directly on the command line, or
59     they can be read from a configuration file. When emulating a userland
60     environment (syscall-only emulation, not emulating complete machines),
61     then the program name and its argument should be given on the command
62     line.
63     .Pp
64     The easiest way to use the emulator is to supply settings directly on the
65     command line. The most important thing you need to supply is the
66     file argument. This is the name of a binary file (an ELF, a.out, ECOFF,
67     SREC, or a raw binary image) which you wish to run in the emulator. This file
68     might be an operating system kernel, or perhaps a ROM image file.
69     .Pp
70     If more than one filename is supplied, all files are loaded into memory,
71     and the entry point (if available) is taken from the last file.
72     .Pp
73     Apart from the name of a binary file, it is also necessary to select
74     which specific emulation mode to use. For example, a MIPS-based machine
75     from DEC (a DECstation) is very different from a MIPS-based machine
76     from SGI. Use
77     .Nm
78     .Fl H
79     to get a list of available emulation modes.
80     .Pp
81     (There is an exception to the normal invocation usage mentioned above;
82     if you want to use the DECstation emulation mode, and have a bootable
83     DECstation harddisk or CDROM image, then just supplying the diskimage via
84     the
85     .Fl d
86     option is sufficient. The filename of the kernel can then be
87     skipped, as the emulator runs the bootblocks from the diskimage directly and
88     doesn't need the kernel as a separate file.)
89     .Pp
90     Machine selection options:
91     .Bl -tag -width Ds
92     .It Fl E Ar t
93     Try to emulate machine type
94     .Ar "t".
95     (Use
96     .Fl H
97     to get a list of types.)
98     .It Fl e Ar st
99     Try to emulate machine subtype
100     .Ar "st".
101     Use this together with
102     .Fl E .
103     (This option is not always needed, if a machine type has no subtypes.)
104     .El
105     .Pp
106     Other options:
107     .Bl -tag -width Ds
108     .It Fl B
109     Disable dynamic binary translation completely. By default, bintrans
110     will be turned on if the host architecture supports it.
111     However, in this release (0.3.1), there is no new bintrans system.
112     If you want to enable binary translation, use
113     .Fl "b".
114     .It Fl b
115     Use the OLD binary translation subsystem. (Alpha and i386 hosts only.)
116     .It Fl C Ar x
117     Try to emulate a specific CPU type,
118     .Ar "x".
119     This overrides the default CPU type for the machine being emulated.
120     (Use
121     .Fl H
122     to get a list of available CPU types.)
123     .It Fl d Ar name
124     Add
125     .Ar name
126     as a disk image. By adding one or more modifier characters and then a
127     colon (":") as a prefix to
128     .Ar "name",
129     you can modify the disk image's behaviour. Available modifiers are:
130     .Bl -tag -width Ds
131     .It b
132     Specifies that this is a boot device.
133     .It c
134 dpavlin 4 CD-ROM.
135 dpavlin 2 .It d
136 dpavlin 4 DISK (this is the default).
137     .It f
138     FLOPPY.
139 dpavlin 2 .It i
140 dpavlin 4 IDE.
141 dpavlin 2 .It r
142     Read-only (don't allow changes to be written to the file).
143 dpavlin 4 .It s
144     SCSI (this is the default for most machine types).
145 dpavlin 2 .It t
146 dpavlin 4 Tape.
147 dpavlin 2 .It 0-7
148     Force a specific SCSI ID number.
149     .El
150     .Pp
151 dpavlin 4 Filenames ending with ".iso" are assumed to be CDROM images. Files with a
152     size of exactly 1.44 MB are assumed to be floppy images. All others
153     are assumed to be disks.
154 dpavlin 2 .It Fl I Ar x
155     Emulate clock interrupts at
156     .Ar x
157     Hz. (This affects emulated clock devices only, not actual runtime speed.
158     This disables automatic clock adjustments, which is otherwise turned on.)
159     (This option is probably only valid for DECstation emulation.)
160     .It Fl i
161     Display each instruction as it is being executed.
162     .It Fl J
163     Disable some speed tricks.
164     .It Fl j Ar n
165     Set the name of the kernel to
166     .Ar "n".
167     Useful names are "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix.
168     ("netbsd" is usually the default value.)
169     .It Fl M Ar m
170     Emulate
171     .Ar m
172     MBs of physical RAM. This overrides the default amount of RAM for the
173     selected machine type.
174     .It Fl m Ar nr
175     Run at most
176     .Ar nr
177     instructions (on any cpu).
178     .It Fl N
179     Display nr of instructions/second average, at regular intervals.
180     .It Fl n Ar nr
181     Set nr of CPUs (for SMP experiments).
182     .It Fl O
183     Force a "netboot" (tftp instead of disk), even when a disk image is
184     present (for DECstation, SGI, and ARC emulation).
185     .It Fl o Ar arg
186     Set the boot argument (for DEC, ARC, or SGI emulation).
187     Default
188     .Ar arg
189     for DEC is '-a', for ARC '-aN'.
190     .It Fl p Ar pc
191     Add a breakpoint (remember to use the '0x' prefix for hex).
192     .It Fl Q
193     Disable the built-in PROM emulation. This is useful for running raw ROM
194     images from real machines.
195     .It Fl R
196     Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.)
197     .It Fl r
198     Dump register contents for every executed instruction.
199     .It Fl S
200     Initialize the emulated RAM to random data, instead of zeroes.
201     .It Fl T
202     Enter the single-step debugger on unimplemented memory accesses.
203     .It Fl t
204     Show a trace tree of all function calls being made.
205     .It Fl U
206     Enable slow_serial_interrupts_hack_for_linux.
207     .It Fl X
208     Use X11.
209     .It Fl x
210     Open up new xterms for emulated serial ports. (Default is to open up
211     xterms when using configuration files, but not when starting an
212     emulation with settings directly on the command line.)
213     .It Fl Y Ar n
214     Scale down framebuffer windows by
215     .Ar n
216     x
217     .Ar n
218     times.
219     .It Fl y Ar x
220     Set max_random_cycles_per_chunk to
221     .Ar x
222     (experimental).
223     .It Fl Z Ar n
224     Set the number of graphics cards, for emulating a dual-head or tripple-head
225     environment. (Only for DECstation emulation so far.)
226     .It Fl z Ar disp
227     Add
228     .Ar disp
229     as an X11 display to use for framebuffers.
230     .El
231     .Pp
232     Userland options:
233     .Bl -tag -width Ds
234     .It Fl u Ar emul-mode
235     Userland-only (syscall) emulation. (Use
236     .Fl H
237     to get a list of available emulation modes.) Some (but not all) of the
238     options listed under Other options above can also be used with userland
239     emulation.
240     .El
241     .Pp
242     General options:
243     .Bl -tag -width Ds
244     .It Fl D
245     Guarantee fully deterministic behaviour. Normally, the emulator calls
246     srandom() with a seed based on the current time at startup. When the
247     .Fl D
248     option is used, the srandom() call is skipped, which should cause two
249     subsequent invokations of the emulator to be identical, if all other
250     settings are identical. (If this option is used, then
251     .Fl I
252     must also be used.)
253     .It Fl H
254     Display a list of available CPU types, machine types, and userland
255     emulation modes. (Most of these don't work. Please read the documentation
256     included in the
257     .Nm
258     distribution for details on which modes that actually work.)
259     .It Fl h
260     Display a list of all available command line options.
261     .It Fl K
262     Force the single-step debugger to be entered at the end of a simulation.
263     .It Fl q
264     Quiet mode; this suppresses startup messages.
265     .It Fl s
266     Show opcode usage statistics after the simulation.
267     .It Fl V
268     Start up in the single-step debugger, paused.
269     .It Fl v
270     Verbose debug messages.
271     .El
272     .Pp
273     Configuration file startup:
274     .Bl -tag -width Ds
275     .It @ Ar configfile
276     Start an emulation based on the contents of
277     .Ar "configfile".
278     .El
279     .Pp
280     For more information, please read the documentation in the doc/
281     subdirectory of the
282     .Nm
283     distribution.
284     .Sh EXAMPLES
285     The following command will start NetBSD/pmax on an emulated DECstation
286     5000/200 (3MAX), with the old bintrans system enabled:
287     .Pp
288     .Dl "gxemul -E dec -e 3max -b -d netbsddisk.img"
289     .Pp
290     netbsddisk.img should be a raw disk image containing a bootable
291     NetBSD/pmax filesystem.
292     .Pp
293     The following command will start an emulation session based on settings in
294     the configuration file "mysession". The -v option tells gxemul to be
295     verbose.
296     .Pp
297     .Dl "gxemul -v @mysession"
298     .Pp
299     If you have compiled the small Hello World program mentioned in the
300     .Nm
301     documentation, the following command will start up an
302     emulated test machine in "paused" mode:
303     .Pp
304     .Dl "gxemul -E testmips -V hello_mips"
305     .Pp
306     (Paused mode means that you enter the interactive single-step debugger
307     directly at startup, instead of launching the Hello World program.)
308     .Pp
309     Please read the documentation for more details.
310     .Sh BUGS
311     There are many bugs. Some of the known bugs are listed in the BUGS
312     file in the
313     .Nm
314     source distribution, some are indirectly mentioned in the TODO file.
315     .Pp
316     There is no new bintrans system in this release (0.3.1), so you will
317     need to add
318     .Fl b
319     to select the old bintrans system, if you want speed.
320     .Pp
321     .Nm
322     does not simulate individual pipe-line stages or penalties caused by
323     branch-prediction misses, so it cannot be used for accurate performance
324     measurement.
325     .Sh AUTHOR
326     Anders Gavare <anders@gavare.se>
327     .Pp
328     See http://gavare.se/gxemul/ for more information.
  ViewVC Help
Powered by ViewVC 1.1.26