Kegs

What is this?
-------------

KEGS is an Apple IIgs emulator for AmigaOS, Mac OS X, Linux, and Win32.
The Apple IIgs was the most powerful computer in the Apple II line.
It first was sold in 1986.  An Apple IIgs has the capability to run almost
all Apple II, Apple IIe, and Apple IIc programs.

KEGS uses SDL (Simple DirectMedia Layer) and emulates all Apple //gs
sounds accurately.  It supports limited serial port emulation through
sockets.  Audio emulation for Amiga is imperfect yet.

The ROMs and GS/OS (the Apple //gs operating system) are not included
with KEGS since they are not freely distributable.  KEGS is a little
user-hostile now, so if something doesn't work, let me know what went
wrong, and I'll try to help you out. 

KEGS features:
-------------

Fast 65816 emulation:
	Assembly version: about 8MHz on a 712/80, and 25MHz on a C240.
	C version: about 4MHz on a 712/80, 12MHz on a 266MHz Pentium II.
		About 13MHz on a 240MHz 604e PowerCenter 240 running MkLinux.
Emulates low-level 5.25" and 3.5" drive accesses (even nibble-copiers work!).
Emulates classic Apple II sound and 32-voice Ensoniq sound.
	All sound is played in 16-bit stereo at 48KHz.
Emulates all Apple //gs graphics modes, including border effects.
	Can handle mixed-displays (superhires at the top, lores at the bottom).
	Always does 60 full screen video updates per second.
Mouse and joystick support.
Emulates all Apple //gs memory "tricks" for full compatibility.
Low-level ADB keyboard and mouse emulation enables Wolfenstein 3D to run.
Clock chip emulation makes the Unix time available to the Apple //gs.
Emulated battery RAM remembers control panel settings.
Limited SCC (serial port) emulation to enable PR#1/2 IN#1/2 and other
	serial programs to work, but it is still a bit buggy.

KEGS by default emulates a 4MB Apple //gs, but you can change this with
the "--mem" command line option.

KEGS is so accurate, even the built-in ROM selftests pass (you must be in
2.5MHz speed mode to pass the self-tests).

Release info:
------------

Included files:
	CHANGES			- Description of changes since last release
	README.kegs		- you're here
	README.compile		- Describes how to build KEGS
	README.linux.rpm	- Describes how to install KEGS's RPM for Linux
	INTERNALS.overview	- description of how KEGS works
	INTERNALS.xdriver	- Describes the xdriver.c routines for porting
	INTERNALS.iwm		- Describes the internal 3.5" and 5.25" disk
				   handling routines
	KEGS			- the executable, AmigaOS 4
	kegs.spec		- The Linux spec file for making an RPM
	font.65sim		- C-like description of the font KEGS uses.
	kegs_conf		- disk image configuration info
	to_pro			- Hard-to-use ProDOS volume creator
	partls			- Lists partitions on Apple-partitioned hard
				   drives or CD-ROMs
	dc2raw			- Converts Mac Disk Copy images to raw fmt
	xgs2raw			- Script converts .xgs files to KEGS's raw fmt
	src/			- All the source code, with a Makefile

You need to provide:

	1) Patience.
	2) a ROM file called "ROM" in the KEGS directory.  It can be either
		from a ROM 01 (131072 bytes long) or from a ROM 03 machine
		(262144 bytes long.)
	3) A disk image to boot.  This can be either "raw" format or 2IMG.
		See discussion below.  GS/OS would be best.
	4) Edit the file called "kegs_conf" describing what images you want
		KEGS to use.

Getting ROMs
------------

You need a copy of the memory from fe/0000 - ff/ffff from a ROM 01 GS
or fc/0000 - ff/ffff from a ROM 03 GS, and put that in a file called
"ROM".  I'll eventually get detailed instructions on how to do this.

You may find it convenient to also get a file of the Disk II ROMs
from a real Apple II Disk II card and place that in "c600.rom".  This
will improve compatibility with Apple II, II+, and //e programs.

Running KEGS:
------------

Provided in the distribution is an AmigaOS 4 binary, "KEGS" of PPC
native binary compile.  Full source and a makefile is provided
to allow you to compile for other AmigaOS revisions or for other platforms.
See the README.compile file for more info about compiling.

Running it from workbench is as trivial as double-clicking on it's icon,
assuming you obtained the ROM file correctly.

Assuming all goes well, KEGS will then boot your disk image.  See below
for how to tell KEGS what disk images to use.

You can change the memory size using the "--mem" option, see the command
line flags later in this file.

Images (kegs_conf):
------------------

You tell KEGS what disk images to use through the kegs_conf file.
(There are now alias names available for this file: kegs_conf, disk_conf,
and .kegs_conf).  You must set this up before running KEGS.

KEGS can handle "raw", 2IMG, 5.25" ".nib" images, or partitioned images
now.  The raw image format has no header of any type.  KEGS uses the
Unix file permissions to encode the read/write status of the image.
2IMG encodes some information in a header in front of the image (so 800K
disk images are a little bigger than 800K).  Partitions are described
below.

An image is the representation of an Apple //gs disk, but in a file on
Unix.  For 3.5" disks, for example, a raw image would be exactly 800K bytes
long (819200 bytes).  KEGS intercepts the emulated GS accesses to the
image, and does the correct reads and writes of the Unix file instead.

KEGS uses kegs_conf to describe what to load into each virtual disk slot.
The format of the file is very simple.  A '#' indicates a comment--the
rest of the line is ignored.  Otherwise, each line needs to be of the
form:

s6d1 = dos33.dsk

...where the above line means to load the image called 'dos33.dsk' into
KEGS as slot 6, drive 1.  Images loaded into slot 6 (drive 1 or 2) are
assumed to be 140K 5.25" disks in DOS 3.3 sector order, which means all
".dsk" images available on the net should work.  Images loaded into slot
5 (drive 1 or 2) are assumed to be 800K disk images in ProDOS block
format (of which there are none on the net, but see below on how to
convert other types into raw format).  Images loaded into slot 7 (drives
1 through 32) are assumed to be in ProDOS block format, and can be any
size up to 4GB.  Images in slot 7 can also be partitions.

KEGS boots s7d1 by default.  You can change this using the emulated //gs
control panel, just like a real Apple //gs.  KEGS emulates a //gs with
two 5.25" drives in slot 6, two 3.5" drives in slot 5, and up to 32
"hard drives" in slot 7.

The provided sample kegs_conf contains:
	# Paths to images for KEGS

	s5d1 = XMAS_DEMO

	s7d1 = NUCLEUS03
	s7d2 = SAMPLE_IMAGE

If you don't have each of those images loaded, KEGS may fail to start
correctly.  If you don't have the image, comment the line out of kegs_conf.

To do "useful" things with KEGS, you need to get a bootable disk image.
You can ftp to ftp.info.apple.com and get System 6 at:
/Apple_Support_Area/Apple_Software_Updates/US/Apple_II/Apple_IIGS_System_6.0.1/
There used to be ".bxy" files there, which nulib can extract using the
'nulib bx foo.bxy' command which extracts a file called foo.shk, which you
then turn into a disk image with 'nulib xv foo.shk' to extract a raw
image file, which is exactly the format KEGS wants.
Unfortunately, Apple now only has .sea files which are executable files
for Macintosh only.  You need a macintosh to execute those programs,
which creates Disk Copy image files with no special extensions (and with
spaces in the names).  Once you get those files back to Unix, you
can use the provided utility dc2raw to convert the disk image format
back into a raw file that is exactly 800K long.

KEGS also supports partitioned devices.  For instance, if you have a CD-ROM
on your workstation, just pop an Apple II CD in, and KEGS can mount it.
Use "partls" to list the partitions on the CD.  For instance,

partls /dev/dsk/c201d2s0

if your CD is at that address (that's SCSI ID 2 on the SCSI bus of a
712 workstation).  (Partls was compiled for HP-UX 10.20.  If you have an
earlier version or HP-UX, you need to recompile to get it to work.
See README.compile).

The output will list the various partition names in the first column.  You can
mount any partition, but look at the "type" for Apple_PRODOS or
Apple_HFS for interesting ones.  Mounting "Apple_Driver" is the
Macintosh code for a SCSI driver--not too useful.  "Apple_Free" is a
partition containing all the unused blocks--also not useful to mount.

An example from the Golden Orchard CD:
$ partls  /dev/dsk/c201d2s0   
 0:Apple                 size=  0.03MB type=Apple_partition_map
 1:Macintosh_SL          size=  0.02MB type=Apple_Driver
 2:GO.ProDOS             size= 20.00MB type=Apple_PRODOS
 3:GO-Main               size= 70.85MB type=Apple_HFS
 4:Back                  size=351.49MB type=Apple_Free
 5:GO-Misc16bit          size= 80.00MB type=Apple_HFS
 6:GO-Programming        size=125.00MB type=Apple_HFS
 7:GO-Disks              size=144.00MB type=Apple_HFS
 8:GO-Applications       size= 82.00MB type=Apple_HFS
 9:GO-G.S.               size=128.00MB type=Apple_HFS

To mount a partition, the kegs_conf should look like:

s7d10 = /dev/dsk/c201d2s0:GO-Main

KEGS interprets everything up to a colon as the Unix device file, and
everything after as the partition name.  I recommend using /dev/dsk/
paths instead of /dev/rdsk/ for CD-ROMS since /dev/dsk can be cached in
the Unix buffer cache for a big speed boost.  For floppies or real hard
drives, use /dev/rdsk.  I'll fix KEGS to use O_SYNC soon, which would
mean you could use /dev/dsk all the time.

The sample kegs_conf has commented-out sample entries for the Golden Orchard
Apple II CD-ROM.

Since KEGS needs low-level access to the CD-ROM, you should make the
permissions on the /dev/dsk/* files something like:

brw-r--r--   1 root     sys        7 0x201200 Jun 10 00:01 /dev/dsk/c201d2s0

Running KEGS as root is NOT recommended.

If you do not have any disk mounted in s7d1, KEGS will jump into BASIC.

KEGS cannot determine what size /dev/rfloppy is, so you must give it a
hint.  To tell KEGS you want to mount a 1440K floppy at /dev/rfloppy/c20Ad1s0,
use:

s7d6,1440 = /dev/rfloppy/c20ad1s0

All disks in s5dX are 800K, and cannot be changed.  All disks in s6dX are
140K and cannot be changed.  Only disks in s7dX can have the size specified.

Partitions can also be mounted by number.  The ProDOS partition of
the Golden Orchard CD (partition 2, GO.ProDOS) can be mounted as:

s7d1 = /dev/dsk/c201d2s0:2

This is useful if the disk you are trying to use has blank partition
names.

You can skip drive numbers--it's ok to have a disk in s7d20, and nothing
in s7d10-s7d19.

User geoff()gwlink.net adds some notes for mounting disks/floppies/CDs under
Solaris:

  To use a CDROM, insert the CD and let Volume Management mount it.
  Edit kegs_conf and use the filesystem that shows up in the "df -k"
  listing.  The volume name of the CDROM must be included.  For example,
  a CDROM in an IDE drive would look like this:

  s7d19 = /vol/dev/dsk/c1t0d0/ciscocd

  A CDROM in a SCSI drive would look like this:

  s7d20 = /vol/dev/dsk/c0t6d0/j1170_10804

  For floppy use, insert the floppy and run volcheck.  All you need is this 
  in kegs_conf to handle any compatible floppy:

  s7d20,1440 = /vol/dev/aliases/floppy0


The s6d* and s5d* drives support disk swapping and disk ejecting.
For disk swapping, you just edit the kegs_conf file while KEGS is running,
and KEGS will re-parse the file and load in the images you request.
If you comment out a line which is a mounted disk, KEGS "ejects" that
image.

One common use for disk swapping is to run a two-disk 5.25" program
that doesn't look in s6d2.  Set up kegs_conf with:

s6d1 = image1.dsk
s6d2 = image2.dsk

...and then when you want to insert image2 in s6d1, just edit kegs_conf to:

s6d2 = image1.dsk
s6d1 = image2.dsk

...and then you've "inserted" image2.dsk into s6d1.

If a Linux user would chime in with any Linux specifics, I'd be happy
to add them here in the future.

Since a real Apple //gs can eject 3.5" disks, so can KEGS.  If the
Apple //gs wants to eject the disk, KEGS will put a '#' in front of
that disk image name in kegs_conf, and eject the disk.

Support for 5.25" nibblized images is read-only for now (since the
format is kinda simplistic, it's tricky for KEGS to write to it).
Just mount your image, like "disk.nib" in the kegs_conf file like
any .dsk or .po image.


Debugging KEGS:
--------------

KEGS has a lot of debug "traps"--on an unexpected event, it stops the
emulation, and puts the terminal window in a debugger that is similar to
the GS ROM monitor debugger (but not exactly).  Thus, if you think it
should continue after what ever stopped it, type "g" then return in the
terminal window.  You can look at the message before it stopped to get
an idea of why it stopped.  For instance, KEGS stops on accesses to
non-existent memory.  Many buggy programs do this occasionally, like
Appleworks GS.  In most cases, try "g", and if it doesn't continue, let
me know.  Copy the terminal output and mail it to me.  You can "chain"
the g's together--so if you want it to skip 10 breakpoints, just say
"gggggggggg" then hit return.  You may need to do this with some Ensoniq
problems.

If this is really bothersome running some programs, try the "-ignbadacc"
command-line option.  It tells KEGS to not print messages about bad
memory accesses.

KEGS also supports breakpoints and watchpoints.  In the debug window, you
set a breakpoint at an address by typing the address, followed by a 'B'
(it must be in caps).  To set a breakpoint on the interrupt jump point,
type:

e1/0010B

To list all breakpoints, just type 'B' with no number in front of it.
To delete a breakpoint, enter its address followed by 'D', so

e1/0010D

deletes the above breakpoint.  The addresses work like the //gs monitor:
once you change banks, you can use shortcut addresses:

e1/0010B
14B

will add breakpoints at e1/0010 and e1/0014.

This is a "transparent" breakpoint--memory is not changed.  But any
read or write to that address will cause KEGS to halt.  So you can
set breakpoints on I/O addresses, or ROM, or whatever.  Setting a breakpoint
slows KEGS down somewhat, but only on accesses to the 256 byte "page"
the breakpoint is on. Breakpoints are not just instruction breakpoints,
they also cause KEGS to halt on any data access, too (usually called
watchpoints).

You can view memory using 'start.end' address notation, or disassemble
using the 'L' or 'l' command.  KEGS can print out instruction history traces
if you define LOG_PC in engine_s.s or engine_c.c and recompile.  When
you hit a breakpoint, hit "P" and it will dump the trace to pc_log_out.
Similar tracing is available for Ensoniq state.  SCC state tracing is
always active, and you can get a dump to the debugger window using 'Z'.
IWM state is available with 'I'.  An executable with LOG_PC defined
will run at about half speed, but it's invaluable for debugging difficult
failures.

Virtually every capital letter does some debug function--see dis.c for
the big switch statement.  I'll document all of them someday.

Using KEGS:
----------

The Amiga  mouse  is  the  mouse and joystick.  By default, the mouse
is not constrained inside the window.  Press F8 to hide the X windows
cursor and constrain the mouse.  F8 again toggles out of constrain mode.

The default joystick is the mouse position.  Upper left is 0,0.  Lower right
is 255,255.  

The left mouse button is the mouse button for KEGS.  The right mouse
button toggles between three speed modes.  Mode 0 means run as fast as
possible.  Mode 1 means run at 1.024MHz.  Mode 2 means run at 2.5MHz.
Most Apple II games need to be run at 1.024MHz.  Many Apple //gs demos
must run at 2.5MHz.  If a program/demo appears to crash in KEGS, try
forcing speed to 2.5MHz and then running it.

The middle mouse button causes KEGS to stop emulation, and enter the
debugger.  You can continue with "g" then return in the debug window.
You can also disassemble memory, etc.  The section "Debugging KEGS"
above describes the debugger interface a little more.

KEGS has no pop-up menus or other interactive interfaces (other than
the debug window).  Input to the debug window is only acted upon when
the emulation is stopped by hitting a breakpoint or pressing the middle
mouse button.

Quitting KEGS:
-------------

Either ctrl-C in the debugger window at any time, or press the middle-mouse
button in the emulation window, and then type "q" return in the debug window.
Or simply click the close window gadget, if you are running it in window mode.

KEGS command-line option summary:
--------------------------------
  --badrd            Halt on bad reads.
  --ignbadacc        Ignore bad memory accesses (e.g. for Appleworks GS).
  --mem BYTES        Set memory size to BYTES.
  --skip FRAMES      Skip FRAMES frames between screen redraws.
  --audio DEVNUM     Use audio device type DEVNUM (0=none, 1=native, 2=SDL,
                     3=Alib).
  --arate RATE       Use RATE as preferred audio rate.
  --video DEVNUM     Use video device type DEVNUM (0=none, 1=X11, 2=Win32,
                     3=SDL).

  --dhr140           Use simple dhires colormap.
  --joystick DEVNUM  Use joystick device type DEVNUM (0=none, 1=mouse, 2=linux,
                     3=keypad, 4=Win32, 5=SDL).
  --verbose MODE     Set verbose mode to MODE (obtained by or-ing the following
                     values: 0x001=DISK, 0x002=IRQ, 0x004=CLK, 0x008=SHADOW,
                     0x010=IWM, 0x020=DOC, 0x040=ADB, 0x080=SCC, 0x100=TEST,
                     0x200=VIDEO).

Command/Option keys:
-------------------

The following keys are Option (closed-apple) (not all keyboards have all
keys):  Meta_R, Alt_R, Cancel, Print_screen, Mode_switch and the Windows
key just to the right of the spacebar.  The following keys are Command
(open-apple):  Meta_L, Alt_L, Menu, Scroll_lock, the Windows key left of
the spacebar, and the Windows key on the far right that looks like a
pull-down menu.

If you can't get any of these to work on your machine, let me know.
Note that AmigaOS often has other things mapped to Meta- and Alt-
key sequences, so they often don't get passed through to KEGS.  So it's
best to use another key instead of Alt or Meta.  lAmiga-lAlt-Up-arrow
often means "Move Pointer Up" to Amiga, which means it isn't passed on
to KEGS.

The joystick/paddle buttons are just the Command and Option keys.

Reset:
-----

The reset key is Backspace.  You must hit it with Ctrl to get it to
take effect (just like a real Apple //gs).  Ctrl-open_apple-Reset
forces a reboot.  Ctrl-Close_apple-Open_apple-Reset enters selftests.
Selftests will pass if you force speed to 2.5MHz using the right mouse
button.  Watch out for ctrl-lalt-ralt it will likely cold reboot
your Amiga.

How to use "to_pro":
-------------------

This lame utility solves two problems:  It "formats" large disk images,
and lets you move files from Unix into the simulator.  It does this
by taking the files you provide, and putting them onto Unix file called
"POOF1" that is an image in ProDOS format.

So, if you have a wolfdemo.bxy file from an FTP site, you can get it
into the emulator by:

to_pro -800 wolfdemo.bxy

which creates an 800K Unix file called "POOF1".  POOF1 is now an
image that can be loaded into KEGS, and when you catalog it, it will
have wolfdemo.bxy on it.  Warning: to_pro was compiled on HP-UX 10.20,
and will not run on earlier versions of HP-UX--you have to re-compile it
(which is easy) to make it work.  See README.compile.

To create a 4MB image:

to_pro -4096 wolfdemo.bxy

which puts wolfdemo.bxy on a much larger image.

I don't know what happens if the file, wolfdemo.bxy, is bigger than
the image...it probably crashes.

Even if you want to format a "blank" image, you have to put something in it.
Like:

echo "This is a lame utility" > foo
to_pro -16384 foo

...creates a 16MB POOF1 with the file foo on it.  Just delete foo
from within KEGS.

See?  I told you it was a lame utility!

to_pro can handle up to 51 files at a time--for example:

to_pro -32000 *.shk

...would put all *.shk files in the current Unix directory into a 31.25MB
image called POOF1.

To_pro tries to truncate Unix filenames to the 15 character ProDOS
limit, and converts all punctuation to dots.  I've tested it enough
that it has worked for my purposes.

The algorithm to_pro uses to create a disk volume is possibly suspect.
I recommend reformatting any images again inside KEGS (using GS/OS, for
instance) just to make sure the directory structure is good.  To_pro
is intended to put files into images quickly and easily, and then to
copy the files off of those images onto images formatted from within
KEGS by an Apple //gs OS.

Since ProDOS cannot handle > 32MB images, make sure you run to_pro with
arguments under 32767.  I personally haven't tried a partition bigger
than 30000K (about 2.5MB short of the maximum).  Well, you can use bigger
images if you format them HFS, but I don't trust the GS/OS HFS driver.

To_pro automatically sets the ProDOS filetype of files ending in ".shk"
to $E0.

Details on kegs_conf/images:
---------------------------

The file "kegs_conf" describes the images KEGS will use.  The sample
file has all the lines commented out with '#' to show sample uses.
Remember, KEGS will boot s7d1 (unless you've changed that using the
Apple //gs control panel), so you must put an image in that slot.

KEGS watches the file "kegs_conf", and if it changes, it re-reads it
and reloads disk images.  That is, while KEGS is running, you can
edit kegs_conf using, say, vi, and add or change disks.  KEGS will print
messages in the debug window describing what new disks it has found.
Changing disks in slot 7 does not work, but you can move around
disks in slots 5 and 6.  This allows you to "eject" disks and change them.
This is especially useful for multi-disk 5.25" programs.

KEGS uses the Unix permissions on raw disk images to decide how to load
it into the emulator.  If the file is unreadable, it cannot load the
image (duh).  KEGS used to support the concept of "Write-through-to-Unix",
but I've removed it since only one user found it slightly useful, and
many new users struggled with it.

Here's what various Unix permissions mean to KEGS:

rwx
-**: Unreadable image
r--: Read-only image.  Image will appear write-protected in KEGS.
rw-: Read-write image.  Image will appear writeable in KEGS, and changes
	will be passed through to the Unix file

KEGS, by default, runs the IWM (3.5" and 5.25" disks) emulation in an
"approximate" mode, called "fast_disk_emul".  In this mode, KEGS
emulates the hardware "faster" than real, meaning the data the code
being emulated expects is made available much faster than on a real
Apple //gs, providing a nice speed boost.  For instance, the 5.25"
drives run 10x the real speed usually.  Almost everything will work
except for nibble copiers, which don't like the data coming this fast.
(Meaning, unless you're using a nibble copier, you shouldn't run into an
issue.  All games/demos/etc run fine in this mode).  To make nibble
copiers work, Press F7.  Earlier versions of KEGS had a bug in
fast_disk_emul which made it unable to format 5.25" disks under GS/OS,
but that bug has been fixed.

KEGS always does low-level emulation of 5.25" and 3.5" drive hardware.  It
is very accurate, supporting nibble-copiers, etc.  KEGS can read in
the ".nib" nibblized disk format, but as read-only mode.  If
the emulated image is no longer ProDOS or DOS 3.3 standard, KEGS will
automatically treat the image as "Not-write-through-to-Unix" from then
on.  This mode means KEGS will continue to emulate the disk properly in
memory, but it cannot encode the changes in the standard .dsk or .nib
image format.  It prints a message saying it has done so.  However,
the "disk" in emulation is fully useable as long as KEGS is running.  A
standard reformatting will not cause an image to flip to not-write-
through-to_unix, but running things like a "drive-speed" test will cause
further changes not to propagate to the Unix file.  You will need
to "eject" the image and re-insert it before writes will take effect.

In full accuracy mode (i.e., not fast_disk_emul), 5.25" drive accesses
force KEGS to run at 1MHz, and 3.5" drive accesses force KEGS to run at
2.5MHz.

KEGS Timing:
-----------

KEGS supports running at three speeds:  1.024MHz, 2.5MHz, or "as fast as
possible".  Pressing the middle mouse button toggles between these
modes.

KEGS will always run at 1.024MHz at least.  If it is unable to keep up,
it will extend the emulated time to maintain the illusion of running
at 1MHz.  That is, it may do just 40 screen refreshes per real second,
instead of the usual 60.  It is difficult to get KEGS so bogged down
in overhead that it cannot maintain 1MHz.  Let me know if you find an
application which does.

If you force KEGS to run at 1.024MHz, it will strive to run at exactly
1.024MHz.  If it is running faster (almost always), it will pause
briefly several times a second to maintain the 1MHz speed.  It does this
in a Unix-friendly way that makes time available to other Unix
processes.  This makes older Apple II games very playable just like a
real Apple //gs on slow speed.  KEGS is running at exactly the same
speed as an Apple //e when in 1.024MHz mode.  The 1.024MHz mode you set
through the middle mouse button overrides the "fast" mode you can access
through the control panel.  But, 3.5" accesses will "speed up" to 2.5MHz
to enable that code to operate correctly while the 3.5" disk is being
accessed.  If KEGS is running fast, the small pauses cause KEGS to give
time to other applications, which you can see via the Unix "top"
command.

If you force KEGS to run at 2.5MHz, KEGS tries to run at 2.5MHz.  But
like a real unaccelerated Apple //gs, if you set the control panel to
"slow", it will really be running at 1.024MHz.  Accesses to 5.25" disk
automatically slow down to 1.024MHz, when running the IWM in accurate
mode (F7).  KEGS may not be able to keep up with some programs running
at 2.5MHz due to video and sound overheads on lower-end machines.  If
that happens, it effectively runs slower by extending the emulated
"second", like in the 1.024MHz mode.  You can tell this is happening
when Eff MHz in the status area falls below 2.5MHz.  If KEGS is running
faster than 2.5MHz, it takes small pauses to slow down, just like in
1.024MHz.  Many Apple //gs demos must be run at 2.5MHz.  The built-in
selftests (cmd-option-ctrl-Reset) must run at 2.5MHz.  Many Apple //gs
action games are more playable at 2.5MHz.

Letting KEGS run "as fast as possible" means KEGS will run at whatever
speed it is able to, above 1.024MHz (if it falls below 1.024, it
extends the emulated second).  Eff MHz gives you the current Apple //gs
equivalent speed.  Many games will be unplayable at the unlimited setting.
Setting the //gs control panel speed to "slow" will slow down to 1MHz.

Sound output has an interesting relationship to KEGS timing.  KEGS must
play one second of sound per second of emulated time.  Normally, this
works out exactly right.  But as noted above, if KEGS can't maintain the
needed speed, it extends the emulated second.  If it extends the second
to 1.4 real seconds, that means KEGS only produces 1.0 second of sound
data every 1.4 seconds--the sound breaks up!  Unfortunately, some demos
require 2.5MHz timing--on slow machines, you just have to let the sound
break up to see the visual effects (especially border effects).  Sorry.
Get a faster machine and this problem goes away.


KEGS:  What works:
-----------------

Basically, just about every Apple II program works.  See the file
README.a2.compatibility for directions on how to make certain games/programs
work.

KEGS is EXTREMELY compatible.  But, I haven't tested everything.  Let
me know if you find a program which is not working correctly.

Some old Apple II 5.25" games require the old C600 ROM image, and don't work
with the default Apple IIgs ROM.  This is not KEGS's fault--these games
don't run on a real Apple IIgs either.  KEGS has built-in the old Apple II
Disk PROM which you can enable by using the IIgs control panel to set
Slot 6 to "Your Card".  This allows many more Apple II games to run, and
is the recommended setting.

The NinjaForce Megademo mostly works, but sometimes hangs in the BBS Demo.
Just skip that demo if it happens.

The California Demo hangs at startup unless you use the IIgs control panel
to boot from slot 5, and then do a ctrl-Open_Apple-Reset to boot--doing
the above lets it work fine. This seems to be a bug in the demo.


KEGS bugs:
---------

On a ROM03, KEGS makes a patch to the ROM image (inside emulation, not
to the Unix file) to fix a bug in the ROM code.  Both ROM01 and ROM03
are patched to enable use of more than 8MB of memory.  I then patch the ROM
self-tests to make the ROM checksum pass.  But other programs, like
the Apple IIgs Diagnostic Disk, will detect a ROM checksum mismatch.
Don't worry about it.

Sound breaks up if KEGS is unable to keep up--it should only be happening
if you are trying to force KEGS to run at 2.8MHz, but cannot due to
sound and video overhead.


Sound emulation:
---------------

KEGS supports very accurate classic Apple II sound (clicking of the
speaker using $C030) and fairly accurate Ensoniq sound.

When KEGS determines that no sound has been produced for more than
5 seconds, it turns off the sound calculation routines for a small
speedup.  It describes that it has done this by saying "Pausing sound"
in the debug window.  However, when sound restarts, it sometimes
"breaks-up" a little.  I will work on fixes for this.

If your display is not using shared memory, audio defaults to off unless
you override it with "-audio 1".

SCC (Serial Port) emulation:
---------------------------

KEGS emulates the two serial ports on a IIgs as being two Unix sockets.
Port 1 (printer port) is at socket address 6501, and port 2 (modem)
is at socket address 6502.

By default, slot 1 is emulated using a simple receive socket, and slot 2
emulates a Virtual Modem.

A Virtual Modem means KEGS acts as if a modem is on the serial port
allowing Apple II communcation programs to fully work, but connected to
internet-enabled sockets.  KEGS emulates a "Hayes- Compatible" modem,
meaning it accepts "AT" commands.  You can use KEGS to connect to free
telnet-BBSs, or run a BBS program on KEGS and become a telnet BBS yourself.

The two main AT commands are: ATDT for dialing out, and ATA for receiving
calls.  To dial out, enter "ATDThostname", or for example,
"ATDTboycot.no-ip.com" (which is down at the moment, unfortunately).
You can also enter an IP address, like "ATDT127.0.0.1".  On a Mac, to
create a telnet server to allow telnet connections (do not use over the
internet, but on a private network behind a firewall, this should be
fine), in a Terminal window type: "sudo /usr/libexec/telnetd -debug".
You must then enable telnet on port 23 through your Mac OS X Firewall in
the System Preferences->Sharing->Firewall page (just add port 23 as
open--you'll need to use the "New..." button and then select Other for
Port Name, and enter Port Number as 23). Then from KEGS in a
communications program, do "ATDT127.0.0.1", and then log-in to your Mac.

KEGS also accepts incoming "calls".  Start KEGS, and initialize the
Virtual Modem with some AT command (ATZ resets all state, and is a useful
start).  KEGS now has a socket port open, 6502 for slot 2, which you
can connect to using any telnet program.  In a Terminal window, then
type "telnet 127.0.0.1 6502" and you will connect to KEGS.  The Virtual
Modem then starts printing "RING" every 2 seconds until you answer with
"ATA".  You are now connected.  I have not tried BBS programs, but have
made connections with ProTERM.

On Windows XP SP2, when KEGS tries to open this incoming socket, you'll
need to enable it and click Unblock to the dialog that Windows pops up.
If you do not want incoming connections, you can block it instead.

Once connected, you can go back to talking to the Virtual Modem by
pressing + three times quickly (+++), and then not type anything for a second.
This goes back to the AT-command mode.  You can now "ATH" to hang up, or
"ATO" to go back online.

On Windows, the socket code is very preliminary and there are problems
receiving connections.

KEGS also supports an older, simpler socket interface, which it defaults
to using on slot 1.  In KEGS, from APPLESOFT, if you PR#1, all output will
then be sent to socket port 6501.  You can see it by connecting to the
port using telnet.  In another terminal window, do: "telnet localhost 6501"
and then you will see all the output going to the "printer".

Under APPLESOFT, you can PR#1 and IN#1.  This gets input from the
socket also.  You can type in the telnet window, it will be sent on
to the emulated IIgs.  You may want to go to the F4 Config Panel and set
"mask off high bit" for serial port accesses to make PR#1 work a little nicer.

You can "print" from BASIC by using something like PR#1 in KEGS and
"telnet localhost 6501 | tee file.out" in another window.


KEGS status area:
----------------

The status area is updated once each second.  It displays info I am
(or was at some time) interested in seeing.

Line 1: (Emulation speed info)
dcycs:  number of seconds since KEGS was started
sim MHz:  Effective speed of KEGS instruction emulation, not counting
	overhead for video or sound routines.
Eff MHz:  Above, but with overhead accounted for.  Eff MHz is the
	speed of an equivalent true Apple IIgs.  This is extremely
	accurate.
sec:	The number of real seconds that have passed during on of KEGS's
	emulated seconds. Should be 1.00 +/- .01.  Under 1
	means KEGS is running a bit fast, over 1 means KEGS is
	running slow.  When you force speed to 2.5MHz, if KEGS
	can't keep up, it extends sec, so you can see how slow
	it's really going here.
vol:	Apple IIgs main audio volume control, in hex, from 0-F.
pal:	Super-hires palette that is unavailable.  KEGS needs one palette
	for the standard Apple // graphics mode on an 8-bit display,
	and it grabs the least-used palette.  Defaults to 0xe.
	You can try changing it with F10.  If you change it to a
	palette that is not least used, KEGS changes it back in
	one second.  Any superhires lines using the unavailable
	palette will have their colors mapped into the
	closest-matching "lores" colors, to minimize visual
	impact.
Limit:	Prints which speed setting the user has requested: 1MHz, 2.8MHz,
	or Unlimited.

Line 2: (Video and X info)
xfer:  In hex, number of bytes transferred to the X screen per second.
xred_cs:	Percentage of Unix processor cycles that were spent in the X
	server (or other processes on the machine).
ch_in:	Percentage of Unix processor cycles spent checking for X input Events.
ref_l:	Percentage of Unix processor cycles spent scanning the Apple IIgs
	memory for changes to the current display screen memory,
	and copying those changes to internal XImage buffers.
ref_x:	Percentage of Unix processor cycles spent sending those XImage buffers
	to the X server.  Very similar to xred_cs.

Line 3: (Interpreter overhead)
Ints:  Number of Apple IIgs interrupts over the last second.
I/O:	Rate of I/O through the fake smartport interface (hard drives).
	Does not count 3.5" or 5.25" disk accesses.
BRK:	Number of BRKs over the last second.
COP:	Number of COPs over the last second.
Eng:	Number of calls to the main instruction interpreter loop in the
	last second.  All "interrupts" or other special behavior
	causes the main interpreter loop to exit.  A high call
	rate here indicates a lot of overhead.  12000-15000 is normal.
	20000+ indicates some sort of problem.
act:	Some instructions are handled by the main interpreter loop returning
	special status "actions" to main event loop.  This is the
	number over the last second.  Should be low.
hev:	This tracks HALT_EVENTs.  KEGS returns to the main loop to recalc
	effective speed whenever any speed-changing I/O location is
	touched.  See the code, mostly in moremem.c
esi:	This counts the number of superhires scan-line interrupts
	taken in the last second.
edi:	This counts the number of Ensoniq "special events" over the last
	second.  A sound that stops playing always causes a KEGS
	event, even if it doesn't cause a IIgs interrupt.

Line 4: (Ensoniq DOC info)
snd1,2,3,4:  Percentage of Unix processor cycles spent handling various
	sound activities.  snd1 is the total sum of all sound overhead.
st:	Percentage of Unix cycles spent starting new Ensoniq oscillators.
est:	Percentage of Unix cycles spent looking for 0 bytes in sounds.
x.yz:	This final number is the average number of oscillators playing
	over the last second.  Up to 4.00 is low overhead, over
	20.0 is high overhead.

Line 5: (Ensoniq DOC info)
snd_plays:	Number of calls to a routine called sound_play, which
	plays Ensoniq sounds.  Always called at least 60 times per sec.
doc_ev:	Number of Ensoniq (DOC) events in the last second.  A sound
	stopping is an event, but changing a parameter of a sound
	while it is playing is also an event.
st_snd:	 Number of sounds that were started in the last second.
snd_parms:	Number of times a sound parameter was changed while it
	was playing.

Line 6: (IWM info)
For each IWM device, this line displays the current track (and side for
3.5" disks).  If a disk is spinning, there will be an "*" next to the
track number.  Only updated once a second, so the disk arm moving may
appear to jump by several tracks.  "fast_disk_emul:1" shows that KEGS
is using less accurate, but faster, IWM emulation.  Press F7 to toggle
to accurate disk emulation.

Key summary:
-----------

F6:    Enter debugger.
F8:    Grab/release mouse pointer.
F9:    Change paddles emulation speed.
	key doesn't work on my keyboard...sigh).
F10:   Change the emulator videomode.
	the superhires screen looking a little "off", this may help.
F11:   Fullscreen mode On/Off.
F12:   Toggle limit speed - 1.024MHz (Slow),2.8MHz (Normal),
        8.0MHz (Zip Speed), as fast as possible!
Ctrl+F1:  Cycle through the Joystick input method - with this keys combination
	you can select Joystick, Joypad, Mouse or no input at all.



Alt_R, Meta_r, Menu, Print, Mode_switch:   Option key
Alt_L, Meta_L, Cancel, Scroll_lock:        Command key

"Home": Alias for keypad equals (since some Unix keyboards doesn't have an =).

Documentation To-Do:
-------------------

Describe the tracing and breakpoint debug features.
Describe the debug interface.
Describe how the code works.
Describe more of what's known to work.
Describe my changes to SPEEDTEST.

KEGS To-Do:
----------

    * possibility to paste text to the emulator (on SDL, X11 and possibly Win32)
    * disk swapping facility (probably OS-specific too, possibly drag'n'drop).
    * support for keyboards other than QWERTY (like the infamous French
keyboard).


-------------------

If you have any problems/questions/etc., just let me know.

http://hirudov.com
http://devernay.free.fr/apple2/
http://kegs.sourceforge.net