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 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 Same as above, but mounts the image on Slot 5, Drive 2. -s6d1 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 Same as above, but mounts the image on Slot 6, Drive 2. -smptX 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 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.