/[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 10 - (show 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 .\" $Id: gxemul.1,v 1.24 2005/06/26 10:05:02 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 JUNE 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 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 .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 are two exceptions to the normal invocation usage mentioned above.
82 The first is for DECstation emulation: if you 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 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 .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 Disable dynamic binary translation. By default, bintrans
115 will be turned on if the host+target architecture combination is
116 supported.
117 .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 you can modify the way the disk image is treated. Available modifiers are:
131 .Bl -tag -width Ds
132 .It b
133 Specifies that this is a boot device.
134 .It c
135 CD-ROM.
136 .It d
137 DISK (this is the default).
138 .It f
139 FLOPPY.
140 .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 .It i
144 IDE.
145 .It r
146 Read-only (don't allow changes to be written to the file).
147 .It s
148 SCSI (this is the default for most machine types).
149 .It t
150 Tape.
151 .It 0-7
152 Force a specific ID number.
153 .El
154 .Pp
155 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 .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 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 along to the boot program. Useful names are "bsd" for OpenBSD/pmax,
182 or "vmunix" for Ultrix.)
183 .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 for DEC is "-a", for ARC "-aN".
204 .It Fl p Ar pc
205 Add a breakpoint. (Remember to use the "0x" prefix for hex.)
206 .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 Guarantee fully deterministic behavior. Normally, the emulator calls
260 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 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 .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 5000/200 (3MAX):
302 .Pp
303 .Dl "gxemul -E dec -e 3max -d nbsd_pmax.img"
304 .Pp
305 nbsd_pmax.img should be a raw disk image containing a bootable
306 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 The binary translation subsystem is really terrible, but it is less
332 terrible than running without it.
333 .Pp
334 .Nm
335 does not simulate individual pipe-line stages or penalties caused by
336 branch-prediction misses or cache misses, so it cannot be used for
337 accurate performance measurement.
338 .Pp
339 .Nm
340 is not timing-accurate.
341 .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