/[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 4 - (show annotations)
Mon Oct 8 16:18:00 2007 UTC (16 years, 6 months ago) by dpavlin
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 .\" $Id: gxemul.1,v 1.14 2005/04/16 02:38:21 debug Exp $
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 CD-ROM.
135 .It d
136 DISK (this is the default).
137 .It f
138 FLOPPY.
139 .It i
140 IDE.
141 .It r
142 Read-only (don't allow changes to be written to the file).
143 .It s
144 SCSI (this is the default for most machine types).
145 .It t
146 Tape.
147 .It 0-7
148 Force a specific SCSI ID number.
149 .El
150 .Pp
151 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 .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