XGS: The Portable Apple IIGS(tm) emulator
Version 0.50 -- May 1st, 1997
Written and (C) 1996-97 by Joshua M. Thompson

"Baby's got a master plan...a foolproof master plan." -- Fluke, 'Atom Bomb'

-----------
LEGAL STUFF
-----------

You may distribute this program so long as you do not sell it (selling a CD
of freeware and shareware does not qualify as selling it). All I ask is that
you keep this file intact, and that you include the source code.

Many thanks to Kent Dickey (kentd@hpcuhe.cup.hp.com). Kent not only gave me
a hell of a lot of nice ideas (like the memory handling subsystem for the
slow memory banks), but he even donated code to the project. Thanks, Kent!

I'd also like to thank anyone who has done work on porting XGS to non-Unix
platforms. Their names and email addresses are listed in the PORTS file in
the docs/ subdirectory.

Apple, IIGS, Apple IIGS, and GS/OS are registered trademarks of Apple
Computer, Inc.  All rights reserved.

------------
CONTACT INFO
------------

I can be reached via Internet email as invid@optera.com, and sometimes on
IRC (EFnet) as LrdRayden.

The latest versions of this code will be made available through the XGS
home page. The URL is "http://www.optera.com/~invid/emulators/XGS/".

There is also a mailing list for discussing XGS issues. You can subscribe
by sending mail to "majordomo@optera.com" and including the words
"subscribe xgs-list" on a line by itself in the body of the letter. I
strongly suggest you subscribe to it if you're going to use XGS.

------------
INTRODUCTION
------------

XGS is a program to emulate an Apple IIGS.  This is a beta version; many
features are not implemented yet, and many others don't work exactly like
they should.

The following features are currently implemented:

o CPU emulation
o Memory map emulation
o All known video modes
o Ensoniq sound
o ADB keyboard
o ADB mouse
o Joystick (follows mouse movement)
o Clock chip
o Battery RAM
o IWM hardware emulation for drives in slots 5 and 6 (3.5" / 5.25")
o A 14-unit Extended SmartPort device in slot 5

The following features are NOT currently implemented:

o Serial ports
o True ADB hardware emulation
o Many, many other minor things.

-------------------
SYSTEM REQUIREMENTS
-------------------

o A 90 MHz Pentium or better (it will run on slower, but it'll be virtually
  unusable.)

o A compatible operating system. Ports are currently available for Unix
  systems running an 8-bit X server, Windows 95/NT + DirectX, and MacOS 7.x.

o A copy of the ROMs from a ROM 01 or 03 Apple IIGS (see "How to Use It" below).

----------------------
HOW TO COMPILE (WIN32)
----------------------

Compiling for Win32 is currently supported only on Microsoft Visual C++
Version 4.0 and later. The files in arch/win32/vcplus comprise a Visual
C++ 4.0 project workspace for building the Win32 port of XGS. To use
them you will need to copy them into the main level of the XGS source tree.

The kit assumes you have the DirectX 2 or DirectX 3 SDK installed in
C:\DXSDK. If you have installed it somewhere else you will need to change
the library and include search paths to point to your DirectX includes and
link libraries.

---------------------
HOW TO COMPILE (UNIX)
---------------------

Please read this entire section through at least once before you do anything.

XGS uses the GNU autoconf packages to make configuration quick and painless.
Simply type "./configure" and XGS will (on most systems) configure itself. You
may want to glance over the Makefile and config.h file after doing this, just
to make sure they are correct.

Once XGS is configured, type "make depend" to generate the Makefile
dependancies. You can then type "make install" to build and install XGS. The
default install location is under /usr/local (/usr/local/bin/xgs for the binary
and /usr/local/share/xgs for the fonts and other support files). You can change
this with the --prefix option to configure.

The default configuration generated by the configure program will build a
version of XGS for SVGAlib without sound support. Other configurations are
possible by passing additional parameters to the configure command: 

--with-x		Enable X11 support. If you _don't_ select this, then
			an svgalib version of XGS will be built instead.

--with-oss-sound	Enable sound support for systems supporting the Open
			Sound System API (the "/dev/dsp" device; Linux and
			FreeBSD are in this category).

--with-sparc-sound	Enable sound support for systems supporting the
			"/dev/audio" device, such as SunOS 4.x and Solaris.

--with-mit-shm		Enable support for the MIT shared memory extensions
			to X. XGS will then use shared memory to talk to the
			X server whenever it can.

--with-debug		Enable debugging support, such as the trace mode in
			the CPU emulator. You can leave this disabled unless
			you're trying to track down a problem in XGS.

There are also some useful support utilities included with XGS. To build and
install them, type "make install-utils". They will be installed in the same
directory as the XGS binary.

-------------
HOW TO USE IT
-------------

You will need a ROM image file to make XGS run. You can get the ROMs from a
IIGS by saving them out in 32 KB chunks in AppleSoft BASIC. Boot a ProDOS 8
disk and get into BASIC, then do the following:

**** For a ROM 01 machine: ****

] CALL -151
* 00/800<FE/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000
* 00/800<FE/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$8000
* 00/800<FF/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$10000
* 00/800<FF/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$18000

**** For a ROM 03 machine: ****

] CALL -151
* 00/800<FC/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000
* 00/800<FC/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$8000
* 00/800<FD/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$10000
* 00/800<FD/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$18000
* 00/800<FE/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$20000
* 00/800<FE/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$28000
* 00/800<FF/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$30000
* 00/800<FF/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$38000

The resulting XGS.ROM file should be exactly 131,072 bytes long for a ROM 01
image or 262,144 bytes long for a ROM 03 image. If it isn't then you messed up
somewhere...go back and try again.

You now have to get the file over to your machine. If you've got a Mac this is
easy; the Macintosh can read the IIGS floppy directly. Otherwise you're going
to have to use a serial cable or modem to transfer the file from the IIGS to
your machine.

If you don't have a real IIGS to get the ROMs from then you're on your own.
Apple owns the copyrights on the ROMs, so I can't legally give you a copy (nor
can anyone else). As a result you're probably not going to find them on an FTP
site anywhere.

I will repeat this one more time:

*** I CANNOT (AND WILL NOT) GIVE YOU A COPY OF THE IIGS ROM!! ***
*** SO DON'T SEND ME MAIL AND AND ME ABOUT IT. IT WON'T HELP. ***

Now that that's out of the way, let's move on to actually running the program.
The following support files must be in the XGS lib directory (normally this
will be /usr/local/share/xgs on Unix or C:\XGS on Windows):

xgs40.fnt	The Apple II 40-column screen font for US systems
xgs80.fnt	The Apple II 80-column screen font for US systems
xgs40fr.fnt	The Apple II 40-column screen font for French systems (*)
xgs80fr.fnt	The Apple II 80-column screen font for French systems (*)
xgs.rom		The ROM image 
xgs.ram		The battery ram save file

(*) Move these files to xgs40.fnt and xgs80.fnt if you want to use them. They
    are only needed if you want the IIgs to display the special French
    characters.

If everything looks OK then start XGS. For Unix systems, just type "xgs" and
hit RETURN; for Windows systems double-click on the XGS program icon.

If everything goes well, you should see the virtual IIGS boot and dump you
into AppleSoft BASIC (because you don't have any boot disk image yet -- more
on that later). If you don't get the BASIC screen then you have a problem;
refer to the "Troubleshooting" section below.

For the most part, the keyboard is mapped one-to-one with a IIGS keyboard.
However, there are certain exceptions that are designed to get around
limitations of the various systems on which IIGS runs, as well as special
key sequences to control XGS itself. The exceptions are listed below:

F1			(Win32 only). This is the IIGS escape key.

F3			(Win32 only). This is the IIGS command key.

F4			(Win32 only). This is the IIGS option key.

F5			Toggle joystick emulation on/off. Note that
			you can't turn on joystick emulation unless
			mouse emulation is off!

F6			Toggle mouse emulation on/off. Note that you
			can't turn on mouse emulation unless joystick
			emulation is off!

F12			(Win32 only). This is the IIGS keypad Enter key.
			This is temporary until the Win32 port supports
			keypad keys (The X11 port already does this).

Left Alt		(X11 only). This is the IIGS command key.

Right Alt		(X11 only). This is the IIGS option key.

Control-End		Quits XGS.

Control-Home		Sends a Control-Reset to the emulator.

Control-PageUp		Turns on trace mode (if you conmpiled
			with debugging support). Note that on
			Windows the trace output goes into the
			BOOTLOG.TXT file.

Control-PageDown	Turns off trace mode (if you compiled
			with debugging support).

Pause			Sends a Non-Maskable Interrupt (NMI) to
			the emulator. This is a guaranteed way
			to get into the monitor and poke around.
			This also dumps a copy of banks $00 and $01
			into banks $E8 and $E9 for debugging
			purposes.

Whenever joystick or mouse emulation is on, the pointer is confined to the XGS
window. Turn off the joystick or mouse emulation to move the pointer to other
windows.

The default for the emulator is to emulate a 2 MB machine. To change this, add
the "-ram #" option to the xgs command line, where # is the number of megabytes
to emulate (must be between 1 and 8).

To disable sound emulation (which signifigantly speeds up XGS), start XGS with
the "-nosound" command line option.

-----------------
USING DISK IMAGES
-----------------

XGS allows you to mount files as Apple IIGS disks. These files (called disk
images) must be in a specific format for XGS to recognize them.

For ports that have a GUI interface (such as XGS-Mac and XGS-Win32) you can
use the program's interface to mount images at boot time. Otherwise, you can
use the following command line options when you start XGS:

-s5d1 <image>		Mounts an image on Slot 5, Drive 1 (the first 3.5"
			disk drive). The image must be exactly 1600 ProDOS
			blocks in size or it will not be loaded.

-s5d2 <image>		Same as above, but mounts the image on Slot 5, Drive 2.

-s6d1 <image>		Mounts an image on Slot 6, Drive 1 (the first 5.25"
			disk drive). The imge must be exactly 280 ProDOS blocks
			in size or it will not be loaded.

-s6d2 <image>		Same as above, but mounts the image on Slot 6, Drive 2.

-smptX <image>		Mounts an image as device number X (where X is between
			0 and 13) on the SmartPort in slot 7. Device #0 is the
			boot device and is mapped to Slot 7, Drive 1. The
			remaining devices are mapped to additional slot/drive
			combinations under ProDOS 8 v2.0 and higher (under
			GS/OS they will be directly accessible).

XGS supports several image types:

"2IMG" Universal Image Format ("file.2mg")
Raw ProDOS-order images ("file.po" or "file.raw")
Raw DOS 3.3-order 5.25" images ("file.do" or "file.dsk")
Pre-nibblized 5.25" disk images ("file.nib")
Macintosh DiskCopy 4.2 images ("file.dc")

Note that the only format which XGS can reliably detect is the 2IMG format;
all other formats are detected by making a guess based on the filename
extension. In other words, DiskCopy images MUST end in ".dc", nibblized images
MUST end in ".nib", etc. The extensions which XGS uses are the same as are
commonly used for images distributed via the Internet, so this should not be
a problem.

XGS comes with two utilities to make dealing with images easier. They are:

    imgconv <source file> <destination file>

	If you have any images in the old proprietary XGS format, this will
	convert them to the new universal 2IMG format. The proprietary format
	is no longer supported by XGS so you _will_ need to convert such
	images in order to use them.

    imgutil

	This is a universal utility for working with 2IMG images. It lets you
	create new images, lock/unlock images, and convert other images formats
	into 2IMG images.

---------------
TROUBLESHOOTING
---------------

If the XGS screen doesn't appear, then the emulator probably couldn't start,
and you should read the startup output to figure out why.  You probably have a
missing file. On Windows systems, the startup output is saved into the file
BOOTLOG.TXT in the same directory as XGS.EXE.

If the screen appears and then disappears, then the emulator probably crashed.
Mail me a bug report. If you're really ambitious you can even try to debug it
yourself.

If XGS crashes while running a certain piece of software, see if you can
reproduce the crash and tell me how you did it.  Even better, try to send
me a snippit of XGS debug output that shows the instruction that caused the
crash, along with a hundred or so lines preceding the crash.
