302 lines
9.9 KiB
Groff
302 lines
9.9 KiB
Groff
.\" Apple ][ emulator manpage
|
|
.\" by Aaron Culliney - chernabog@baldmountain.bbn.com - (C) 1997-1998
|
|
.\"
|
|
.\" apple2.6 - manpage which mostly echos README
|
|
.\"
|
|
.\" $Id: apple2.6,v 1.8 1998/08/25 03:00:00 chernabog Exp $
|
|
.\"
|
|
.\" MODIFICATION HISTORY
|
|
.\" v0.5 by Aaron Culliney <chernabog@baldmountain.bbn.com>, Feb 1998.
|
|
.\" v0.6 by Aaron Culliney <chernabog@baldmountain.bbn.com>, Aug 1998.
|
|
.\" This code has nothing to do with my employer, GTE Internetworking,
|
|
.\" BBN Technologies. It was written completely on my own time and on
|
|
.\" my own machine.
|
|
.\"
|
|
.TH APPLE2 6 "31 August 1998"
|
|
.UC 7
|
|
.SH NAME
|
|
apple2, xapple2 \- Apple ][+ and //e emulator
|
|
.SH SYNOPSIS
|
|
.ft B
|
|
apple2
|
|
.PP
|
|
.ft B
|
|
xapple2 [ -noshm ]
|
|
.ft R
|
|
.SH DESCRIPTION
|
|
.I apple2
|
|
(svgalib) and
|
|
.I xapple2
|
|
(X11) both emulate a 64k Apple ][+ and 128k Apple //e computer (the latter
|
|
only if //e support
|
|
compiled in). To use the emulator you need to acquire the original
|
|
][+ and //e ROM files which are not distributed due to copyright
|
|
reasons. The emulator reads standard 143360-byte and 232960-byte disk
|
|
image files with
|
|
.I .dsk
|
|
and
|
|
.I .nib
|
|
suffixes respectively.
|
|
You can also change any images with the extension
|
|
.I .do
|
|
to
|
|
.I .dsk
|
|
and they will work too.
|
|
.PP
|
|
There are only a few command line options:
|
|
.TP
|
|
.I -noshm
|
|
This forces the X11 version to not use the MITSHM extension. This may degrade
|
|
the speed of the emulator but allow you to run it remote.
|
|
.PP
|
|
.ft R
|
|
.SH THE .apple2 FILE
|
|
The emulator reads user preferences from a
|
|
.I .apple2
|
|
file located in your home directory. Copy the
|
|
.I .apple2
|
|
file that comes distributed with the emulator to your home directory.
|
|
You can edit the settings using your favorite editor, but most of the
|
|
settings can be tweaked from within the emulator (see menus section below).
|
|
.TP
|
|
.I speed
|
|
Speed of emulation, 1 - XXX. (Actually this is an inverse delay-loop counter). 1 is
|
|
slow, and XXX is as fast as can be.
|
|
A delay loop is needed to bring the emulation rate down to near what would be
|
|
considered a normal Apple ][ speed.
|
|
The max speed value should be determined by
|
|
.I YOU
|
|
when you compile the emulator.
|
|
For <= 100Mhz Pentium systems, I personally
|
|
like a max value of 100 with a normal apple ][ speed somewhere in the 70s.
|
|
For faster machines, try larger ranges.
|
|
.TP
|
|
.I mode
|
|
Starting emulation mode. One of "][+", "][+ undocumented", "//e". You can
|
|
also dynamically change the emulation mode from within the emulator.
|
|
.TP
|
|
.I disk path
|
|
Toplevel path of disk images directory. Personally I like
|
|
/usr/local/games/apple2/disks.
|
|
.TP
|
|
.I color
|
|
Black/white, lazy color, color, lazy interpolated, interpolated.
|
|
.TP
|
|
.I sound
|
|
Off, pc speaker.
|
|
.TP
|
|
.I joystick
|
|
Off, linear, pc joystick.
|
|
.TP
|
|
.I joystick range
|
|
2 - 256. Range of the joystick values. Good settings are 256 and
|
|
sometimes 128, with centers at 128 and 64 respectively. This often depends on
|
|
the game.
|
|
.TP
|
|
.I origin_x
|
|
X coordinate origin. 128 is good for many games with a range of 256. Others
|
|
like 64 with a range of 128.
|
|
.TP
|
|
.I origin_y
|
|
Y coordinate origin. 128 is good for many games with a range of 256. Others
|
|
like 64 with a range of 128.
|
|
.TP
|
|
.I pc joystick parms
|
|
You can configure this from within the emulator. Select the 'Calibrate'
|
|
option from the F10 menu. If the emulator complains that
|
|
it cannot open the joystick device, make sure the module is loaded.
|
|
.I This option is only valid if you've compiled the emulator with -DPC_JOYSTICK.
|
|
.TP
|
|
.I sensitivity
|
|
1% - 100%. This value is used for the emulated joystick using the
|
|
numeric keypad.
|
|
.TP
|
|
.I system path
|
|
The directory holding the rom files. The emulator won't run if this
|
|
is not set properly. You can only change this by editing the
|
|
.I .apple2
|
|
file.
|
|
.PP
|
|
So here is an example .apple2 file:
|
|
.nf
|
|
speed = 72
|
|
mode = ][+
|
|
disk path = /usr/local/games/apple2/disks
|
|
color = interpolated
|
|
sound = pc speaker
|
|
joystick = pc joystick
|
|
joystick range = 256
|
|
origin_x = 128
|
|
origin_y = 128
|
|
pc joystick parms = 767 693 1344 28 1454 28 13
|
|
sensitivity = 13%
|
|
system path = /usr/local/games/apple2/rom
|
|
.fi
|
|
.PP
|
|
.ft R
|
|
.SH ROM FILES
|
|
The emulator requires several ROM files to run.
|
|
.TP
|
|
.I apple_II.rom
|
|
You need this file for basic ][+ emulation. It contains the 12K ROM
|
|
of your Apple ][+. It is not distributed due to copyright issues, so
|
|
you have to get this file on your own. If you have been running
|
|
another apple2 emulator, you can most likely use its ROM files
|
|
directly. This file is a memory dump of the consecutive addresses
|
|
from D000 to FFFF of the Apple ][+. This file may also be named
|
|
.I apple.rom
|
|
or
|
|
.I apple2.rom,
|
|
but is referenced internally as
|
|
.I apple_II.rom.
|
|
.TP
|
|
.I slot6.rom
|
|
You need this file for basic disk drive emulation. It is 256 byte
|
|
memory dump of the consecutive addresses from C600 to C6FF. This file
|
|
is not distributed again due to copyright issues. This file may also
|
|
be named
|
|
.I controller.rom,
|
|
but is referenced internally as
|
|
.I slot6.rom.
|
|
.TP
|
|
.I apple_IIe.rom
|
|
If //e support was not compiled into the emulator, then you do not need this
|
|
file.
|
|
It is the 32K ROM of your 128k Apple //e, a dump of main memory (bank 0)
|
|
addresses C000-FFFF concatenated with auxiliary memory (bank 1)
|
|
addresses C000-FFFF. Because the
|
|
.I apple_IIe.rom
|
|
contains the C600 slot, you can construct the
|
|
.I slot6.rom
|
|
file from this one. The
|
|
.I apple_IIe.rom
|
|
file may also be named
|
|
.I apple2e.rom
|
|
but is referenced internally as
|
|
.I apple_IIe.rom.
|
|
.TP
|
|
.I character.rom
|
|
A 2048 byte ][+ character rom file. This file is distributed with the
|
|
emulator.
|
|
.PP
|
|
.ft R
|
|
.SH DISK IMAGES
|
|
The emulator reads standard DOS3.3-order 143360 byte '.dsk' images and
|
|
raw-nibble 232960 byte '.nib' images. The emulator can handle images
|
|
which are gzip'ed as long as the suffixes are '.dsk.gz' and '.nib.gz'
|
|
respectively. The emulator simply assumes that /bin/gzip is available
|
|
to compress/decompress these images in place as needed and that you have
|
|
permission to do so.
|
|
.PP
|
|
The images are raw binary dumps, containing the tracks from 0 to 34
|
|
from the original 5.25 disk. For the standard 143360 byte '.dsk'
|
|
format each track is partitioned into sectors of 256 bytes, numbered
|
|
from 0 to 15.
|
|
.PP
|
|
The raw nibblized 232960-byte images are usually made of
|
|
programs that have non-standard formatting as a means of copy
|
|
protection. The nibblized format attempts to preserve the
|
|
non-standard format, and so defeats the copy protection without
|
|
"cracking" the program.
|
|
.PP
|
|
To transfer Apple ][ diskettes into one of these formats requires that
|
|
you own an original Apple ][. Since the drives provided by the IBM
|
|
PC's are not compatible with the original Apple ][ drives there are no
|
|
conversion programs directly available. If you have used other Apple
|
|
][ emulators it is most likely that the files will work with this
|
|
emulator too. For more information on Apple ][ disk formats and such,
|
|
see
|
|
.I Beneath Apple DOS
|
|
by Don Worth and Pieter Lechner, published long ago by Quality Software.
|
|
.PP
|
|
.ft R
|
|
.SH EMULATOR KEYS/MENUS
|
|
.TP
|
|
.I F1
|
|
Interface to switch disk in Drive A, Slot 6. Arrow keys navigate the
|
|
selection. If the disk highlighted is already in the drive, it will
|
|
have a <rw1> or <r1> tag after the name indicating read/write or
|
|
read-only access. Select this disk to eject it. To select a disk,
|
|
you can press 'w' or RETURN to insert it into the drive. Pressing 'w'
|
|
will attempt to open the disk as read/write (if you have permission to
|
|
do so).
|
|
Pressing RETURN defaults to opening the disk read-only. Press
|
|
ESC to accept current settings and exit the menu.
|
|
.TP
|
|
.I F2
|
|
Interface to switch disk in Drive B, Slot 6. Same controls as for
|
|
.I F1.
|
|
.TP
|
|
.I F4
|
|
Pause the emulation. The Pause/Break key will also work. Hit a key
|
|
to resume.
|
|
.TP
|
|
.I F5
|
|
Display the Apple ][+ or //e keyboard layout.
|
|
.TP
|
|
.I F7
|
|
Enter the Debugger console (if this support was compiled into the
|
|
program). See the file DEBUGGER that came with the emulator for
|
|
command information.
|
|
.TP
|
|
.I F9
|
|
Toggles between maximum speed and configured speed. This is useful to 'fastboot'
|
|
programs, and then slip back to normal Apple ][ speed.
|
|
.TP
|
|
.I F10
|
|
General parameter settings menu, including the all-important QUIT option.
|
|
You can edit most of the parameters in your
|
|
.I .apple2
|
|
file from this menu.
|
|
Two options worth mentioning are
|
|
the 'Calibrate' and 'JS Sample' options. 'Calibrate' lets you
|
|
calibrate the PC Joystick device. 'JS Sample' lets you set the sample
|
|
rate of the PC Joystick device. 'Save' lets you save the settings to
|
|
your
|
|
.I .apple2
|
|
file.
|
|
.TP
|
|
.I Special Keys
|
|
The key combination Ctrl-'PrintScrn/SysReq' will reboot the machine.
|
|
The Ctrl-'Pause/Break' combination will reset the machine. Remember
|
|
that 'Pause/Break' alone will pause emulation. AltLeft and AltRight
|
|
keys correspond to the OpenApple and ClosedApple keys (joystick
|
|
buttons 0 & 1). NOTE: In //e mode try Ctrl-AltRight-'Pause/Break'
|
|
sequence for a system self-test. The numeric keypad is used for
|
|
emulated joystick movement.
|
|
.ft R
|
|
.SH BUGS AND STUFF
|
|
See the PROBLEMS file that came with the code.
|
|
.PP
|
|
Using the joystick for some disk images is problematic.
|
|
Apparently there is a bug in Apple ]['s where reading values from the
|
|
joystick ports too quickly results in a smaller value than normal.
|
|
Unfortunately the emulator doesn't emulate this bug in the machine,
|
|
but you can mostly get the same
|
|
effect by changing the range of the joystick. For instance, games like Space
|
|
Rogue and Airheart like a range of 0x80 with the center around 0x40. Most
|
|
other games will like a range of 0x100 with the center around 0x80.
|
|
.PP
|
|
Under X, you may notice that some keys are not working as advertised
|
|
(Pause/Break as reboot for instance). Make sure that these keys are mapped.
|
|
(Run xmodmap -pke for the current mapping).
|
|
.ft R
|
|
.SH MORE INFO
|
|
More information is available in the online newsgroups
|
|
.I comp.emulators.apple2,
|
|
and
|
|
.I comp.sys.apple2.
|
|
.PP
|
|
See also:
|
|
.TP
|
|
.I Apple //e Technical Reference Manual
|
|
.TP
|
|
.I Beneath Apple DOS
|
|
.TP
|
|
.I Beneath Apple ProDOS
|
|
.ft R
|
|
.SH AUTHORS
|
|
Apple //e support and revisions v006, v005, v004, v003 by Aaron Culliney
|
|
(aculline@bbn.com). Revision v002 by Stephen Lee. Original version(s)
|
|
by Alexander Jean-Claude Bottema.
|