💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › GS.Emulators › APPLER.DOC.TXT captured on 2023-01-29 at 04:31:02.
-=-=-=-=-=-=-
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] [[-]<filename>[.APL]] [[-]<filename>[.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 <Alt+Ctrl+Del> (this will not restart your
system). To enter DOS Shell, press <Alt+Ctrl+Esc>.
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 <Alt+Fkey> 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 <F1> 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: <reg> = <value>
E: pc = fbdd
A: Change 65C02 registers value.
F: regs
A: Enter 65C02 registers editor (you can use <Alt+R> instead).
F: asm [<addr>]
E: asm @768
A: Enter Assembler mode. If the address is missing debugger assumes
address of the current (hilighted) instrunction (you can use <Alt+P>
instead).
F: ea [<addr>]
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 <Alt+M>
instead).
F: eb [<addr>]
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 <Alt+M>
instead).
F: d <addr>
E: d 300
A: Change disassembling address. Use arrow keys to browse.
F: da <addr>
E: da 300
A: Change Memory Dump A address.
F: db <addr>
E: db 300
A: Change Memory Dump B address.
F: [<addr1>,<addr2>]
E: [ 300,3FF ]
A: Specify memory block for COPY, COMPARE and FIND.
F: find [<byte>[,<byte>]]['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 <addr>[,f][,b]
E: copy 2000
A: Copy specified memory block to <addr>. If you want, use the <f> or
<b> parameter to specify the copying direction (Forward or
Backward).
F: compare <addr>
E: compare 4000
A: Compare specified memory block with block at address <addr>.
Responding message appears and if the blocks are not identical
Memory Dump A locates first different byte.
F: pdump [<filename>]
E: pdump esd.txt
A: Print memory dump on the printer (if no filename is given) or in the
specified file.
F: pasm [<filename>]
E: pasm esd.txt
A: Print disassembled program on the printer (if no filename is given)
or in the specified file.
F: break<num> [= <addr>]
E: break1 = @768
A: Set the breakpoint number <num> at address <addr>. If address is
missings this command toggles breakpoint activity.
F: go [<start>][,<stop>]
E: go 300,32B
A: Start the program at address <start> with optional breakpoint at
address <stop>.
F: . <identifier> = <value>
E: . Lives = 468A
A: Define specified label
F: list
A: Show defined labels list.
F: dl <identifier>
E: dl Lives
A: Delete (undefine) a label.
F: labels on|off
E: labels off
A: Set labels activity ON or OFF.
F: sl <filename>
E: sl monitor
A: Save defined labels in file <filename>. If extension is missing, the
debugger assumes '.LAB'.
F: ll <filename>
E: ll monitor
A: Load labels from file <filename>.
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 [<filename>]
E: play karateka
A: Play keystrokes in the buffer or read them from the specified file,
then play.
F: lm <filename>
E: lm mario
A: Load keystrokes (macro) in the buffer.
F: sm <filename>
E: sm mario
A: Save keystrokes (macro) in <filename>.
F: swap <timer_ticks>
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: ? <expression>[,b][,d]
E: ? 2+@58-%1001100/2*y,b
A: Evaluate and show the result of an expression. Use <b> or <d>
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