/[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 14 - (show annotations)
Mon Oct 8 16:18:51 2007 UTC (12 years, 4 months ago) by dpavlin
File size: 12006 byte(s)
++ trunk/HISTORY	(local)
$Id: HISTORY,v 1.982 2005/10/07 22:45:32 debug Exp $
20050816	Some success in decoding the way the SGI O2 PROM draws graphics
		during bootup; lines/rectangles and bitmaps work, enough to
		show the bootlogo etc. :-)
		Adding more PPC instructions, and (dummy) BAT registers.
20050817	Updating the pckbc to support scancode type 3 keyboards
		(required in order to interact with the SGI O2 PROM).
		Adding more PPC instructions.
20050818	Adding more ARM instructions; general register forms.
		Importing armreg.h from NetBSD (ARM cpu ids). Adding a (dummy)
		CATS machine mode (using SA110 as the default CPU).
		Continuing on general dyntrans related stuff.
20050819	Register forms for ARM load/stores. Gaah! The Compaq C Compiler
		bug is triggered for ARM loads as well, not just PPC :-(
		Adding full support for ARM PC-relative load/stores, and load/
		stores where the PC register is the destination register.
		Adding support for ARM a.out binaries.
20050820	Continuing to add more ARM instructions, and correcting some
		bugs. Continuing on CATS emulation.
		More work on the PPC stuff.
20050821	Minor PPC and ARM updates. Adding more machine types.
20050822	All ARM "data processing instructions" are now generated
		automatically.
20050824	Beginning the work on the ARM system control coprocessor.
		Adding support for ARM halfword load/stores, and signed loads.
20050825	Fixing an important bug related to the ARM condition codes.
		OpenBSD/zaurus and NetBSD/netwinder now print some boot
		messages. :)
		Adding a dummy SH (Hitachi SuperH) cpu family.
		Beginning to add some ARM virtual address translation.
		MIPS bugfixes: unaligned PC now cause an ADEL exception (at
		least for non-bintrans execution), and ADEL/ADES (not
		TLBL/TLBS) are used if userland tries to access kernel space.
		(Thanks to Joshua Wise for making me aware of these bugs.)
20050827	More work on the ARM emulation, and various other updates.
20050828	More ARM updates.
		Finally taking the time to work on translation invalidation
		(i.e. invalidating translated code mappings when memory is
		written to). Hopefully this doesn't break anything.
20050829	Moving CPU related files from src/ to a new subdir, src/cpus/.
		Moving PROM emulation stuff from src/ to src/promemul/.
		Better debug instruction trace for ARM loads and stores.
20050830	Various ARM updates (correcting CMP flag calculation, etc).
20050831	PPC instruction updates. (Flag fixes, etc.)
20050901	Various minor PPC and ARM instruction emulation updates.
		Minor OpenFirmware emulation updates.
20050903	Adding support for adding arbitrary ARM coprocessors (with
		the i80321 I/O coprocessor as a first test).
		Various other ARM and PPC updates.
20050904	Adding some SHcompact disassembly routines.
20050907	(Re)adding a dummy HPPA CPU module, and a dummy i960 module.
20050908	Began hacking on some Apple Partition Table support.
20050909	Adding support for loading Mach-O (Darwin PPC) binaries.
20050910	Fixing an ARM bug (Carry flag was incorrectly updated for some
		data processing instructions); OpenBSD/cats and NetBSD/
		netwinder get quite a bit further now.
		Applying a patch to dev_wdc, and a one-liner to dev_pcic, to
		make them work better when emulating new versions of OpenBSD.
		(Thanks to Alexander Yurchenko for the patches.)
		Also doing some other minor updates to dev_wdc. (Some cleanup,
		and finally converting to devinit, etc.)
20050912	IRIX doesn't have u_int64_t by default (noticed by Andreas
		<avr@gnulinux.nl>); configure updated to reflect this.
		Working on ARM register bank switching, CPSR vs SPSR issues,
		and beginning the work on interrupt/exception support.
20050913	Various minor ARM updates (speeding up load/store multiple,
		and fixing a ROR bug in R(); NetBSD/cats now boots as far as
		OpenBSD/cats).
20050917	Adding a dummy Atmel AVR (8-bit) cpu family skeleton.
20050918	Various minor updates.
20050919	Symbols are now loaded from Mach-O executables.
		Continuing the work on adding ARM exception support.
20050920	More work on ARM stuff: OpenBSD/cats and NetBSD/cats reach
		userland! :-)
20050921	Some more progress on ARM interrupt specifics.
20050923	Fixing linesize for VR4121 (patch by Yurchenko). Also fixing
		linesizes/cachesizes for some other VR4xxx.
		Adding a dummy Acer Labs M1543 PCI-ISA bridge (for CATS) and a
		dummy Symphony Labs 83C553 bridge (for Netwinder), usable by 
		dev_footbridge.
20050924	Some PPC progress.
20050925	More PPC progress.
20050926	PPC progress (fixing some bugs etc); Darwin's kernel gets
		slightly further than before.
20050928	Various updates: footbridge/ISA/pciide stuff, and finally
		fixing the VGA text scroll-by-changing-the-base-offset bug.
20050930	Adding a dummy S3 ViRGE pci card for CATS emulation, which
		both NetBSD and OpenBSD detects as VGA.
		Continuing on Footbridge (timers, ISA interrupt stuff).
20051001	Continuing... there are still bugs, probably interrupt-
		related.
20051002	More work on the Footbridge (interrupt stuff).
20051003	Various minor updates. (Trying to find the bug(s).)
20051004	Continuing on the ARM stuff.
20051005	More ARM-related fixes.
20051007	FINALLY! Found and fixed 2 ARM bugs: 1 memory related, and the
		other was because of an error in the ARM manual (load multiple
		with the S-bit set should _NOT_ load usermode registers, as the
		manual says, but it should load saved registers, which may or
		may not happen to be usermode registers).
		NetBSD/cats and OpenBSD/cats seem to install fine now :-)
		except for a minor bug at the end of the OpenBSD/cats install.
		Updating the documentation, preparing for the next release.
20051008	Continuing with release testing and cleanup.

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

  ViewVC Help
Powered by ViewVC 1.1.26