Apple //e Emulator -- Randy Frank randy@tessa.iaf.uiowa.edu Release 2.0 1 March 1991 ----First the necessities----- apple2e Copyright (C) 1990, Randy Frank Randy Frank ("Author") grants to the party hereby receiving "apple2e" from an authorized provider ("Recipient") a non-exclusive, royalty-free license to copy, display, distribute, and produce derivative works of "apple2e", provided that the above copyright notice appears in all copies made of "apple2e" and both the copyright notice and this license appear in supporting documentation, and that the name of Author not be used in advertising or publicity pertaining to "apple2e". The Author requests to be made aware of any derivative works. "apple2e" is provided "as is" without express or implied warranty. Author does not and cannot warrant the performance of "apple2e" or the results that may be obtained by its use or its fitness for any specific use by Recipient or any third party. In no event shall Author become liable to Recipient or any other party, for any loss or damages, consequential or otherwise, including but not limited to time, money, or goodwill, arising from use or possession, authorized or not, of "apple2e" by Recipient or any other party. ----Now on with the show----- What the package is: This software package is an Apple //e emulator. Emulation includes the 65C02 and an extended 80 column video card. Dos 3.3 and ProDOS are supported. The emulator uses the curses package for display. Building the application: The source code for the program is provided in compressed tar format. One need only uncompress the archive and extract all the files from the tar file and type make to get started. Two tar archives are needed. The first contains just the images of the disks needed to emulate DOS (and ProDOS) functions. The second contains the program itself. The program comes in two flavors: GL and curses. The GL version runs on Silicon Graphics machines (and possibly IBM RS6000) and the other runs on most Unix boxes with the curses library. The disk images are in the file emu.disks.tar.Z which you must have for both versions of the emulator. The curses code is in the file ap2e.tar.Z and the GL code is in the file ap2egl.tar.Z. You should NOT try to build both programs in the same directory as many source filename common between the versions. To build it completely: % uncompress emu.disks.tar.Z % tar xvof emu.disks.tar % rm emu.disks.tar % uncompress ap2e.tar.Z (or ap2egl.tar.Z for graphics versions) % tar xvof ap2e.tar (or ap2egl.tar for graphics versions) % rm ap2e.tar (or ap2egl.tar for graphics versions) % make On most systems make should run ok. If not check the Makefile for flags and syntax not permitted on your machine. It may be necessary to specify a library path and/or include path on some systems. (People who have an error with the beep() function please see the end of this document). You must provide two files for the emulator to run. First you must provide a copy of the CDROM from an enhanced //e. (Note: ROMs from //c, unenhanced //e, and ][+ machines will NOT work) Instructions on preparing the file are included at the end of this document. You must also provide a copy of the file PRODOS from any bootable PRODOS disk. This must be a binary copy off a booting PRODOS disk transferred to the UNIX machine and named 'PRODOS'. At this point the following files should be in the same directory on the UNIX box: filename in tar archive? description apple2e no executable file generated by make CDROM no //e ROM file (you provide) PRODOS no PRODOS file (you provide) Makefile yes makefile apple.h yes emulator source main.c yes emulator source 6502.c yes emulator source debug.c yes emulator source mega2.c yes emulator source extras.c yes emulator source s6d1 yes DOS 3.3 slot 6 drive 1 disk arch s6d2 yes DOS 3.3 slot 6 drive 2 disk arch PRODOS.IMAGE.D1 yes PRODOS slot 7 drive 1 disk arch PRODOS.IMAGE.D2 yes PRODOS slot 7 drive 2 disk arch (other .o files) no produced by your compiler If you built the graphics version you would have the following files also: graphics.c yes emulator source alt.font yes alternate char font pri.font yes primary char font You are now ready to run the emulator. The syntax is as follows: apple2e [-t] [-s] Trace (-t) mode causes the state of the processor to be printed to the standard error at the end of each 65C02 instruction. Silent (-s) mode defeats the emulation of the speaker beep. If the emulator fails to start running check to see if any of the listed files are missing or named incorrectly. The emulator will exit gracefully but will not tell you what is missing should it be unable to open one of these files. The emulator will begin an apple2e boot but will NOT see any disk drives on powerup because of a patch placed in the ROMs to prevent complete autobooting. Note: to fix a booting problem the following patch is applied to the CDROM after loading into memory. FAB5:C1 This masks the emulated drives from the slot searching code on cold boot. The code checks for a C8 at this location before attempting to patch. Once in the emulator, to start DOS 3.3 you type: pr#6 to start PRODOS you type pr#7. (Remember: DOS 3.3 commands are entered in UPPER CASE!!!) While the emulator is running ctrl-A may be used to access various features: ctrl-A ctrl-A : Inputs a normal crtl-A ctrl-A d : Enters the debugger ctrl-A 0 : Toggles the state of BUTTON0 ctrl-A 1 : Toggles the state of BUTTON1 Note:Until you toggle it back the button will remain pressed once you set it. So in Appleworks to get help and back you: ctrl-A 0 ? ctrl-A 0 ESC Without the second 'ctrl-A 0' Appleworks thinks you are typing oa-ESC and won't allow you to exit. (Graphics users see the end of this document for alternate ctrl-A schemes) In the debugger: q : Quit to UNIX l : Load a UNIX file into memory @ $2000 t : Set a trace journal file d : Boot DOS 3.3 p : Boot ProDOS r : Execute a power up reset (dirty power up checksum and reset) c : Continue execution s (or ret) : Single step execution DOS 3.3 emulation: Under DOS 3.3 there are two permanent drives at slot 6 drives 1 and 2. If the files 's5d1' and/or 's5d2' are in the directory they can be accessed under DOS 3.3 as slot 5 drives 1 and 2. DOS 3.3 is booted by loading BOOT2 into memory (for the curious this is done by loading sectors in the memory range $b600-$bfff starting from track 0 sector 0 and then jumping into BOOT2. See Beneath Apple DOS for further discussion.) from the UNIX file and executing it. So some non-standard DOS 3.3s may also be run (read some non-standard games which still use the $bd00 RWTS). The emulator intercepts RWTS execution at $bd00. Note: the UNIX files contain all the data on a DOS 3.3 5.25 disk. However, the files are not in straight t0s0,t0s1,t0s2... order. Instead the DOS 3.3 files are in PRODOS interleave format. So the first 256 bytes are t0s0 but the second are t0se. This is exactly the format you get by reading a DOS 3.3 disk with the PRODOS block scheme. See the included program at the end of this file on how to copy your 5.25" DOS 3.3 disks into the emulator. ProDOS emulation: Under ProDOS there are two or four drives. Slot 6 drive 1 is a 280 block boot volume. Slot 6 drive 2 is a 1024 block quasi-hard drive. If the files 's5d1' and/or 's5d2' exist they will be mounted as 280 block disks under slot 5. And as usual the aux memory will be set up as /RAM. PRODOS is booted by loading the data in the UNIX file 'PRODOS' into memory at $2000 and jumping to it with some zero page variables set. PRODOS UNIX files are just a block by block binary dump of the data on the 5.25 disk. The included program will also convert PRODOS disks into UNIX files. //e emulation: The system will be a 128k //e with an 80col card in slot3 and some combination of drives in slots 5, 6 and 7. Apple keys are emulated as well as most of the softswitches (see mega2.c) Note: the VBL bit is emulated as a random number and the paddles are NOT currently emulated in the curses version. PR#3 will startup 80 columns also. (Note: PRs emulations are actually checks of the PC going to Cx000 so the monitor ctrl-p and Cx000g will work to boot an operating system.) The Apple //e arrow keys must be typed as their control key equivalents (I didn't like the idea of timing out ESC sequences). Thus for a backarrow you would type ctrl-h, for a forward arrow type ctrl-u, for a down arrow type ctrl- j and for an up arrow type ctrl-k. As mentioned earlier, since there is no 'universal' method for looking at 'meta' keys you must toggle the apple keys on and off using a ctrl-d 1/0 sequence. (Note:in the graphics version this is no longer necessary as the arrow keys are mapped correctly and mouse buttons map to the apple keys.) -------------------------------------------------------------------------------- To obtain the needed CDROM and PRODOS files: 1) Boot your //e into PRODOS 2) Get the CDROM file with the following commands: ] call -151 * c007:0 * 2100