APPLE2(1) APPLE2(1)
NAME
apple2, xapple2 - Apple ][+ and //e emulator
SYNOPSIS
apple2
xapple2 [ -noshm ]
DESCRIPTION
apple2 (svgalib) and 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 .dsk
and .nib suffixes respectively. You can also change any images with
the extension .do to .dsk and they will work too.
There are only a few command line options:
-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.
THE .apple2 FILE
The emulator reads user preferences from a .apple2 file located in your
home directory. Copy the .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).
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 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.
mode Starting emulation mode. One of "][+", "][+ undocumented",
"//e". You can also dynamically change the emulation mode from
within the emulator.
disk path
Toplevel path of disk images directory. Personally I like
/usr/local/games/apple2/disks.
color Black/white, lazy color, color, lazy interpolated, interpolated.
sound Off, pc speaker.
joystick
Off, linear, pc joystick.
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.
origin_x
X coordinate origin. 128 is good for many games with a range of
256. Others like 64 with a range of 128.
origin_y
Y coordinate origin. 128 is good for many games with a range of
256. Others like 64 with a range of 128.
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. This option is only valid if you've compiled the emula-
tor with -DPC_JOYSTICK.
sensitivity
1% - 100%. This value is used for the emulated joystick using
the numeric keypad.
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 .apple2 file.
So here is an example .apple2 file:
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
ROM FILES
The emulator requires several ROM files to run.
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 con-
secutive addresses from D000 to FFFF of the Apple ][+. This
file may also be named apple.rom or apple2.rom, but is refer-
enced internally as apple_II.rom.
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 controller.rom, but is referenced
internally as slot6.rom.
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
apple_IIe.rom contains the C600 slot, you can construct the
slot6.rom file from this one. The apple_IIe.rom file may also be
named apple2e.rom but is referenced internally as apple_IIe.rom.
character.rom
A 2048 byte ][+ character rom file. This file is distributed
with the emulator.
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.
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' for-
mat each track is partitioned into sectors of 256 bytes, numbered from
0 to 15.
The raw nibblized 232960-byte images are usually made of programs that
have non-standard formatting as a means of copy protection. The nib-
blized format attempts to preserve the non-standard format, and so
defeats the copy protection without "cracking" the program.
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 con-
version 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
Beneath Apple DOS by Don Worth and Pieter Lechner, published long ago
by Quality Software.
EMULATOR KEYS/MENUS
F1 Interface to switch disk in Drive A, Slot 6. Arrow keys navi-
gate the selection. If the disk highlighted is already in the
drive, it will have a <rw1> or <r1> tag after the name indicat-
ing 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.
F2 Interface to switch disk in Drive B, Slot 6. Same controls as
for F1.
F4 Pause the emulation. The Pause/Break key will also work. Hit a
key to resume.
F5 Display the Apple ][+ or //e keyboard layout.
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.
F9 Toggles between maximum speed and configured speed. This is
useful to 'fastboot' programs, and then slip back to normal
Apple ][ speed.
F10 General parameter settings menu, including the all-important
QUIT option. You can edit most of the parameters in your
.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 .apple2 file.
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 emula-
tion. 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.
BUGS AND STUFF
See the PROBLEMS file that came with the code.
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. Unfortu-
nately 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.
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).
MORE INFO
More information is available in the online newsgroups comp.emula-
tors.apple2, and comp.sys.apple2.
See also:
Apple //e Technical Reference Manual
Beneath Apple DOS
Beneath Apple ProDOS
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.
4.4 Berkeley Distribution 31 August 1998 APPLE2(1)
