
                           APPLE ][ FOREVER
                           ~~~~~~~~~~~~~~~~
                     APPLER - AN APPLE ][ EMULATOR
                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

              by Emil Dotchevski and Alexander Patalenski


                           TABLE OF CONTENTS
                     -----------------------------
                       1. OVERVIEW
                       2. DISTRIBUTION
                       3. SYSTEM REQUIREMENTS
                       4. EMULATED HARDWARE
                       5. FLOPPY DISK EMULATION
                       6. COMPATIBILITY
                       7. STARTUP & EXIT
                       8. UTILITIES
                       9. DEBUGGER
                      10. PERFORMANCE
                      11. REALTIME MODE
                      12. PROBLEMS RUNNING APPLER
                      13. CONTACT US AT
                     -----------------------------



1. OVERVIEW
~~~~~~~~~~~
Those of you who don't know what Apple ][ is, I'll try to explain. It is
maybe the first worldwide popular personal computer. Just imagine this:
48K RAM, 1MHz CPU, big main board with many separate chips on it... And
compare it to today's powerful computers! If you have never seen any
program running on Apple ][, you are probably thinking that it should be
slow like hell and ugly looking. But people who still remember Lode
Runner, Karateka, Robot Odyssey, ... know that making quality games and
programs doesn't require hundreds of MHz and tons of RAM.


2. DISTRIBUTION
~~~~~~~~~~~~~~~
Appler is free software. You can distribute it as long as you do not
charge anything for it, and you have not changed the original ZIP
archive. It should contain these files, with exact size and date/time
stamp:

Filename        Size     Date    Time   Comment
------------  -------  --------  -----  --------------------------------
README   1ST   18,335  01-06-98  2:00a  The file you're reading now
APPLER   COM   48,646  01-06-98  2:00a  The emulator itself
APPLE    ROM   12,292  01-06-98  2:00a  Apple ][ ROM file
FLOPPY   ROM      260  01-06-98  2:00a  Floppy disk controller ROM
APPLER   DSK  143,360  01-06-98  2:00a  Startup Apple ][ disk
MONITOR  LAB    8,196  01-06-98  2:00a  Monitor labels for the debugger

Source code is also available for free downloading at the URL shown in
the bottom of this file.


3. SYSTEM REQUIREMENTS
~~~~~~~~~~~~~~~~~~~~~~
Appler needs at least 386 CPU, 1M RAM, 128K EGA, MS DOS 3.30. Emulator
will run faster than an Apple ][ even on slow 386 machine but it is
recommended to use 486/33MHz because on fast computers appler supports
realtime mode. This is useful when you play games or musics -- Apple ][
has no system timers and Apple ][ programs count time by calculating CPU
clocks. See 'APPLER REALTIME MODE' for details.

Appler is DOS software it can run in a DOS window under Windows.


4. EMULATED HARDWARE
~~~~~~~~~~~~~~~~~~~~
Appler fully emulates the following Apple ][ hardware:

       - 65C02 CPU (valid instructions only)
       - 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 registers (on slot #6)
       - Apple ][ video modes (even mixed GR/TEXT modes)
       - Apple ][ keyboard
       - Apple ][ digital joystick (using arrow keys in Num Lock mode)
       - Apple ][ Floppy Disk Controller and two Floppy Disk Drives


5. FLOPPY DISK EMULATION
~~~~~~~~~~~~~~~~~~~~~~~~
Appler uses special files to store and emulate Apple ][ disks. 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 the
whole track info using 6&2 coding. On the contrary, when an Apple ][
program tries to write some bytes, Appler decodes information to obtain
DOS 3.3 sectors, then writes them in the '.DSK' file. In this case when
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 this information. Use this file format for
storing non-DOS 3.3 disks, for example DOS 3.2 disks.


6. COMPATIBILITY
~~~~~~~~~~~~~~~~
Appler is 99.99% compatible with real Apple ][ computer. Of course, it
is possible to write Apple ][ program that runs on real Apple ][ and
don't run in Appler environment. Actually if Appler can't run a program,
that means program is designed to crash Apple ][ resident debuggers. In
that case you can use Appler integrated Debugger to fix it.


7. STARTUP & EXIT
~~~~~~~~~~~~~~~~~
When Appler starts, it searches the startup (not current) directory
for *.ROM files and reads these files in the memory. A '.ROM' file must
have the following structure: first two bytes contain the start address
in the memory and the second two bytes - the length in bytes. Such a
structure is used by Apple DOS 3.3 to store binary files on disks.
After that Appler searches current directory for files APPLER.DSK and
APPLER.NBL and if found 'inserts' them in the emulated floppy disk
drives.

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 ('.APL' files has the same
structure as '.ROM' files, see above) and starts the last one. Use
the minus sign to disable file to be executed.

To exit Appler, press <Alt+X>. To enter DOS Shell, press <Alt+D>.


8. UTILITIES
~~~~~~~~~~~~
You can use several utility programs inside the Appler:

        - Appler On-Line Debugger - for tracing and debugging Apple ][
          programs in memory (see 'APPLER DEBUGGER' for details).

        - Appler File Manager - for loading and saving MS DOS files.
          File Manager can save current Apple ][ status in a disk file
          and restore it later.

        - Appler Disk Manager - for inserting and removing 'disks' in
          emulated Disk Drives - see 'FLOPPY DISK EMULATION'.

        - Appler Keyboard Setup - for changing keys assignement and AT
          keyboard settings.

        - Appler Help Screen - guess what is used for.

All the utility programs (and the emulator itself) are controlled by
simple but powerfull task manager. They are completely independent from
each other. You can switch between utilities at any time, similarly to
switching tasks in Windows.

When Apple ][ program is running utilities are accessible by pressing
responding functional key. When you already are in an utility program
and want to go to another use <Alt+functional key> 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.


9. DEBUGGER
~~~~~~~~~~~
You can enter Appler Integrated Debugger at any time while Apple ][
program is running by pressing the <F1> key. 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. You are not required to type the
entire command, you need to give enough symbols for debugger to be able
to recognize your command from others. Here is a list of all commands
available:

REG
Format:         <reg> = <value>
Example:        pc = fbdd
Action:         Change 65C02 registers value.

REGS
Format:         regs
Example:        regs
Action:         Enter 65C02 registers editor (you can use
                <Alt+R> instead).

ASM
Format:         asm [<addr>]
Example:        asm @768
Action:         Enter Assembler mode. If the address is missing debugger
                assumes address of the current (hilighted) instrunction
                (you can use <Alt+P> instead).

EA
Format:         ea [<addr>]
Example:        ea 300
Action:         Enter Memory Dump A editor. If the address is missing
                debugger assumes address of the current dump location
                (you can use <Alt+M> instead).

EB
Format:         eb [<addr>]
Example:        eb 300
Action:         Enter Memory Dump B editor. If the address is missing
                debugger assumes address of the current dump location
                (you can use <Alt+M> instead).

D
Format:         d <addr>
Example:        d 300
Action:         Change disassembling address. Use arrow keys to browse
                in disassembled program.

DA
Format:         da <addr>
Example:        da 300
Action:         Change Memory Dump A address.

DB
Format:         db <addr>
Example:        db 300
Action:         Change Memory Dump B address.

[]
Format:         [<addr1>,<addr2>]
Example:        [ 300,3FF ]
Action:         Specify memory block for COPY, COMPARE and FIND.

FIND
Format:         find [<byte>[,<byte>]]['str']["str"]
Example:        find fa,"ESD",@65,'Alex'
Action:         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.

COPY
Format:         copy <addr>[,f][,b]
Example:        copy 2000
Action:         Copy specified memory block to <addr>. If you want, use
                the <f> or <b> parameter to specify the copying
                direction (Forward or Backward).

COMPARE
Format:         compare <addr>
Example:        compare 4000
Action:         Compare specified memory block to the block at address
                <addr>. Responding message appears and if the blocks are
                not identical Memory Dump A locates first different
                byte.

PDUMP
Format:         pdump [<filename>]
Example:        pdump esd.txt
Action:         Print memory dump on the printer (if no filename is
                given) or in the specified file.

PASM
Format:         pasm [<filename>]
Example:        pasm esd.txt
Action:         Print disassembled program on the printer (if no
                filename is given) or in the specified file.

BREAK
Format:         break<num> [= <addr>]
Example:        break1 = @768
Action:         Set the breakpoint number <num> at address <addr>. If
                address is missings this command toggles breakpoint
                activity.

GO
Format:         go [<start>][,<stop>]
Example:        go 300,32B
Action:         Start the program at address <start> with optional
                breakpoint at address <stop>.

.
Format:         . <identifier> = <value>
Example:        . Lives = 468A
Action:         define specified label

LIST
Format:         list
Example:        list
Action:         Show defined labels list.

DL
Format:         dl <identifier>
Example:        dl Lives
Action:         Delete (undefine) a label.

LABELS
Format:         labels on|off
Example:        labels off
Action:         Set labels activity ON or OFF.

SL
Format:         sl <filename>
Example:        sl monitor
Action:         Save defined labels in file <filename>. If extension is
                missing, the debugger assumes '.LAB'.

LL
Format:         ll <filename>
Example:        ll monitor
Action:         Load labels from file <filename>.

RECORD
Format:         record [,f]
Example:        record
Action:         Start recording keystrokes. In this mode Appler stores
                all keys you press in a buffer. Use ',f' parameter to
                ignore delays between the keystrokes.

STOP
Format:         stop
Example:        stop
Action:         Stop recording keystrokes.

PLAY
Format:         play [<filename>]
Example:        play karateka
Action:         Play keystrokes in the buffer or read them from the
                specified file, then play.

LM
Format:         lm <filename>
Example:        lm mario
Action:         Load keystrokes (macro) in the buffer.

SM
Format:         sm <filename>
Example:        sm mario
Action:         Save keystrokes (macro) in <filename>.

SWAP
Format:         swap <timer_ticks>
Example:        swap @18
Action:         Set delay for screen swapping when tracing statements.

SOUND
Format:         sound on|off
Example:        sound off
Action:         Turn Apple ][ sound on and off.

RESET
Format:         reset
Example:        reset
Action:         Cold RESET Apple ][.

?
Format:         ? <expression>[,b][,d]
Example:        ? 2+@58-%1001100/2*y,b
Action:         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.

When you enter addresses or numbers you can use simple mathematical
expressions instead. Available operations are: '+', '-', '*', '/',
'|' (bitwise or), '&' (bitwise and), '^' (bitwise xor), '<' (shift
left), '>' (shift right). 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) or binary
(using '%' prefix) numbers.


10. PERFORMANCE
~~~~~~~~~~~~~~~
Appler is 100% 80386 assembler code (about 800K source, 22000 lines)
and that's why it is so fast. The following diagram shows the relative
Appler performance in comparison to some other Apple ][ emulators. The
following emulartors are tested:

Appler          - by Alexander Patalenski & Emil Dotchevski
Apl             - by Todor Todorov
Apple           - by Randy Spurlock
][ in a PC      - by Randy Ubillos & David Dixon
CRoss Debugger  - by Nickolay Nickolov

------------------------------------------------------------------------
Appler:         *************************************************** 100%
Apl:            ********************************************* 87%
Apple:          ****************************** 58%
][ in a PC:     **************************** 55%
CRoss Debugger: ******************** 39%
------------------------------------------------------------------------

This test contains intensive video memory usage without page swapping.
When a program often use 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 to a real Apple ][ (when realtime mode is OFF):

------------------------------------------------------------------------
Apple ][:   ******* 100%
386 SX 20:  ************** 140%
486 SX 20:  *********************** 197%
486 SX 40:  ******************************************************* 400%
------------------------------------------------------------------------

The 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 the video memory the real speed is 18-20% less.


11. 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) but Appler counts 65C02 clocks and synchronizes CPU
speed when program accesses an Apple ][ I/O address ($C030 for example).
If your computer isn't fast enough Appler will run faster than an Apple
(even when realtime mode is ON).


12. PROBLEMS RUNNING APPLER
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Appler accesses some AT hardware at low machine level and that's why
it can't run on some PCs. I have noticed two problems with some
computers:

        - because of low-level access keyboard stops responding (but
          computer do not freeze). I dont know how to solve this
          problem so I 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.

        - 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 (I don't know why) do not work on some
          motherboards and on such computers realtime mode will not
          work. This means, the emulated Apple ][ will run faster than
          a real Apple ][, even when realtime mode is on.

If you notice some other bugs or know how to solve these problems please
contact me at the address given at the end of this file.


13. CONTACT US AT
~~~~~~~~~~~~~~~~~
If you have some suggestions or notes please write us to the following
addresses in English, Bulgarian or Russian language. Actually Alex does
not interest Appler any more and it is better to write to me (if you
want to).

EMIL DOTCHEVSKI                                     ALEXANDER PATALENSKI
1540 7th St., Suite 300                           43 'Chernishevski' st.
Santa Monica, CA 90401                                           Plovdiv
USA                                                             Bulgaria

zajo@geocities.com                               alexp@unforgettable.com

   ------------------------------------------------------------------
    URL: http://www.geocities.com/SiliconValley/Bay/3577/appler.html
   ------------------------------------------------------------------
