The "APPLER Emulator.ZIP' archive is currently available from the following url: ftp://apple.cabi.net//pub/apple_II/incoming/APPLER Emulator.ZIP ---------------------------------------------------------------------- ABOUT APPLER ~~~~~~~~~~~~ Appler is an Apple ][ emulator. If you don't know what Apple ][ is you better stop reading this file and erase Appler immediatly. But if you still remember 'Lode Runner', 'Karateka', 'Robot Odyssey' then enjoy Appler -- the best Apple ][ Emulator! ABOUT APPLER.DOC ~~~~~~~~~~~~~~~~ This file contains information about some Appler features that are not supported by a real Apple ][ computer. This is not a help file. Appler is made convenient to use and probably you will not need detailed help to use it. SYSTEM REQUIREMENTS ~~~~~~~~~~~~~~~~~~~ Appler needs at least 386 CPU, 1M RAM, 128K EGA, MS DOS 3.30. Even on slow 386 machines Appler can run faster than a real Apple ][ but it is recommended to use 486/33MHz because on fast computers appler supports realtime mode. While realtime is ON Appler synchronizes emulated CPU speed so it runs just like 6502 at 1 MHz. This is useful when you play games or musics -- Apple ][ has no system timers and Apple ][ programs synchronize time by counting 6502 CPU clocks. See 'REALTIME MODE' for details. EMULATED APPLE ][ HARDWARE ~~~~~~~~~~~~~~~~~~~~~~~~~~ Appler supports following Apple ][ hardware: - 65C02 CPU; - Apple ][ Memory: 48K RAM, 12K ROM, 16K Additional RAM; - Apple ][ I/O Memory: - $C000, $C010 - Keyboard; - $C020 - Sound Output (using DAC on LPT1); - $C030 - Internal Speaker; - $C050..$C057 - Video Mode Switches; - $C060, $C070 - Joystick Buttons & Timers; - $C080..$C08F - Additional RAM Switches; - $C0E0..$C0EF - Floppy Disk Controller (on slot #6) regs; - Apple ][ Video Modes: TEXT, GR, HGR (even mixed modes); - Apple ][ Keyboard; - Apple ][ Digital Joystick (using arrow keys in Num Lock mode); - Apple ][ Floppy Disk Controller and two Floppy Disk Drives. FLOPPY DISK EMULATION ~~~~~~~~~~~~~~~~~~~~~ Appler supports low-level floppy disk emulation and that's why it can run Apple ][ software that accesses floppy disks directly via Floppy Disk Controller registers. To store and emulate Apple ][ disks, Appler uses special MS-DOS files. Two file formats are supported: with '.DSK' and '.NBL' extension. A '.DSK' file contains DOS 3.3 sectors, 256 bytes each, 16 sectors per track. When an Apple ][ program reads disk track Appler encodes whole track info using 6&2 code. On the contrary, when an Apple ][ program tries to write some bytes Appler decodes information to obtain DOS 3.3 sectors and writes them in the '.DSK' file. In case Appler can't decode track info using 6&2 decoding method an error screen appears expecting user intervention. The '.DSK' file format is suitable for storing standard DOS 3.3 disks. '.NBL' files do not contain logical sectors but only tracks info and Appler do not interpret disk information. Use this file format to store non-DOS 3.3 disks, for example DOS 3.2 disks. If you didn't understand anything use '.DSK' files by default. If a program crashes accessing floppy disk drive, use DSK2NBL command-line utility to convert '.DSK' file to '.NBL' format. COMPATIBILITY ~~~~~~~~~~~~~ Appler is 99.99% compatible to a real Apple ][ computer. Of course, it is possible to write Apple ][ program that runs on real Apple ][ and doesn't run in Appler environment. Actually, if Appler can't run a program, that means the program is designed to crash Apple ][ resident debuggers. To fix such a programs, use Appler Integrated Debugger. APPLE ][ SOFTWARE ~~~~~~~~~~~~~~~~~ There are many Apple ][ games and programs in Appler distributive disks. Most of these games are piracy copies. Many of them are corrupted. If you own a better copy of a program or you have something new, please send Apple ][ disk to me and (if we find it of value) it will be included in the next Appler release. STARTUP & EXIT ~~~~~~~~~~~~~~ Appler recognizes command line syntax as follows: appler [/k] [[-][.APL]] [[-][.APL]] ... The '/k' switch is used to disable low-level keyboard access (see 'PROBLEMS RUNNING APPLER' for details). If you specify '.APL' filenames Appler loads these files in the memory and starts the last one when Apple ][ boots up. Minus sign is used to disable a file to be executed. Appler expects an '.APL' file header to be as follows: first two bytes: start address in the memory (low, hi); second two bytes: file length in bytes (low, hi). Appler scans the startup (not the current) directory for *.ROM files and reads these files in the Apple ][ memory (ROM files must have same header as the '.APL' files). Note that Appler will run even if no ROM file is found. Have you work on Apple ][ without ROM? When all '.ROM' files are loaded, Appler searches current directory for files APPLER.DSK and APPLER.NBL and 'inserts' them in the emulated floppy disk drives. If startup procedure described above is successful Apple ][ boots up. To exit Appler, press (this will not restart your system). To enter DOS Shell, press . UTILITIES ~~~~~~~~~ You can use several utility programs: 1. On-Line Apple ][ Debugger (see 'DEBUGGER' for details). 2. File Manager - for loading and saving MS DOS files. File Manager can save current Apple ][ status in a disk file and restore it later. 3. Disk Manager - for inserting and removing 'disks' in emulated disk drives (see 'FLOPPY DISK EMULATION' for details). 4. Keyboard Setup - for tuning Apple ][ keyboard. While Apple ][ program is running utilities are accessible by pressing a responding functional key. When you are already in utility program and want to go to another, use instead. At the bottom of each utility screen is shown current functional keys assignement. When a key label is grayed this means that responding function is disabled and you can't use it right now. DEBUGGER ~~~~~~~~ To enter Appler Integrated Debugger press the key while Apple ][ program is running. Debugger contains windows showing specific Apple ][ information. Most frequently used operations are accessible by pressing functional keys. In addition, you can use some commands to debug your program. Supported commands list follows: >> Legend: (F)ormat, (E)xample, (A)ction F: = E: pc = fbdd A: Change 65C02 registers value. F: regs A: Enter 65C02 registers editor (you can use instead). F: asm [] E: asm @768 A: Enter Assembler mode. If the address is missing debugger assumes address of the current (hilighted) instrunction (you can use instead). F: ea [] E: ea 300 A: Enter Memory Dump A editor. If the address is missing debugger assumes address of the current dump location (you can use instead). F: eb [] E: eb 300 A: Enter Memory Dump B editor. If the address is missing debugger assumes address of the current dump location (you can use instead). F: d E: d 300 A: Change disassembling address. Use arrow keys to browse. F: da E: da 300 A: Change Memory Dump A address. F: db E: db 300 A: Change Memory Dump B address. F: [,] E: [ 300,3FF ] A: Specify memory block for COPY, COMPARE and FIND. F: find [[,]]['str']["str"] E: find fa,"ESD",@65,'Alex' A: Find a string in the specified memory block. Enter strings and/or bytes to find. If parameters are missing (e.g. you've entered simply 'FIND') debugger repeats the last search. F: copy [,f][,b] E: copy 2000 A: Copy specified memory block to . If you want, use the or parameter to specify the copying direction (Forward or Backward). F: compare E: compare 4000 A: Compare specified memory block with block at address . Responding message appears and if the blocks are not identical Memory Dump A locates first different byte. F: pdump [] E: pdump esd.txt A: Print memory dump on the printer (if no filename is given) or in the specified file. F: pasm [] E: pasm esd.txt A: Print disassembled program on the printer (if no filename is given) or in the specified file. F: break [= ] E: break1 = @768 A: Set the breakpoint number at address . If address is missings this command toggles breakpoint activity. F: go [][,] E: go 300,32B A: Start the program at address with optional breakpoint at address . F: . = E: . Lives = 468A A: Define specified label F: list A: Show defined labels list. F: dl E: dl Lives A: Delete (undefine) a label. F: labels on|off E: labels off A: Set labels activity ON or OFF. F: sl E: sl monitor A: Save defined labels in file . If extension is missing, the debugger assumes '.LAB'. F: ll E: ll monitor A: Load labels from file . F: record [,f] A: Start recording keystrokes. In this mode Appler stores all keys you press in a buffer. Use ',f' parameter to ignore delays between the keystrokes. F: stop A: Stop recording keystrokes. F: play [] E: play karateka A: Play keystrokes in the buffer or read them from the specified file, then play. F: lm E: lm mario A: Load keystrokes (macro) in the buffer. F: sm E: sm mario A: Save keystrokes (macro) in . F: swap E: swap @18 A: Set delay for screen swapping when tracing statements. F: sound on|off E: sound off A: Turn Apple ][ sound on and off. F: reset A: Cold RESET Apple ][. F: ? [,b][,d] E: ? 2+@58-%1001100/2*y,b A: Evaluate and show the result of an expression. Use or switches to specify the result type - binary or decimal. Otherwise you will receive a hexadecimal result. You can enter simple mathematical expressions instead of adresses or numbers expected in commands syntax. Valid operations are: '+', '-', '*', '/', '|' (bitwise or), '&' (bitwise and), '^' (bitwise xor), '<' (bitwise shift left), '>' (bitwise shift right). All of the operations expects unsigned integer operands. There is no priority and brackets are not allowed -- expression evaluates from left to the right. Also you can enter hexadecimal (by default), decimal (using '@' prefix) and binary (using '%' prefix) numbers or addresses. PERFORMANCE ~~~~~~~~~~~ Appler is 100% 80386 assembler code (about 800K source, 22000 lines) and that's why it is so fast. Next diagram shows relative Appler performance in comparison with some other Apple ][ emulators. Emulators that were tested are: CRoss Debugger by Nickolay Nickolov, ][ in a PC by Randy Ubillos & David Dixon, Apple by Randy Spurlock, Apl by Todor Todorov, and Appler by Alexander Patalensky & Emil Dochevsky. Of course, Appler is tested with realtime mode OFF. ÚÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄ CRD ³ðððððððððððððððððððð 39% ][ in a PC ³ðððððððððððððððððððððððððððð 55% Apple ³ðððððððððððððððððððððððððððððð 58% Apl ³ððððððððððððððððððððððððððððððððððððððððððððð 87% Appler ³ððððððððððððððððððððððððððððððððððððððððððððððððððð 100% ÀÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄ 0% 25% 50% 75% 100% This test contains intensive video memory usage without page swapping. When a program often uses both pages some of the emulators slows down in a great degree and this proves Appler performance once more. The next diagram shows Appler performance on different computers in comparison with a real Apple ][: ÚÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄ Apple ][ ³ððððððð 100% 386 SX 20 ³ðððððððððððððð 140% 486 SX 20 ³ððððððððððððððððððððððð 197% 486 SX 40 ³ððððððððððððððððððððððððððððððððððððððððððððððððððððððð 394% ÀÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄ 50% 100% 150% 200% 250% 300% 350% 400% This test does not use the graphics modes, e.g. it shows the approximate computing proformance of the emulated 65C02 processor. For programs that often address video memory actual speed is 15-20% less. REALTIME MODE ~~~~~~~~~~~~~ On fast PCs Appler supports realtime mode. Use F12 key to turn realtime mode ON and OFF. When realtime mode is ON, Appler runs like an Apple ][ at 1 MHz. Actually this isn't really realtime mode because Appler don't synchronize speed at every 65C02 instruction (even 486/66MHz isn't fast enough to do that). Appler just counts 65C02 clocks and synchronizes CPU speed when a program accesses Apple ][ video memory or some I/O address ($C030 for example). If your computer isn't fast enough Appler will run faster than a real Apple ][ (even when realtime mode is ON). PROBLEMS RUNNING APPLER ~~~~~~~~~~~~~~~~~~~~~~~ Appler accesses some AT hardware at low machine level and that's why it can't run on some PCs. We have noticed these problems with some PCs: 1. Because of low-level access some AT-keyboards stops responding (but computer do not freeze). We dont know how to solve this problem so we added '/k' command line switch that disables low-level keyboard access. If you use this switch Appler will not manage keyboard lights and will not change repeat settings. 2. For running in realtime Appler needs to time moments as short as 10-15 microseconds. To do that it reads system timer via port 40h. This (we don't know why) do not work on some motherboards and on such computers realtime mode will not work properly. If you notice some other bugs or know how to solve these problems please contact us at the address given at the end of this file. CONTACT US AT ~~~~~~~~~~~~~ If you have some suggestions or notes please write us to the following address in English, Bulgarian or Russian language. Appler is at Public Domain but if you feel kind-hearted ;-) send us some money or something else you don't care about, please. APPLE ][ FOREVER! EMIL DOCHEVSKY 15 'Belitsa' str. Plovdiv Bulgaria tel.+359-32-451-824