/[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 22 - (show annotations)
Mon Oct 8 16:19:37 2007 UTC (13 years, 1 month ago) by dpavlin
File size: 15392 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.1121 2006/02/18 21:03:08 debug Exp $
20051126	Cobalt and PReP now work with the 21143 NIC.
		Continuing on Alpha dyntrans things.
		Fixing some more left-shift-by-24 to unsigned.
20051127	Working on OpenFirmware emulation; major cleanup/redesign.
		Progress on MacPPC emulation: NetBSD detects two CPUs (when
		running with -n 2), framebuffer output (for text) works.
		Adding quick-hack Bandit PCI controller and "gc" interrupt
		controller for MacPPC.
20051128	Changing from a Bandit to a Uni-North controller for macppc.
		Continuing on OpenFirmware and MacPPC emulation in general
		(obio controller, and wdc attached to the obio seems to work).
20051129	More work on MacPPC emulation (adding a dummy ADB controller).
		Continuing the PCI bus cleanup (endianness and tag composition)
		and rewriting all PCI controllers' access functions.
20051130	Various minor PPC dyntrans optimizations.
		Manually inlining some parts of the framebuffer redraw routine.
		Slowly beginning the conversion of the old MIPS emulation into
		dyntrans (but this will take quite some time to get right).
		Generalizing quick_pc_to_pointers.
20051201	Documentation update (David Muse has made available a kernel
		which simplifies Debian/DECstation installation).
		Continuing on the ADB bus controller.
20051202	Beginning a rewrite of the Zilog serial controller (dev_zs).
20051203	Continuing on the zs rewrite (now called dev_z8530); conversion
		to devinit style.
		Reworking some of the input-only vs output-only vs input-output
		details of src/console.c, better warning messages, and adding
		a debug dump.
		Removing the concept of "device state"; it wasn't really used.
		Changing some debug output (-vv should now be used to show all
		details about devices and busses; not shown during normal
		startup anymore).
		Beginning on some SPARC instruction disassembly support.
20051204	Minor PPC updates (WALNUT skeleton stuff).
		Continuing on the MIPS dyntrans rewrite.
		More progress on the ADB controller (a keyboard is "detected"
		by NetBSD and OpenBSD).
		Downgrading OpenBSD/arc as a guest OS from "working" to
		"almost working" in the documentation.
		Progress on Algor emulation ("v3" PCI controller).
20051205	Minor updates.
20051207	Sorting devices according to address; this reduces complexity
		of device lookups from O(n) to O(log n) in memory_rw (but no
		real performance increase (yet) in experiments).
20051210	Beginning the work on native dyntrans backends (by making a
		simple skeleton; so far only for Alpha hosts).
20051211	Some very minor SPARC updates.
20051215	Fixing a bug in the MIPS mul (note: not mult) instruction,
		so it also works with non-64-bit emulation. (Thanks to Alec
		Voropay for noticing the problem.)
20051216	More work on the fake/empty/simple/skeleton/whatever backend;
		performance doesn't increase, so this isn't really worth it,
		but it was probably worth it to prepare for a real backend
		later.
20051219	More instr call statistics gathering and analysis stuff.
20051220	Another fix for MIPS 'mul'. Also converting mul and {d,}cl{o,z}
		to dyntrans.
		memory_ppc.c syntax error fix (noticed by Peter Valchev).
		Beginning to move out machines from src/machine.c into
		individual files in src/machines (in a way similar to the
		autodev system for devices).
20051222	Updating the documentation regarding NetBSD/pmax 3.0.
20051223	- " - NetBSD/cats 3.0.
20051225	- " - NetBSD/hpcmips 3.0.
20051226	Continuing on the machine registry redesign.
		Adding support for ARM rrx (33-bit rotate).
		Fixing some signed/unsigned issues (exposed by gcc -W).
20051227	Fixing the bug which prevented a NetBSD/prep 3.0 install kernel
		from starting (triggered when an mtmsr was the last instruction
		on a page). Unfortunately not enough to get the kernel to run
		as well as the 2.1 kernels did.
20051230	Some dyntrans refactoring.
20051231	Continuing on the machine registry redesign.
20060101-10	Continuing... moving more machines. Moving MD interrupt stuff
		from machine.c into a new src/machines/interrupts.c.
20060114	Adding various mvmeppc machine skeletons.
20060115	Continuing on mvme* stuff. NetBSD/mvmeppc prints boot messages
		(for MVME1600) and reaches the root device prompt, but no
		specific hardware devices are emulated yet.
20060116	Minor updates to the mvme1600 emulation mode; the Eagle PCI bus
		seems to work without much modification, and a 21143 can be
		detected, interrupts might work (but untested so far).
		Adding a fake MK48Txx (mkclock) device, for NetBSD/mvmeppc.
20060121	Adding an aux control register for ARM. (A BIG thank you to
		Olivier Houchard for tracking down this bug.)
20060122	Adding more ARM instructions (smulXY), and dev_iq80321_7seg.
20060124	Adding disassembly of more ARM instructions (mia*, mra/mar),
		and some semi-bogus XScale and i80321 registers.
20060201-02	Various minor updates. Moving the last machines out of
		machine.c.
20060204	Adding a -c command line option, for running debugger commands
		before the simulation starts, but after all files have been
		loaded.
		Minor iq80321-related updates.
20060209	Minor hacks (DEVINIT macro, etc).
		Preparing for the generalization of the 64-bit dyntrans address
		translation subsystem.
20060216	Adding ARM ldrd (double-register load).
20060217	Continuing on various ARM-related stuff.
20060218	More progress on the ATA/wdc emulation for NetBSD/iq80321.
		NetBSD/evbarm can now be installed :-)  Updating the docs, etc.
		Continuing on Algor emulation.

==============  RELEASE 0.3.8  ==============


1 .\" $Id: gxemul.1,v 1.49 2006/02/18 14:02:20 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 FEBRUARY 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 .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. Several
51 emulation modes are available. In some modes, processors and surrounding
52 hardware components are emulated well enough to let unmodified operating
53 systems (e.g. NetBSD) run inside the emulator as if they were running on a
54 real machine.
55 .Pp
56 The processor architecture best emulated by GXemul is MIPS, but other
57 architectures (ARM and PowerPC) are also partially emulated.
58 .Pp
59 MIPS processors are emulated using either a simple binary translation
60 layer (recompilation into native code), which is used on Alpha and i386
61 hosts, or by traditional interpretation (very very slow, but works on any
62 host platform).
63 .Pp
64 Non-MIPS processors are emulated using a newer dynamic translation
65 system (called dyntrans in the rest of this man page). Performance is
66 somewhere between traditional interpretation and recompilation into native
67 code. However, the dynamic translation system used in GXemul does NOT
68 generate native code, and thus doesn't require platform-specific
69 back-ends. In plain English, this means that the dyntrans system works on
70 any host platform.
71 .Pp
72 There are three ways to invoke the emulator:
73 .Pp
74 1. When emulating a complete machine, configuration options can be entered
75 directly on the command line.
76 .Pp
77 2. Options can be read from a configuration file.
78 .Pp
79 3. When emulating a userland environment (syscall-only emulation, not
80 emulating complete machines), then the program name and its argument
81 should be given on the command line. (This mode doesn't really work yet.)
82 .Pp
83 The easiest way to use the emulator is to supply settings directly on the
84 command line. The most important thing you need to supply is the
85 file argument. This is the name of a binary file (an ELF, a.out, COFF/ECOFF,
86 SREC, or a raw binary image) which you wish to run in the emulator. This file
87 might be an operating system kernel, or perhaps a ROM image file.
88 .Pp
89 If more than one filename is supplied, all files are loaded into memory,
90 and the entry point (if available) is taken from the last file.
91 .Pp
92 Apart from the name of a binary file, it is also necessary to select
93 which specific emulation mode to use. For example, a MIPS-based machine
94 from DEC (a DECstation) is very different from a MIPS-based machine
95 from SGI. Use
96 .Nm
97 .Fl H
98 to get a list of available emulation modes.
99 .Pp
100 There are two exceptions to the normal invocation usage mentioned above.
101 The first is for DECstation emulation: if you have a bootable
102 DECstation harddisk or CDROM image, then just supplying the diskimage via
103 the
104 .Fl d
105 option is sufficient. (The filename of the kernel can then be
106 skipped, as the emulator runs the bootblocks from the diskimage directly and
107 doesn't need the kernel as a separate file.)
108 The second is if you supply an ISO9660 CDROM disk image. You may then use
109 the
110 .Fl j
111 option to indicate which file on the CDROM filesystem that should be
112 loaded into emulated memory.
113 .Pp
114 Machine selection options:
115 .Bl -tag -width Ds
116 .It Fl E Ar t
117 Try to emulate machine type
118 .Ar "t".
119 This option is not always needed, if the
120 .Fl e
121 option uniquely selects a machine.
122 (Use
123 .Fl H
124 to get a list of types.)
125 .It Fl e Ar st
126 Try to emulate machine subtype
127 .Ar "st".
128 Use this together with
129 .Fl E .
130 (This option is not always needed, if a machine type has no subtypes.)
131 .El
132 .Pp
133 Other options:
134 .Bl -tag -width Ds
135 .It Fl A
136 Disable load/store alignment checks in some cases. This might give a small
137 increase in performance, but the emulator will not run correctly if the
138 emulated code actually tries to do unaligned loads or stores. (This option
139 is only meaningful when emulating MIPS CPUs, when the host architecture is
140 Alpha or i386, and binary translation is enabled.)
141 .It Fl B
142 Disable native translation backends. By default, translation backends are
143 used if the host+target architecture combination is supported. Currently,
144 the only supported host architecture for the old bintrans system (used
145 when emulating MIPS processors) are Alpha and i386. The old bintrans
146 system will hopefully be removed some day.
147 .It Fl C Ar x
148 Try to emulate a specific CPU type,
149 .Ar "x".
150 This overrides the default CPU type for the machine being emulated.
151 (Use
152 .Fl H
153 to get a list of available CPU types.)
154 .It Fl d Ar name
155 Add
156 .Ar name
157 as a disk image. By adding one or more modifier characters and then a
158 colon (":") as a prefix to
159 .Ar "name",
160 you can modify the way the disk image is treated. Available modifiers are:
161 .Bl -tag -width Ds
162 .It b
163 Specifies that this is a boot device.
164 .It c
165 CD-ROM.
166 .It d
167 DISK (this is the default).
168 .It f
169 FLOPPY.
170 .It gH;S;
171 Override the default geometry; use H heads and S sectors-per-track.
172 (The number of cylinders is calculated automatically.)
173 .It i
174 IDE. (This is the default for most machine types.)
175 .It r
176 Read-only (don't allow changes to be written to the file).
177 .It s
178 SCSI.
179 .It t
180 Tape.
181 .It 0-7
182 Force a specific ID number.
183 .El
184 .Pp
185 Unless otherwise specified, filenames ending with ".iso" or ".cdr" are
186 assumed to be CDROM images. Most others are assumed to be disks. Depending
187 on which machine is being emulated, the default for disks can be either
188 SCSI or IDE. Some disk images that are very small are assumed to be floppy
189 disks. (If you are not happy with the way a disk image is detected, then
190 you need to use explicit prefixes to force a specific type.)
191 .Pp
192 For floppies, the gH;S; prefix is ignored. Instead, the number of
193 heads and cylinders are assumed to be 2 and 80, respectively, and the
194 number of sectors per track is calculated automatically. (This works for
195 720KB, 1.2MB, 1.44MB, and 2.88MB floppies.)
196 .It Fl I Ar x
197 Emulate clock interrupts at
198 .Ar x
199 Hz. (This affects emulated clock devices only, not actual runtime speed.
200 This disables automatic clock adjustments, which is otherwise turned on.)
201 (This option is probably only valid for DECstation emulation.)
202 .It Fl i
203 Display each instruction as it is being executed.
204 .It Fl J
205 Disable some speed tricks. For MIPS emulation, these are mostly
206 timing-related. For non-MIPS emulation (i.e. modes using dyntrans),
207 this flag disables the use of "instruction combinations".
208 .It Fl j Ar n
209 Set the name of the kernel to
210 .Ar "n".
211 When booting from an ISO9660 filesystem, the emulator will try to boot
212 using this file. (In some emulation modes, eg. DECstation, this name is passed
213 along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
214 or "vmunix" for Ultrix.)
215 .It Fl M Ar m
216 Emulate
217 .Ar m
218 MBs of physical RAM. This overrides the default amount of RAM for the
219 selected machine type.
220 .It Fl m Ar nr
221 Run at most
222 .Ar nr
223 instructions (on any cpu).
224 .It Fl N
225 Display nr of instructions/second average, at regular intervals.
226 .It Fl n Ar nr
227 Set nr of CPUs (for SMP experiments). Note: The emulator allocates quite a
228 lot of virtual memory for per-CPU translation tables. On 64-bit hosts,
229 this is normally not a problem. On 32-bit hosts, this can use up all
230 available virtual userspace memory. The solution is to either run the
231 emulator on a 64-bit host, or limit the number of emulated CPUs to a
232 reasonable number (say, less than 32).
233 .It Fl O
234 Force a "netboot" (tftp instead of disk), even when a disk image is
235 present (for DECstation, SGI, and ARC emulation).
236 .It Fl o Ar arg
237 Set the boot argument (mostly useful for DEC, ARC, or SGI emulation).
238 Default
239 .Ar arg
240 for DEC is "-a", for ARC/SGI it is "-aN", and for CATS it is "-A".
241 .It Fl p Ar pc
242 Add a breakpoint. (Remember to use the "0x" prefix for hex.)
243 .It Fl Q
244 Disable the built-in PROM emulation. This is useful for running raw ROM
245 images from real machines.
246 .It Fl R
247 Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.)
248 .It Fl r
249 Dump register contents for every executed instruction.
250 .It Fl S
251 Initialize the emulated RAM to random data, instead of zeroes.
252 .It Fl T
253 Enter the single-step debugger on unimplemented memory accesses.
254 .It Fl t
255 Show a trace tree of all function calls being made.
256 .It Fl U
257 Enable slow_serial_interrupts_hack_for_linux.
258 .It Fl X
259 Use X11. This option enables graphical framebuffers.
260 .It Fl x
261 Open up new xterms for emulated serial ports. The default behaviour is to
262 open up xterms when using configuration files, or if X11 is enabled. When
263 starting up a simple emulation session with settings directly on the
264 command line, and neither
265 .Fl X
266 nor
267 .Fl x
268 is used, then all output is confined to the terminal that
269 .Nm
270 started in.
271 .It Fl Y Ar n
272 Scale down framebuffer windows by
273 .Ar n
274 x
275 .Ar n
276 times. This option is useful when emulating a very large framebuffer, and
277 the actual display is of lower resolution. If
278 .Ar n
279 is negative, then there will be no scaledown, but emulation of certain
280 graphic controllers will be scaled up
281 by
282 .Ar -n
283 times instead. E.g. Using
284 .Ar -2
285 with VGA text mode emulation will result in 80x25 character cells rendered
286 in a 1280x800 window, instead of the normal resolution of 640x400.
287 .It Fl y Ar x
288 Set max_random_cycles_per_chunk to
289 .Ar x
290 (experimental).
291 .It Fl Z Ar n
292 Set the number of graphics cards, for emulating a dual-head or tripple-head
293 environment. (Only for DECstation emulation so far.)
294 .It Fl z Ar disp
295 Add
296 .Ar disp
297 as an X11 display to use for framebuffers.
298 .El
299 .Pp
300 Userland options:
301 .Bl -tag -width Ds
302 .It Fl u Ar emul-mode
303 Userland-only (syscall) emulation. (Use
304 .Fl H
305 to get a list of available emulation modes.) Some (but not all) of the
306 options listed under Other options above can also be used with userland
307 emulation.
308 .El
309 .Pp
310 General options:
311 .Bl -tag -width Ds
312 .It Fl c Ar cmd
313 Add
314 .Ar cmd
315 as a command to run before starting the simulation. A similar effect can
316 be achieved by using the
317 .Fl V
318 option, and entering the commands manually.
319 .It Fl D
320 Guarantee fully deterministic behavior. Normally, the emulator calls
321 srandom() with a seed based on the current time at startup. When the
322 .Fl D
323 option is used, the srandom() call is skipped, which should cause two
324 subsequent invocations of the emulator to be identical, if all other
325 settings are identical and no user input is taking place. (If this option
326 is used, then
327 .Fl I
328 must also be used.)
329 .It Fl H
330 Display a list of available CPU types, machine types, and userland
331 emulation modes. (Most of these don't work. Please read the documentation
332 included in the
333 .Nm
334 distribution for details on which modes that actually work.)
335 .It Fl h
336 Display a list of all available command line options.
337 .It Fl K
338 Force the single-step debugger to be entered at the end of a simulation.
339 .It Fl q
340 Quiet mode; this suppresses startup messages.
341 .It Fl s
342 For MIPS emulation: Show opcode usage statistics after the simulation.
343 For non-MIPS emulation (i.e. using dyntrans): Save statistics to a file at
344 regular intervals of which physical addresses that were executed.
345 .It Fl V
346 Start up in the single-step debugger, paused.
347 .It Fl v
348 Increase verbosity (show more debug messages). This option can be used
349 multiple times.
350 .El
351 .Pp
352 Configuration file startup:
353 .Bl -tag -width Ds
354 .It @ Ar configfile
355 Start an emulation based on the contents of
356 .Ar "configfile".
357 .El
358 .Pp
359 For more information, please read the documentation in the doc/
360 subdirectory of the
361 .Nm
362 distribution.
363 .Sh EXAMPLES
364 The following command will start NetBSD/pmax on an emulated DECstation
365 5000/200 (3MAX):
366 .Pp
367 .Dl "gxemul -e 3max -d nbsd_pmax.img"
368 .Pp
369 nbsd_pmax.img should be a raw disk image containing a bootable
370 NetBSD/pmax filesystem.
371 .Pp
372 The following command will start an emulation session based on settings in
373 the configuration file "mysession". The -v option tells gxemul to be
374 verbose.
375 .Pp
376 .Dl "gxemul -v @mysession"
377 .Pp
378 If you have compiled the small Hello World program mentioned in the
379 .Nm
380 documentation, the following command will start up an
381 emulated test machine in "paused" mode:
382 .Pp
383 .Dl "gxemul -E testmips -V hello_mips"
384 .Pp
385 (Paused mode means that you enter the interactive single-step debugger
386 directly at startup, instead of launching the Hello World program.)
387 .Pp
388 Please read the documentation for more details.
389 .Sh BUGS
390 There are many bugs. Some of the known bugs are listed in the BUGS
391 file in the
392 .Nm
393 source distribution, some are indirectly mentioned in the TODO file,
394 and some are mentioned in the source code itself.
395 .Pp
396 The binary translation subsystem used for emulating MIPS processors is
397 really terrible, but it is less terrible than running without it. It will
398 be removed once the newer MIPS dyntrans emulation mode works well enough.
399 .Pp
400 Userland (syscall-only) emulation doesn't really work yet.
401 .Pp
402 Emulation of MIPS CPUs is done differently from other emulation modes; the
403 documentation sometimes only reflects the way things work with MIPS
404 emulation, and it is incorrect when applied to e.g. ARM emulation.
405 .Pp
406 .Nm
407 is in general not cycle-accurate; it does not simulate individual
408 pipe-line stages or penalties caused by branch-prediction misses or
409 cache misses, so it cannot be used for accurate simulation of any actual
410 real-world processor.
411 .Pp
412 .Nm
413 is not timing-accurate, i.e. clocks inside the emulator are in general
414 not at all synched with clocks in the real world. There are a few
415 exceptions to this rule (the mc146818 device tries to automagically
416 adjust emulated timer ticks to actual emulation speed).
417 .Sh AUTHOR
418 GXemul is Copyright (C) 2003-2006 Anders Gavare <anders@gavare.se>
419 .Pp
420 See http://gavare.se/gxemul/ for more information. For other Copyright
421 messages, see the corresponding parts of the source code and/or
422 documentation.

  ViewVC Help
Powered by ViewVC 1.1.26