@DATABASE AII.Guide @NODE Main AII.Guide @TOC Main @INDEX MyIndex @{BG HIGHLIGHT} @{B}Apple ][ Emulator 1.0 @{UB} @{BG BACKGROUND} @{I}Program and docs by Mike Fenton @{UI} @{I}Apple and Apple II are registered trademarks of Apple Computer, Inc.@{UI} @{B}Beginner's survival guide...@{UB} @{"Requirements" LINK Requires} @{"Installation" LINK Install} @{"Getting Started" LINK Start} @{B}Apple ][ Emulator User's Manual...@{UB} @{"Acknowledgements" LINK Ack} @{"How to use this emulator" LINK Usage} @{"Setting the options" LINK Options} @{"Switches" LINK Switches} @ENDNODE Main @NODE Requires "Requirements" @{BG HIGHLIGHT} @{B}Requirements@{UB} @{BG BACKGROUND} In order to use the Apple II emulator, you must have: @{FG HIGHLIGHT}@{BG TEXT} 1. Amiga 2.04 OS (Kickstart version 37) or newer. 2. At least one megabyte of memory (two megabytes preferred). 3. 68020 or newer CPU. 4. Apple II system and Basic ROM's (copied into a file). @{FG TEXT}@{BG BACKGROUND} Amiga OS has gone through a number of revisions. Amiga 1.0 and 1.1 OS are obsolete (A1000). Amiga 1.2 and 1.3 is still used on various A500 and A2000 systems. If you have 1.2 or 1.3, you should seriously consider upgrading. The Apple II ROM's may be in one file or two (one file for system, and one for the Basic). In any case, the system ROM is 2048 bytes long, and the Basic ROM is 10240 bytes long (or 12288 together). Make sure the length is correct before attempting to use the emulator. @ENDNODE Requires @NODE Install "Installation" @{BG HIGHLIGHT} @{B}Installation@{UB} @{BG BACKGROUND} @{FG HIGHLIGHT}@{BG TEXT} 1. Drag the drawer titled "AII1.0" to a disk or partition of your choosing. 2. If you can, copy the ROM file(s) into the drawer as well. This will make it more convenient when you will need to select the ROM file(s). @{FG TEXT}@{BG BACKGROUND} That's it! The first time you run the emulator, it will ask you where the ROM file(s) may be found. Afterward, you need not worry about the ROM file(s). @ENDNODE Install @NODE Ack "Acknowledgements" @{BG HIGHLIGHT} @{B}Acknowledgements@{UB} @{BG BACKGROUND} Many thanks to Jim Drew for the Apple II stuff without which none of this would have been possible. A large portion of this program was derived from the Atari emulator. The CPU code was designed by Joe Fenton. This saved me about two months of work. Much credit is also due to Winston D. Gayler for his reference manual "The Apple II Circuit Description" which proved to be valuable for the kind of hardware questions we needed answers to. @ENDNODE Ack @NODE Start "Getting Started" @{BG HIGHLIGHT} @{B}Getting Started@{UB} @{BG BACKGROUND} @{I}Running the emulator for the first time...@{UI} § @{B}Step A@{UB} Once you have the ROM's on file, the rest is easy. Simply double-click on the "AII" icon. An information requester will appear. Click on "OK" to continue. § @{B}Step B@{UB} Next, a file requester will appear. This allows you to select or type the name of the ROM file(s) the emulation is requesting. Within the requester is a scrolling list of files and drawers. Drag the scroll bar up and down to see more of the list (if there is more) and click on the (first) file name you want to select. Make sure length of the file(s) are correct. (2,048 for the system ROM, 10,240 for the Basic ROM, and 12,288 combined.) If you wish to select another name, hold down the shift key and select another name. Then release the shift key. Both names will remain selected until you click on "OK." If you only need to select one file, you may double-click on the name. This is the shortcut way of selecting the file and clicking on "OK." Click on "Cancel" if you wish to quit at this point. § @{B}Step C@{UB} If the ROM file(s) load properly, the emulation will start up automatically. The Basic prompt will appear (or the monitor, if you did not select a Basic ROM image). Once the prompt appears, you can load files, boot disk images, or simply use the emulation as you wish. @ENDNODE Start @NODE Usage "How to use this emulator" @{BG HIGHLIGHT} @{B}How to use this emulator@{UB} @{BG BACKGROUND} @{I}A lot of controls rest at your fingertips. The following explains how they all work.@{UI} @{"Overview" LINK Overview} @{"Application Keys" LINK AppKeys} @{"Keyboard" LINK Keyboard} @{"Paddles" LINK Paddles} @{"Files" LINK Files} @{"Disks" LINK Disks} @{"Debugger" LINK Debugger} @ENDNODE Usage @NODE Overview "Overview" @{BG HIGHLIGHT} @{B}Overview@{UB} @{BG BACKGROUND} Using this emulator is easier than using VCR+ to program your VCR. Never- theless, you might find yourself stuck in Emulatorland before too long without any directions. So, before you get the gun and shoot your monitor, save yourself some bucks and read over the next few passages. @ENDNODE Overview @NODE AppKeys "Application Keys" @{BG HIGHLIGHT} @{B}Application Keys@{UB} @{BG BACKGROUND} The only thing really missing from the emulation is all the other switches and knobs you'd find on a real Apple II. To make up for this, you can use keyboard equivalents of those switches, knobs, and such. @{I}To use the function, press the @{B}right Amiga key@{UB} plus the other key which represents the function. Here is a list of the functions:@{UI} Key combo Name Function ---------------------------------------------------------------------------- Amiga + L Load Load program or disk D1, reboot Amiga + 1 Load Load program or disk D1 (don't reboot if disk) Amiga + 2 Load Load program or disk D2 (don't reboot if disk) Amiga + R Reboot Simulate power off and on, clear memory, etc. Amiga + Q Quit Go away. Shut down emulator. Amiga + B Break Stop the emulator and begin debugging. Amiga + M Mono Monochrome display on/off (high res. only) In addition to those, function keys also allow you to switch options. F1 Set speed to normal (100%) F2 Slow down the emulation F3 Speed up the emulation F4 Unlimited speed F5 Reset (key) F6 Joystick paddles F7 Mouse paddles F8 Keypad paddles F9 not used F10 No paddles When you press a function key, an icon will appear briefly on the right side of the screen, illustrating your option choices. @ENDNODE AppKeys @NODE Keyboard "Keyboard" @{BG HIGHLIGHT} @{B}Keyboard@{UB} @{BG BACKGROUND} The use and complexity of the keyboard depends mostly on the model of emulation you select. § Apple II/II+ No lower case characters, no CAPS LOCK, and no Apple keys appear on these keyboards. In this model, you can only enter upper case keys through the keyboard. The Apple only had the two arrow keys (left and right), but this emulation does return values for up and down (^K, ^J--VT, LF). § Apple IIe/IIc/IIgs These models all use the CAPS LOCK, and the Alt keys function as Apple keys. The arrow keys work the same as II/II+. § Special keys The Shift-Ctrl combinations with M, N, and P produce GS, RS, and NUL--29, 30, and 0--respectively. F5 is used to produce "Reset." For clean memory and such, you will need to "reboot" (Amiga-R). @ENDNODE Keyboard @NODE Paddles "Paddles" @{BG HIGHLIGHT} @{B}Paddles@{UB} @{BG BACKGROUND} The Apple paddles are simulated by your choice of device. See @{"Joystick" LINK Joystick} for more information about this option. Some software also looks for a device referred to as a "Joyport" or "Atari joystick." This device is emulated by using a digital joystick which you connect to game port 1. @ENDNODE Paddles @NODE Files "Files" @{BG HIGHLIGHT} @{B}Files@{UB} @{BG BACKGROUND} Files can be utilized in various ways. You can use DOS, the loader, or the emulation of another device to retrieve or store files. When you start up the emulation, you can load a file right away using the emulated cassette device. The file should actually be stored on an AmigaDOS disk. You can also type in a program and save it in this fashion. One of the advantages to loading programs in this fashion is that Basic will have more memory to work with (than with DOS). To use the emulated cassette device, simply type LOAD or SAVE at the Basic prompt. Note that this will not work with an alternate language (like a loaded Integer Basic) on the language card. If you load (Amiga-L) a DOS disk, the DOS should start up and display whatever message it automatically starts up with. When you receive the Basic prompt you can then load and save files through DOS to that disk (or other disks). The @{"Write Protect" LINK WriteProt} options allow you to prevent saving to the disk. Under DOS you can have any type of file. Types of files include Basic files, binary files, and text files. Basic files LOAD and SAVE in the usual fashion. Binary files require the use of BLOAD and BSAVE to function. Text files should be loaded by an application program (which you RUN or BRUN). Other files are usually used like text files (through the application). If you load (Amiga-L) a program file, the file should run and display its start-up messages and such. Once this type of file is loaded, you can use Amiga-1 and Amiga-2 to provide disks as necessary. Using this method, though, removes DOS from the system. So, if the program expects to use a disk, it should have its own routines for accessing the drive (like a low- level disk copier). Program files normally run without any other support files. If they do require the ability to access other files, then they should only be used within a DOS disk/disk file. @ENDNODE Files @NODE Disks "Disks" @{BG HIGHLIGHT} @{B}Disks@{UB} @{BG BACKGROUND} As previously mentioned (see @{"Files" LINK Files}), DOS can be used to load files. Once DOS has been loaded, however, you are not restrained to one disk. The Amiga-1 and Amiga-2 functions will allow you to select other disks. Disks do not necessarily contain DOS. A disk can have a custom loader and operate in its own format. These types of disks are not always compatible with DOS disks. In addition to this, a disk does not have to use Basic or allow you access to the Basic prompt. Some disks are even loaded with protection schemes. In any case, selecting a disk/disk file will provide the appropriate response from the emulator, and using it is entirely up to you and whatever programs exist within the disk. If the name you select is not a disk drive and the file you specify does not exist, you can create a disk file from one of the various formats for use with the emulation. Note that if you create a disk file for use with DOS, the disk file will need to be formatted (INIT) before you can use it. @ENDNODE Disks @NODE Debugger "Debugger" @{BG HIGHLIGHT} @{B}Debugger@{UB} @{BG BACKGROUND} The debugger currently allows you to trace and set break points, but I recommend that you not use it. I haven't put it through any but the most preliminary tests, and the interface has not been fully completed. @ENDNODE Debugger @NODE Options "Setting the options" @{BG HIGHLIGHT} @{B}Setting the options@{UB} @{BG BACKGROUND} @{I}Options can be set in a variety of ways. They control how the emulator functions, and how you can communicate with the emulation.@{UI} @{"Overview" LINK OptOverview} @{"Speed" LINK Speed} @{"Pause" LINK Pause} @{"Priority" LINK Priority} @{"Joystick" LINK Joystick} @{"Write Prot" LINK WriteProt} @{"ROM File(s)" LINK OptROM} @{"Model" LINK Model} @{"Menu Items" LINK OptMenu} @ENDNODE Options @NODE OptOverview "Overview" @{BG HIGHLIGHT} @{B}Overview@{UB} @{BG BACKGROUND} In order to get the most of the Apple II emulator, you must select options which suit the way you prefer to use it. For example, if you prefer to use the keyboard for paddle control, you must select the "Keypad" as your Joystick option. You may also wish to adjust the speed, change the priority, or change the Apple II system you are using. To set the options, run the emulator and wait for the Apple II prompt to come up. Then switch to the Workbench (press left Amiga-N), and double- click on the icon called "A][ Icon". A window will appear with a group of gadgets which represent the options you wish to change. Now, you may change the desired option(s) by selecting or dragging the gadget which represents what you want to change. For example, to change the speed, drag the knob within the slider titled "Speed." A number to the immediate right of the slider will indicate the exact speed you have chosen. Some options will act immediately upon your selections, and others will require that you "Reboot" the emulation to enact the changes. See below for details. @ENDNODE OptOverview @NODE Speed "Speed" @{BG HIGHLIGHT} @{B}Speed@{UB} @{BG BACKGROUND} With most applications, you should probably leave the Speed at "0." This runs the program at the same speed as an actual Apple II (or 100%). The speed of the emulator changes immediately when you use the slider gadget. The speed influences the way audio and video performs. When you increase the speed, the pitch of a sound may increase. When you decrease speed, the objects on the screen may be drawn and redrawn slower. The speed also influences the speed of other programs the Amiga is running. However, when you increase the speed of the Apple II emulator, other programs tend to become slower. If you move the slider to "-100," the emulator will run at its slowest speed (25%). If you move the slider to "100," the emulator will run at unlimited speed (using as much CPU time as possible). Note: If you use higher speeds, then set your Back Priority to "-5" or lower. This will prevent other tasks from being slowed down too much by the Apple II emulator. @ENDNODE Speed @NODE Pause "Pause" @{BG HIGHLIGHT} @{B}Pause@{UB} @{BG BACKGROUND} This option causes the emulator to stop whenever the AII screen is inactive. If you do not select Pause, then the emulator will continue to run when it is in the background (not active). Note that since the emulator is in the background when you select this option, it will take effect immediately. This option is on by default. This option overrides the speed option because speed does not get a chance to take effect when this option is selected. The speed option does take effect when you select the AII screen, though. Technically speaking, pause does not stop the emulation altogether. The emulation does run, but at about 1,000 times slower than 100%. If you want the emulation to completely halt, run the debugger (Amiga-B). @ENDNODE Pause @NODE Priority "Priority" @{BG HIGHLIGHT} @{B}Priority@{UB} @{BG BACKGROUND} This option allows you to control how fast the emulation runs when other programs are also running. If you set the priority high, the emulation will run faster, but it may also cause other programs to become slower. This is particularly true if you run at high speeds. In order to keep the priority organized, two different options appear. One refers to the priority of the emulation when it is receiving inputs (front) and the other refers to the priority when it is not (back). As a general rule, you should always set your back priority low, especially if you run the emulation at high speed. Since the options window causes the emulation to be inactive, the back priority is used immediately. The front priority does not take effect until you select the emulation screen (making the emulation active). @ENDNODE Priority @NODE Joystick "Joystick" @{BG HIGHLIGHT} @{B}Joystick@{UB} @{BG BACKGROUND} Currently, you can select among None, Mouse, Joystick, and Keypad. None is simply nothing--no paddles/joystick. The mouse option lets you use the normal Amiga mouse to position the paddles. The joystick button (game port 1) or the middle button (3-button mouse) centers the positions of the paddles. The left and right buttons translate to button 0 and 1. The joystick option lets you use a digital joystick in game port 1 to emulate extreme paddle positions. The joystick button translates to button 0 and the right mouse button translates to button 1. 3-button sticks translate as follows: B = button 0, C = button 1. (6-button mode not supported.) The keypad option lets you use the keypad for extreme paddle positions. Most keyboards allow you to use more than one key at a time for diagonal positions (my A1200 won't, though). 8, 5, 4, and 6, translate to up, down, left, and right, respectively. (You can also use 2 for down.) 7, 9, 1, and 3 translate to their appropriate diagonal positions. The paddles return to center when you release the keys. The "Enter" and "+" on the numeric keypad translate to button 0 and button 1. @ENDNODE Joystick @NODE WriteProt "Write Prot" @{BG HIGHLIGHT} @{B}Write Prot@{UB} @{BG BACKGROUND} Normal disk files (binary, raw gcr) and actual disks operate by default in read-write mode. Selecting the write protect option switches into read-only mode. This will prevent any data from being written to the disk/file. Selecting the option will act immediately, although (if you have write data pending) you will have to select whether to save any current data. Compressed disk files by default are read-only. This option does not have any effect on compressed disk files. Program files are also read-only because they do not (per se) use the disk drive emulation. @ENDNODE WriteProt @NODE OptROM "ROM File(s)" @{BG HIGHLIGHT} @{B}ROM File(s)@{UB} @{BG BACKGROUND} ROM Files are part of the requirements to run this emulation. They should contain the image of the system and work on the model computer that you are attempting to emulate. You can also select a Basic image as a separate file or together in one file. This option does not take effect until you "reboot" (Amiga-R) the emulator. If you already have working ROMs and the emulation is already running, the file(s) you select work cumulatively on the memory--that is, they add to whatever other ROMs you already have selected. So, once you load the Basic ROM once, you need not load it again if you want a different Autoboot ROM (or vice versa). Once you "reboot," if the file(s) do not fit the description of a ROM file, you will get a warning, and the emulator will revert back to the old image of the ROMs. @ENDNODE OptROM @NODE Model "Model" @{BG HIGHLIGHT} @{B}Model@{UB} @{BG BACKGROUND} Currently, only the II+ option is supported. @ENDNODE Model @NODE OptMenu "Menu Items" @{BG HIGHLIGHT} @{B}Menu Items@{UB} @{BG BACKGROUND} In addition to the gadgets in the window, you can use a menu item to perform the following functions: @{I}Under "Project" heading:@{UI} Normal Speed Iconify Reboot Quit @{I}Under "Settings" heading:@{UI} Reset to defaults Load config... Save config... To select among the various functions available in the menu, hold down the menu button and move the pointer to one of the headings. Then release the button when you have selected the item you want under that heading. "Quit", "Load config...", and "Save config..." can be used by holding down the right Amiga key and then pressing either "Q", "L", or "S". These are also indicated in the menu by the Amiga key symbol and the letter which indicates its keyboard shortcut. The ellipsis (...) after certain items (like "Load config...") indicates that a requester will appear when you select the item. "Reset to defaults" only affects these options: Speed, Front and Back Priority, and Joystick. The other options remain the same. "Iconify" has the same effect as the window's close gadget--it closes the window and replaces the Workbench application icon. "Reboot" performs the same function as Amiga-R when the custom screen is selected. It clears the memory and restarts the emulator. "Quit" stops the emulator and exits completely. @ENDNODE OptMenu @NODE Switches "Switches" @{BG HIGHLIGHT} @{B}Switches@{UB} @{BG BACKGROUND} @{I}This program attempts to create a file called @{UI}"AII.config"@{I} and put your configuration options into it. Although you should always use the options window in the program to change your options, you can change the options yourself in any text editor by careful use of the following switches.@{UI} @{I}Note: Switches are case-sensitive.@{UI} @{B}/SP:@{UB} Speed Speed is any integer constant between -100 and 100. -100 stands for 25% normal speed. 0 stands for 100% normal speed. 100 stands for unlimited speed. See @{"Speed" LINK Speed} in options for more details. @{B}/PF:@{UB} Front Priority This is the relative priority of the task AII uses to emulate the Apple. It can be any integer constant between -9 and 0. The task uses this priority only when the AII custom screen is selected. @{B}/PB:@{UB} Back Priority This is the relative priority of the task AII uses to emulate the Apple. It can be any integer constant between -9 and 0. The task uses this priority when the AII custom screen is not selected. Note: Try to keep this value as low as you can if you use other programs at the same time. @{B}/JS:@{UB} Joystick Character values: N, M, J, K Use one of the above characters to select among None, Mouse, Joystick, and Keypad as your Joystick option. (Emulates Apple II analog joystick/ paddles.) @{B}/ML:@{UB} Model Character values: P, E, C, G Use one of the above characters to select among II+, IIe, IIc, and IIgs. (Note: Apple II and II+ are compatible.) @{B}/R1:@{UB} ROM #1 This option is followed by the path and filename of the first ROM file you have selected. @{B}/R2:@{UB} ROM #2 This option is followed by the path and filename of the second ROM file you have selected. @{B}/D1:@{UB} Disk #1 Character values: W, R Use one of the above characters to indicate read-Write or Read-only mode. @{B}/D2:@{UB} Disk #2 Character values: W, R Use one of the above characters to indicate read-Write or Read-only mode. @ENDNODE Switches