IIe 3.0 Apple //e emulator for Macintoshes and PowerMacintoshes Copyright © 1995-1996, Vincent and Victor Tan. Thank you for taking the trouble to try this program out. We hope you like it. Note: this file is formatted and is best read with SimpleText and not TeachText. Note: this file is not read-only so that you can easily copy the text if you want to. For example, you can copy the email addresses and URLs. Please don't modify this file or distribute modified versions. Note: you should scroll up and down a pageful at a time so that the pictures will appear properly. If the pictures don't appear, you can make them appear by scrolling up a page and then back down a page. This software is copyrighted material and therefore you are not allowed to modify this software or its documentation in any way, shape or form, nor can you sell it for your own profit. You may only charge a reasonable fee for the cost of distributing it. See the Distribution section below for information about how and on what IIe may be distributed. Contents The documentation for IIe comes in 4 files. Their contents are: 1. Read me first What is it? - description, features, requirements, compatibilty, and performance issues Description Features Hardware and software requirements Compatibility Performance issues Installation and setup Simple installation/setup Tips Frequently Asked Questions (FAQ) 2. Instructions The Apple //e window The display area The //e screen The icon buttons Function keys Graphics modes Disk inserting/removing Using real disks Using disk images How to insert and remove disks and disk images Loading and saving information - memory images Emulator instructions Default settings Starting up the emulator The Reset key The Keyboard Paddles and buttons Debugger instructions 3. Configuring IIe General pane 65c02 pane Memory pane Video pane Sound pane Keyboard pane Joystick/Mouse pane Printing pane 5 1/4" Disks pane Other Disks pane Slots pane 4. Other stuff Cost/fee and registration Version history Future version features Distribution Contacting the author Other software by Vincent Disclaimer 1. Read me first It's best to begin with a word of warning: IIe is a complex program and has some powerful features. You can easily lose Apple //e data by using this program "recklessly" so please do these two things: (1) make a backup of all your important data and disk images, and (2) read these documents thoroughly. By reading these documents, you'll understand how IIe works and how to use it safely and usefully. You can disregard this warning to your own consequence. It will be pointless to complain to me that you lost your work. My reply will be: why didn't you read the instructions and make a backup? Of course I want IIe to work as reliably and as safely as a real //e would. Nevertheless, there are probably some minor bugs in this program, so it's best to be safe and always have a backup. OK, that out the way, let's define some of the terms used below before getting started. The term "IIe" refers to this Mac program. In contrast, the term "//e" refers to the virtual Apple //e that you use in the "Apple //e" window, ie the virtual computer and not the Mac program and its menus, windows, dialogs, etc. Don't worry. It'll make more sense as you read along. If you insist on reading the very minimum, you should at least peruse the Frequently Asked Questions which are at the bottom of this document. What is it? - description, features, requirements, compatibilty, and performance issues Description: IIe is an Apple //e emulator for Macintoshes and PowerMacintoshes. It lets you run virtually any program for the Apple II, Apple II Plus, Apple //e, and Apple //c computers. It does not run Apple IIgs software. It has been tested with a limited number of programs and works well with them. Most of the Apple II OSes boot up, including DOS 3.3, ProDOS 2.0.3, and Apple Pascal 1.2. Most games will work without problems. See below for more details about this version's abilities and limitations. How does it work? IIe takes machine instructions written originally for the 65c02 microprocessor and emulates them in software. In other words, it uses the CPU in your Mac to do the work that was originally intended for a 65c02 microprocessor. The emulator keeps track of the 65c02 instructions, registers and memory usage, as well as converting the memory used for graphics or text into Macintosh graphics. As well, Apple II peripherals such as the Disk II (5 1/4" disk drive), and the UniDisk for 3 1/2" floppy disks are also emulated. The goals of this version are more functionality and compatibility. New to this version are these features: o- sharp graphics - no more hard to read hires text! o- faster PowerPC emulation of 65c02 instructions (the emulator is now written in PowerPC assembly, using pipelining, branch prediction, and several optimisations that are only possible with assembly code) o- ability to ignore illegal opcodes o- ability to emulate a 6502 instead of a 65c02 o- ability to paste text into an Apple II program o- support for more screen sizes from as small as 640 * 400 (PowerBook) to larger than 14" screens o- added an option for a joystick that doesn't auto-centre when you use the keypad o- drag and drop support for easier loading of disk images o- no longer requires you to quit IIe when you change slots (except that memory cards may not get the requested memory size until you allocate more memory to IIe by changing its size in the Finder) o- more peripherals such as printer card support - you can now print from your Apple II program to your Mac printer (text only) o- support for the original Disk II boot ROM (necessary for some disks to boot) o- more drives: the Mac-ProDOS card now supports two drives and the UniDisk card can support up to 4 drives in ProDOS when installed in slot 5 o- can now eject real 3 1/2" disks from the Mac when you remove them from the //e's drive o- more compatible I/O space functioning for some programs that require random numbers (such as Castle Wolfenstein) o- can disable the 80 column card for Pascal programs which run better in 40 column mode (such as Wizardry) o- support for a user-selectable beep sound o- user-adjustable joystick limits (necessary for some games) o- you can now run the emulator at full speed - that is, as fast as your Mac's CPU will run it o- and last but definitely not least, numerous bug fixes Features: o- comes as a "fat binary" - that is, it contains both 680x0 and PowerPC code for optimal performance on any Mac. This version performs quite well on 68040 Macs and PowerMacs and performs "decently" on 68030 Macs. 68040 Macs should get 1Mhz //e performance. PowerMacs should be able to get 2MHz //e performance or better. o- able to display an Apple //e computer in a Mac window. This version supports all the //e graphics modes: text, lores graphics, double lores graphics, hires graphics, and double hires graphics. It even flashes text. The normal and alternate ("MouseText") character sets are supported. The hires and double hires graphics can be displayed in monochrome or colour. Text and hires graphics displayed in monochrome mode can be displayed in a variety of monochrome colours such as white, green or amber (read that sentence twice if you didn't get it the first time) o- able to take keystrokes on your Mac keyboard and pass them to the emulated //e. Supports the "open" (command) and "closed" (option) apple keys on the //e keyboard (as well as the third paddle button by the shift key - known as the "shift key modification"). o- the //e can be reset from your Mac keyboard (by pressing control-delete) o- able to read 5 1/4" disk and 3 1/2" disk images - this version supports all common image formats including 5 1/4" nibble images o- able to read directly from a 3 1/2" disk in the internal drive on your Mac and use it as a 3 1/2" disk in the emulator o- able to use a ProDOS partition of your hard disk as a ProDOS hard disk in the emulator. You can set up such a partition with "Apple HD Setup" or "FWB Hard Disk Toolkit". o- able to directly read from or write to files in a Mac directory from any ProDOS program. This is a very handy feature and allows direct transfer of data without the need for PC Exchange o- supports fast reads and writes on Dos 3.3 and ProDOS 5 1/4" disks o- able to switch any disk in any drive at any time o- emulates a joystick by using the keypad on your Mac keyboard or the mouse o- emulates a RamWorks III RAM disk o- emulates peripherals such as a ThunderClock clock card, the AppleMouse mouse card, the Apple II Memory Expansion memory card, and a serial card with ImageWriter printer attached o- very configurable via an easy-to-use preferences and setup dialog o- supports Apple //e speaker sounds o- has a useful debugger to allow you to set breakpoints, inspect registers, etc. if you want to debug Apple II programs Hardware and software requirements: IIe requires: o- a colour-capable Macintosh (ie, not the Mac Plus, SE, Portable, or PowerBook 100). A fast 68030 Mac is the minimal hardware you should run IIe on. All PowerBooks except the PowerBook 100 can run IIe. o- a monitor of at least 640 * 400 pixel size (sorry to the 12" colour and Colour Classic owners) o- System 7 or later o- the Thread Manager (which is built into System 7.5 or later). o- Sound Manger 3.0 or later. Recommended: o- a fast 68040 Mac or a PowerMac o- support for 256 colours o- System 7.5.1 or later o- Sound Manger 3.1 if you have a PowerPC Mac o- Thread Manger 2.1 if you have a PowerPC Mac o- Macintosh Drag and Drop if you are not running System 7.5 or later o- a ProDOS partition on your Mac hard disk (created with Apple's HD Setup program or a third party utility such as FWB's Hard Disk Toolkit) or a ProDOS hard disk image (using one of the files supplied in this package). Compatibility: This software has been tested on systems 7.1 to 7.5.3. Currently there are no known Mac software conflicts. If you should find a problem, let me know. With regard to Apple II software, there are some programs (especially games) that require special configuration to work properly with IIe. These are the known ones: o- Castle Wolfenstein image on www.asimov.net - requires the Disk II be in "compatible" mode not "fast" mode (or you can copy a normal DOS 3.3 onto it) o- Karateka - requires the original ("dumb") Disk II ROM to boot up o- Legacy of the Ancients - requires "ignore illegal instructions" to boot up o- Championship LodeRunner - requires the joystick x and y maxima be set to about 270 for play with the joystick o- Wizardry I (and probably the others as well) - requires the boot disk to be write protected (ie, locked) otherwise it will be destroyed by the program when you first boot it. If you don't like the 80 column text, click the 80 column card icon in the slots pane to switch it to 40 columns. If you know of any other conflicts or problems, let me know and I'll investigate it and update the list as necessary. Performance issues: This version does not allow background programs much background time to run so you may find print jobs tend to slow down and modem downloads don't work well. Similarly, programs that take up background time will tend to slow down the emulator (because your Mac's CPU spends less time running the emulator). Even having a lot of other programs open will slow down the emulator - merely closing those other 6 apps will bring a noticable speedup in the program! :-) For best performance: o- close all unecessary programs o- reduce the number of extensions you install at startup o- run IIe in Black & White mode (ie, 1-bit mode) - the fastest graphics blitters are the 1-bit blitters because they have the smallest amount of memory to blit o- use the small window size o- use direct drawing Installation and setup Simple installation/setup To install and set up this program: 1) decompress the archive that this program comes in. You've probably already done this to be able to read this Read Me. 2) get a copy of the Apple //e ROMs*. If you're on the internet, you can get it from: http://www.asimov.net/pub/apple_II/emulators/applepc/IIerom.zip If you're on an online service, use its ftp ability to obtain the above file. Use a utility such as "DropStuff with StuffIt Expander" or "ZipIt" to decompress the file. *For legal reasons, the ROMs cannot be distributed with this emulator because they are the copyright of Apple Computer, Inc. "So what?" you might ask. Well, I personally don't enjoy getting letters from lawyers, and since I still own an Apple //e (and it still works just fine thanks), I have all the ROMs I need (well, almost all: if only I'd bought that mouse card, memory card, serial card, etc. etc. when I could have...). If you don't have internet access but do have a real Enhanced //e*, you can follow these instructions to create your copy of the ROMs. You will need some way of transferring the file to your Mac such as a 3 1/2" floppy disk or some kind of serial connection. Ask your nearby user group for info about how to do this. Note that in the following lines, the Ô0' character is a zero, and that anything between angled brackets Ô<' or Ô>' is one character - eg, means hold down the control key and then press the C key (which is an invisible character). Also, note that the ROMs in the Apple IIe card for Mac LCs are modified and will not work with IIe. a) start up your //e and boot up ProDOS. Then run BASIC.SYSTEM to enter Applesoft Basic (it will display a Ô]' prompt) b) type "call-151" to enter the //e's monitor program (it will then display the Ô*' prompt) c) type "2000" d) type "C007:0" e) type "5100" f) type "C006:0" g) type "" to re-enter Basic h) type "BSAVE APPLE2E.ROM,A$1000,L$5000" i) transfer this file to your Mac as a binary file * Enhanced //e's have a 65c02 processor and when you run programs like AppleWorks, they will display folders and characters such as the open and closed apples on the text screen. Unenhanced //e's have a 6502A processor and don't have the special characters so AppleWorks Ôlooks funny'. 3) make sure the ROM file is called "APPLE2E.ROM" and that it is in the same folder as IIe. If you want to see the icon for ROMs, change the type/creator of the file to ÔROMs'/ÔAIIe'. 4) set IIe's memory size. IIe's memory size is preset at 1700K (it will appear as about 2065K on PowerPC Macs with virtual memory off), which is optimal for 68K Macs using a 256K table which helps the emulator run faster. You can change this setting depending on what kind of Mac you have and whether you want to use the table: o- if you have a PowerPC Mac, you can set IIe's memory size to 1200K if you have virtual memory on (or if you have RamDoubler on), or to 1565K if you have virtual memory off. If you set IIe to use more memory in the form of RAM disks, etc. then of course you'll have to use larger values (depending on the size of your extra memory requirements). o- if you have a 680x0 Mac and set IIe to not use the 256K table, then you can reduce IIe's memory size to 1500K. DO NOT set IIe to any value below 1500K or it may crash or behave erratically. You are now set to use IIe. Read the information below and in the following documents to learn how to properly use it. Tips o- changing the creator of a disk image to ÔAIIe' allows you to double click the file to have IIe use it o- clicking the Mono/colour icon button changes the display from monochrome to colour and vice versa o- control-clicking the Mono/colour icon button changes the colour of the monochrome text/graphics o- option-clicking the Mono/colour icon button changes the screen's bit depth from 8 -> 1 -> 4 -> 8, etc. o- control-esc or F15 will start/stop the emulator o- be sure to have backups of your Apple II disks because IIe can destroy the disks as easily as a real //e can! When you delete a file on your disk (or disk image), it's gone! You may be able to recover it with a disk utility program but it's much better (and a whole lot saner) to have a backup and restore it from that Frequently Asked Questions (FAQ) Q: The program complains about not being able to find a file called "APPLE2E.ROM". What gives? A: IIe does not contains the Apple //e ROMs because they are copyrighted material. You will need to either dump your own ROMs or get a copy of the ROMs that have already been dumped. See the section "Installation and Setup" above for more info about obtaining them. Note that legally you cannot use the ROM file specified above unless you own an Apple //e. Q: When I double click IIe, it starts up and then stops and I'm left back in the Finder. What's going on? A: There was a problem during IIe's startup. The most likely causes are: Thread Manager not present or installed, out of memory, and corrupted preferences. Install Thread Manager if you are running a system prior to System 7.5. Try giving IIe more memory. Try deleting the preferences. Q: The program starts up but then nothing happens. What's wrong? A: When you start up IIe without any disks loaded into the drives, the //e is halted until a disk is inserted and the On/Off or Go/Stop icon is clicked. Q: IIe starts up but then crashes/freezes/hangs/bombs/dies/stops working. Help! A: Try these tips in the order shown: 1) restart with all extensions off by holding down the shift key until your Mac says "Welcome to Macintosh. Extensions Off.". If this works, then one of your extensions is conflicting with IIe. If you find out which one it is, let me know (send email) and I'll try to fix it. 2) give IIe more memory 3) turn off (uncheck) the "Direct drawing" option in the video pane of the preferences. Some Mac video cards don't like this option when it's on (checked). 4) install a new copy of IIe and delete the "IIe Preferences" file in your Preferences Folder (which is in your System Folder) 5) contact me with a detailed description of the problem and how to reproduce it. One request: you do not need to give me a 10 page list of your extensions; it usually is not helpful. If I need such a list, I'll ask you for it. Q: It runs too slowly! Help! A: try these suggestions in the order shown: 1) use the small window mode if you can 2) change to Black and White mode if your Mac's video system supports it 3) change the video frequency to 20Hz instead of 30Hz or 60Hz 4) turn on direct drawing 5) increase the CPU speed in the 65c02 pane of the preferences 6) quit all other programs 7) turn off all unecessary extensions, including File Sharing, AppleTalk, Virtual Memory, etc., etc. 8) get a faster machine (sorry but there's a limit to how fast any Mac can operate!) Q: Talking of speed, why isn't IIe as fast as StopTheMadness on my 680x0 Mac? A: IIe emulates an Apple //e and therefore requires a much more complicated memory scheme than StopTheMadness, which emulates an Apple II+. The price of being able to properly use 128K of Apple //e memory (or more) is that the emulator has to do more work to correctly access the memory. Result: slower performance than STM but more flexible and more powerful memory use. Q: Talking of emulators, why isn't IIe an Apple IIgs emulator? Are there plans for this? A: IIe was designed to emulate an Apple //e. Emulating an Apple IIgs is a lot more work and a much harder task. I have no plans for doing this and it is very unlikely I ever will. Instead, I recommend obtaining the FAQ of the internet newsgroup comp.emulators.apple2. There is mention in that document of the IIgs emulators currently in development (and yes, it's written for Macs). Q: Some of the sounds that IIe makes don't sound right. What gives? A: Emulating the Apple //e speaker is one of the hardest things to do right. IIe tries its best but may not always succeed. There isn't much that can be done about it. Most programs will sound OK and only a few will have problems. Choppy sounds may be due to too frequent video drawing or your Mac's CPU being too slow. Slower Macs may not produce continuous sound - sorry, but they just don't have enough CPU speed to do it. Try these suggestions: 1) try using 30Hz or 20Hz instead of 60Hz (see the video pane in the preferences) 2) use the smaller screen 3) use direct drawing (see the video pane in the preferences) 4) turn off as many extensions as you can 5) turn off any networking software you can 6) quit as many programs as you can (and not just close their windows) 7) get a faster Mac (well I had to mention this option, didn't I?) Q: What do the numbers at the top of the window mean? What do the red circles and squares mean? A: These are the drive lights and slot/drive indicators. When an Apple II program accesses the disk, the lights go on to tell you what is happening. You can click them to change the type of displayed lights (but clicking has no other effect on the program). Q: The //e program I'm running suddenly stops, then a window labelled "6502 Debugger" comes up and it's full of gibberish! What on earth is going on? A: Your //e program has come across a "break" instruction or an illegal instruction (or it has reached a breakpoint that was previously set). The most common reasons for this are: a buggy program or a //e conflict (eg, the program you're using doesn't like the Clock card in slot 2). This situation is analogous to your Mac displaying the dreaded "bomb" dialog: the CPU is stuck at a place it can't continue onwards from. It's fairly unlikely you'll be able to continue the //e program and save any data but you may want to try: click the "Skip" button to skip over the illegal instruction. If it works, save your file and reboot the //e to start it up in a "clean" state. To exclude a //e conflict, remove all unneeded "cards" from their "slots". Of course, if you ended up in the debugger because of a breakpoint (it'll say so in the bottom left corner of the window) then just clear the breakpoints and click the "Run" button. On a final note, you can check the "ignore illegal instructions" checkbox in the 65c02 pane of the Preferences to make IIe ignore illegal instructions. Q: Why can't I get my program to work? A: Some programs are "fussy" about your //e setup, and require certain hardware features. See the "Compatibility" section above for known incompatibilities and their work-around. Q: What does the Interrupt icon do? A: This halts the //e's CPU and puts you into the 6502 debugger. From here, you can set breakpoints and follow the code as it is emulated. To exit the debugger, click the Run button (but remember to clear the breakpoints). Most people won't need to ever use this button. You will need to know the 65c02 instruction set to make sense of the 6502 Debugger window. Q: Why is it that when I select a menu command with the mouse it works fine, but when I use the keyboard shortcut for that command then instead of doing anything, I get the key in the //e window? A: when the //e emulator is running, all keystrokes are directed to the emulator window and menu commands are not interpreted. This is so that AppleWorks, Multiscribe and other programs which use "command-" combinations will function correctly. To access the menu commands from the keyboard, first halt the emulator by clicking the "Go/Stop" icon or using the "Go/Stop //e" menu command in the File menu, then select your desired command, and then run the emulator by using the "Go/Stop" icon again. Notes: (i) if the "Go/Stop" icon or command is set up to function as an On/Off switch, then instead of halting the emulator, the icon will switch off the emulator and you will lose all of the contents of the //e's memory without any warning that this will occur. Be careful with this option! (ii) if you have an extended keyboard, you can use the function keys to do many of the same functions that the menu commands do, and you don't need to halt the emulator to use them. Therefore, it is much easier to use the function keys if you can. See the file "2. Instructions" for details on what the function keys do. Q: How much memory should I set IIe to use? A: See the Installation and setup section above for a detailed answer. The "catch all" answer is 1700K, but it will need to be more if you set up IIe to use a RAM disk, etc. Q: I changed the memory settings in the preferences but nothing happens. What's going on? A: Changes to the memory settings won't occur until IIe is restarted. Here's how to change IIe's memory settings: 1) change the settings in the Memory pane in the IIe Preferences window and click the OK button 2) select Quit IIe from the File menu 3) increase or decrease IIe's memory requirements in the Finder's Get Info window 4) close the Get Info window 5) double click the IIe icon. IIe will then start up with the new memory settings. Q: I have some Apple II disks. How do I get the programs to work with IIe? A: If your disks are 3 1/2" disks, just run IIe and then insert the disk into the Mac's floppy drive. IIe will ask you which drive you want to insert it into. Select a drive and then the disk is accessible just like on a real //e. Note that this assumes that you have already installed the UniDisk/Hard Disk card into a slot (see the Slots Pane section in the "Configuring IIe" file for info on how to do this if you haven't). If your disks are 5 1/4" disks, then you'll need a real //e to transfer them to floppy disk or to a Mac via a serial connection. Please obtain the "comp.emulators.apple2" FAQ available on the internet for a detailed description of how to do this. And if you're curious, the answer is "no, you can't use a IBM-compatible PC to read Apple II 5 1/4" disks". Q: How do I write Apple II programs? A: You should be able to find a book on this topic from a library or bookshop. If not, ask your local user group or programming association. On the internet, post a (polite) message to the newsgroup news:comp.sys.apple2.programmer Q: Why doesn't the //e program I wrote work the way I want it to? A: It's beyond the scope of these documents to tell you how to program or what is wrong with it. See the answer to the last question for some resources that you can try. Q: Where on the internet can I get the latest version of IIe from? A: Use a World Wide Web browser to get it from: or The latest version is always at the first URL. If you don't have internet access, then try these suggestions: o- ask someone who has access o- use a "cybercafe" o- try a public library (many have WWW access now) o- try a BBS o- ask your local user group Q: Where on the internet can I find some Apple II software or information? A: Try these places: (hard to get in) (preferred method) is a mirror of grind (hard to get in) (much easier to get into) (can be hard to get in) (???) (???) (limited to 15 users, can also be accessed via gopher!) I also recommend obtaining the document in this directory: it contains useful information especially about transferring data from an Apple II to a Mac/PC. Q: I downloaded a file but it doesn't load or run. What's going on? A: If you download your files from the internet or you get them in compressed format (you can tell because the files end in ".gz" or ".zip") then follow these instructions to decompress them properly. I recommend using Internet Config 1.2, DropStuff with Expander Enhancer 4.0 or later, and StuffIt Expander 4.0 or later, since the combination of these programs can decompress the files correctly when you set up Internet Config for suffix mapping. To do this, run Internet Config and click "File Mappings". Then add the file extensions ".dsk", ".do", and ".po". For each of them, click the "binary data" (and not "Macintosh") button. Then for ".dsk" and ".do" files, map them as File Type ÔDSK5' and File Creator ÔAIIe'. For ".po" files, map them as File Type ÔDISK' and File Creator ÔAIIe'. Save your changes. StuffIt Expander will now be able to correctly decompress the files. Next, configure your transfer program (be it an ftp client or a WWW client) so that files ending in .gz, .zip, .dsk, .do, and .po are downloaded as binary data and not text. Next, if the file ends in .gz or .zip, decompress the file by dragging and dropping it on StuffIt Expander. They will be decompressed and come out as ready-to-use IIe disk images which you can double click to insert them into IIe. See the section "Disk inserting/removing" in the files "2. Instructions" for more detailed instructions on the file types that IIe supports. Q: Why should I register IIe? After all, I have it now and can use it straight away. A: IIe is released as shareware. You're free to try it out but if you decide to keep on using it, you're obliged to register. After all, it's a pretty good deal for you: you get the software and can use it without having to pay up front. Also, it isn't crippled or disabled - so what you see is what you get! On the other hand, unregistered versions remind you to register and have a time limit of one hour. :-) I ask you to be honest about your use of IIe and pay the registration fee when you feel that you wish to keep the program. Think about it from my point of view: this program was hard work. It wouldn't exist unless someone put in the time and effort to write it and make it work well and as bug-free as possible. It's only fair that if a payment is requested then you pay for it if you think it's worth it. Also, paying the fee is very encouraging for me and allows further development to be done. On a final note, payment is a quick and simple thing to do. Please see the last document for details about how to do it. I'll conclude with this: "thank you for supporting shareware".