/[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

Annotation of /trunk/man/gxemul.1

Parent Directory Parent Directory | Revision Log Revision Log


Revision 10 - (hide annotations)
Mon Oct 8 16:18:27 2007 UTC (16 years, 5 months ago) by dpavlin
File size: 11484 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.815 2005/06/27 23:04:35 debug Exp $
20050617	Experimenting some more with netbooting OpenBSD/sgi. Adding
		a hack which allows emulated ethernet networks to be
		distributed across multiple emulator processes.
20050618	Minor updates (documentation, dummy YAMON emulation, etc).
20050620	strcpy/strcat -> strlcpy/strlcat updates.
		Some more progress on evbmips (Malta).
20050621	Adding a section to doc/configfiles.html about ethernet
		emulation across multiple hosts.
		Beginning the work on the ARM translation engine (using the
		dynamic-but-not-binary translation method).
		Fixing a bintrans bug: 0x9fc00000 should always be treated as
		PROM area, just as 0xbfc00000 is.
		Minor progress on Malta emulation (the PCI-ISA bus).
20050622	NetBSD/evbmips can now be installed (using another emulated
		machine) and run (including userland and so on). :-)
		Spliting up the bintrans haddr_entry field into two (one for
		read, one for write). Probably not much of a speed increase,
		though.
		Updating some NetBSD 2.0 -> 2.0.2 in the documentation.
20050623	Minor updates (documentation, the TODO file, etc).
		gzipped kernels are now always automagically gunzipped when
		loaded.
20050624	Adding a dummy Playstation Portable (PSP) mode, just barely
		enough to run Hello World (in weird colors :-).
		Removing the -b command line option; old bintrans is enabled
		by default instead. It makes more sense.
		Trying to finally fix the non-working performance measurement
		thing (instr/second etc).
20050625	Continuing on the essential basics for ARM emulation. Two
		instructions seem to work, a branch and a simple "mov". (The
		mov arguments are not correct yet.) Performance is definitely
		reasonable.
		Various other minor updates.
		Adding the ARM "bl" instruction.
		Adding support for combining multiple ARM instructions into one
		function call. ("mov" + "mov" is the only one implemented so
		far, but it seems to work.)
		Cleaning up some IP32 interrupt things (crime/mace); disabling
		the PS/2 keyboard controller on IP32, so that NetBSD/sgimips
		boots into userland again.
20050626	Finally! NetBSD/sgimips netboots. Adding instructions to
		doc/guestoses.html on how to set up an nfs server etc.
		Various other minor fixes.
		Playstation Portable ".pbp" files can now be used directly.
		(The ELF part of the .pbp is extracted transparently.)
		Converting some sprintf -> snprintf.
		Adding some more instructions to the ARM disassembler.
20050627	More ARM updates. Adding some simple ldr(b), str(b),
		cmps, and conditional branch instructions, enough to run
		a simple Hello World program.
		All ARM instructions are now inlined/generated for all possible
		condition codes.
		Adding add and sub, and more load/store instructions.
		Removing dummy files: cpu_alpha.c, cpu_hppa.c, and cpu_sparc.c.
		Some minor documentation updates; preparing for a 0.3.4
		release. Updating some URLs.

==============  RELEASE 0.3.4  ==============


1 dpavlin 10 .\" $Id: gxemul.1,v 1.24 2005/06/26 10:05:02 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 dpavlin 6 .Dd JUNE 2005
33 dpavlin 2 .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 dpavlin 10 is an experimental instruction-level machine emulator. It can be used to
51     run binary code for (among others) MIPS-based machines, regardless of host
52     platform. Several emulation modes are available. For some modes,
53     processors and surrounding hardware components are emulated well enough to
54     let unmodified operating systems (e.g. NetBSD) run as if they were running
55     on a real machine.
56 dpavlin 2 .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 dpavlin 6 There are two exceptions to the normal invocation usage mentioned above.
82     The first is for DECstation emulation: if you have a bootable
83 dpavlin 2 DECstation harddisk or CDROM image, then just supplying the diskimage via
84     the
85     .Fl d
86 dpavlin 6 option is sufficient. (The filename of the kernel can then be
87 dpavlin 2 skipped, as the emulator runs the bootblocks from the diskimage directly and
88     doesn't need the kernel as a separate file.)
89 dpavlin 6 The second is if you supply an ISO9660 CDROM disk image. You may then use
90     the
91     .Fl j
92     option to indicate which file on the CDROM filesystem that should be
93     loaded into emulated memory.
94 dpavlin 2 .Pp
95     Machine selection options:
96     .Bl -tag -width Ds
97     .It Fl E Ar t
98     Try to emulate machine type
99     .Ar "t".
100     (Use
101     .Fl H
102     to get a list of types.)
103     .It Fl e Ar st
104     Try to emulate machine subtype
105     .Ar "st".
106     Use this together with
107     .Fl E .
108     (This option is not always needed, if a machine type has no subtypes.)
109     .El
110     .Pp
111     Other options:
112     .Bl -tag -width Ds
113     .It Fl B
114 dpavlin 10 Disable dynamic binary translation. By default, bintrans
115     will be turned on if the host+target architecture combination is
116     supported.
117 dpavlin 2 .It Fl C Ar x
118     Try to emulate a specific CPU type,
119     .Ar "x".
120     This overrides the default CPU type for the machine being emulated.
121     (Use
122     .Fl H
123     to get a list of available CPU types.)
124     .It Fl d Ar name
125     Add
126     .Ar name
127     as a disk image. By adding one or more modifier characters and then a
128     colon (":") as a prefix to
129     .Ar "name",
130 dpavlin 6 you can modify the way the disk image is treated. Available modifiers are:
131 dpavlin 2 .Bl -tag -width Ds
132     .It b
133     Specifies that this is a boot device.
134     .It c
135 dpavlin 4 CD-ROM.
136 dpavlin 2 .It d
137 dpavlin 4 DISK (this is the default).
138     .It f
139     FLOPPY.
140 dpavlin 6 .It gH;S;
141     Override the default geometry; use H heads and S sectors-per-track.
142     (The number of cylinders is calculated automatically.)
143 dpavlin 2 .It i
144 dpavlin 4 IDE.
145 dpavlin 2 .It r
146     Read-only (don't allow changes to be written to the file).
147 dpavlin 4 .It s
148     SCSI (this is the default for most machine types).
149 dpavlin 2 .It t
150 dpavlin 4 Tape.
151 dpavlin 2 .It 0-7
152 dpavlin 6 Force a specific ID number.
153 dpavlin 2 .El
154     .Pp
155 dpavlin 6 Unless otherwise specified, filenames ending with ".iso" are assumed to be
156     CDROM images. Most others are assumed to be disks. Depending on which
157     machine is being emulated, the default for disks can be either SCSI or
158     IDE. Some disk images that are very small are assumed to be floppy disks.
159     (If you are not happy with the way a disk image is detected, then you need
160     to use explicit prefixes to force a specific type.)
161     .Pp
162     For floppies, the gH;S; prefix is ignored. Instead, the number of
163     heads and cylinders are assumed to be 2 and 80, respectively, and the
164     number of sectors per track is calculated automatically. (This works for
165     720KB, 1.2MB, 1.44MB, and 2.88MB floppies.)
166 dpavlin 2 .It Fl I Ar x
167     Emulate clock interrupts at
168     .Ar x
169     Hz. (This affects emulated clock devices only, not actual runtime speed.
170     This disables automatic clock adjustments, which is otherwise turned on.)
171     (This option is probably only valid for DECstation emulation.)
172     .It Fl i
173     Display each instruction as it is being executed.
174     .It Fl J
175     Disable some speed tricks.
176     .It Fl j Ar n
177     Set the name of the kernel to
178     .Ar "n".
179 dpavlin 10 When booting from an ISO9660 filesystem, the emulator will try to boot
180     using this file. (In some emulation modes, eg. DECstation, this name is passed
181 dpavlin 6 along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
182     or "vmunix" for Ultrix.)
183 dpavlin 2 .It Fl M Ar m
184     Emulate
185     .Ar m
186     MBs of physical RAM. This overrides the default amount of RAM for the
187     selected machine type.
188     .It Fl m Ar nr
189     Run at most
190     .Ar nr
191     instructions (on any cpu).
192     .It Fl N
193     Display nr of instructions/second average, at regular intervals.
194     .It Fl n Ar nr
195     Set nr of CPUs (for SMP experiments).
196     .It Fl O
197     Force a "netboot" (tftp instead of disk), even when a disk image is
198     present (for DECstation, SGI, and ARC emulation).
199     .It Fl o Ar arg
200     Set the boot argument (for DEC, ARC, or SGI emulation).
201     Default
202     .Ar arg
203 dpavlin 6 for DEC is "-a", for ARC "-aN".
204 dpavlin 2 .It Fl p Ar pc
205 dpavlin 6 Add a breakpoint. (Remember to use the "0x" prefix for hex.)
206 dpavlin 2 .It Fl Q
207     Disable the built-in PROM emulation. This is useful for running raw ROM
208     images from real machines.
209     .It Fl R
210     Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.)
211     .It Fl r
212     Dump register contents for every executed instruction.
213     .It Fl S
214     Initialize the emulated RAM to random data, instead of zeroes.
215     .It Fl T
216     Enter the single-step debugger on unimplemented memory accesses.
217     .It Fl t
218     Show a trace tree of all function calls being made.
219     .It Fl U
220     Enable slow_serial_interrupts_hack_for_linux.
221     .It Fl X
222     Use X11.
223     .It Fl x
224     Open up new xterms for emulated serial ports. (Default is to open up
225     xterms when using configuration files, but not when starting an
226     emulation with settings directly on the command line.)
227     .It Fl Y Ar n
228     Scale down framebuffer windows by
229     .Ar n
230     x
231     .Ar n
232     times.
233     .It Fl y Ar x
234     Set max_random_cycles_per_chunk to
235     .Ar x
236     (experimental).
237     .It Fl Z Ar n
238     Set the number of graphics cards, for emulating a dual-head or tripple-head
239     environment. (Only for DECstation emulation so far.)
240     .It Fl z Ar disp
241     Add
242     .Ar disp
243     as an X11 display to use for framebuffers.
244     .El
245     .Pp
246     Userland options:
247     .Bl -tag -width Ds
248     .It Fl u Ar emul-mode
249     Userland-only (syscall) emulation. (Use
250     .Fl H
251     to get a list of available emulation modes.) Some (but not all) of the
252     options listed under Other options above can also be used with userland
253     emulation.
254     .El
255     .Pp
256     General options:
257     .Bl -tag -width Ds
258     .It Fl D
259 dpavlin 6 Guarantee fully deterministic behavior. Normally, the emulator calls
260 dpavlin 2 srandom() with a seed based on the current time at startup. When the
261     .Fl D
262     option is used, the srandom() call is skipped, which should cause two
263 dpavlin 6 subsequent invocations of the emulator to be identical, if all other
264     settings are identical and no user input is taking place. (If this option
265     is used, then
266 dpavlin 2 .Fl I
267     must also be used.)
268     .It Fl H
269     Display a list of available CPU types, machine types, and userland
270     emulation modes. (Most of these don't work. Please read the documentation
271     included in the
272     .Nm
273     distribution for details on which modes that actually work.)
274     .It Fl h
275     Display a list of all available command line options.
276     .It Fl K
277     Force the single-step debugger to be entered at the end of a simulation.
278     .It Fl q
279     Quiet mode; this suppresses startup messages.
280     .It Fl s
281     Show opcode usage statistics after the simulation.
282     .It Fl V
283     Start up in the single-step debugger, paused.
284     .It Fl v
285     Verbose debug messages.
286     .El
287     .Pp
288     Configuration file startup:
289     .Bl -tag -width Ds
290     .It @ Ar configfile
291     Start an emulation based on the contents of
292     .Ar "configfile".
293     .El
294     .Pp
295     For more information, please read the documentation in the doc/
296     subdirectory of the
297     .Nm
298     distribution.
299     .Sh EXAMPLES
300     The following command will start NetBSD/pmax on an emulated DECstation
301 dpavlin 10 5000/200 (3MAX):
302 dpavlin 2 .Pp
303 dpavlin 10 .Dl "gxemul -E dec -e 3max -d nbsd_pmax.img"
304 dpavlin 2 .Pp
305 dpavlin 10 nbsd_pmax.img should be a raw disk image containing a bootable
306 dpavlin 2 NetBSD/pmax filesystem.
307     .Pp
308     The following command will start an emulation session based on settings in
309     the configuration file "mysession". The -v option tells gxemul to be
310     verbose.
311     .Pp
312     .Dl "gxemul -v @mysession"
313     .Pp
314     If you have compiled the small Hello World program mentioned in the
315     .Nm
316     documentation, the following command will start up an
317     emulated test machine in "paused" mode:
318     .Pp
319     .Dl "gxemul -E testmips -V hello_mips"
320     .Pp
321     (Paused mode means that you enter the interactive single-step debugger
322     directly at startup, instead of launching the Hello World program.)
323     .Pp
324     Please read the documentation for more details.
325     .Sh BUGS
326     There are many bugs. Some of the known bugs are listed in the BUGS
327     file in the
328     .Nm
329     source distribution, some are indirectly mentioned in the TODO file.
330     .Pp
331 dpavlin 10 The binary translation subsystem is really terrible, but it is less
332     terrible than running without it.
333 dpavlin 2 .Pp
334     .Nm
335     does not simulate individual pipe-line stages or penalties caused by
336 dpavlin 10 branch-prediction misses or cache misses, so it cannot be used for
337     accurate performance measurement.
338 dpavlin 6 .Pp
339     .Nm
340     is not timing-accurate.
341 dpavlin 2 .Sh AUTHOR
342     Anders Gavare <anders@gavare.se>
343     .Pp
344     See http://gavare.se/gxemul/ for more information.

  ViewVC Help
Powered by ViewVC 1.1.26