                         XL-it! Atari 8bit Emulator

                                Version 0.20

                               User's manual

                       (c) 1996/97 by Markus Gietzen

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Contents:

   * Introduction

   * Copyright

   * Installation

   * Starting the emulator

   * User-interface

   * Keyboard

   * Monitor

   * The Author

   * F.A.Q.

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Introduction

     XL-it! emulates Atari 800, 800XL and 130XE homecomputer.
     It is developed with Watcom C/C++ and needs at least a 386 CPU. The
     emulator is optimized for the use with Pentium processors. Parts of
     the emulation are written in 386 protected-mode assembly (the whole
     6502-emulation and parts of the Antic-emulation). The main goal of the
     emulator is the ability to run most of the existing software for Atari
     8-bit home-computers. Therefore I try to increase the compatibility
     first and then I try to increase the speed and the comfort of XL-it!.

     Please note that an emulator can never be like the original. It's just
     an attempt to make it possible to use your favourite Atari software on
     your PC.

---------------------------------------------------------------------------

Copyright

   * XL-it! is (c) 1996/97 by Markus Gietzen.
   * Pokey-Emulator is (c) 1996/97 by Ron Fries

   * XL-it! is free as long as it is not used in any commercial matter.
     This also includes all attempts to include XL-it! in CD-collections
     that are sold ! You need my written permission first !
   * Donations are very welcomed!
   * I still have the right to forbid the usage of the emulator at any
     time.

              I am not responsible for any damage caused by XL-it!

---------------------------------------------------------------------------

Installation

     Before you can start with the emulator you must get the ROMs of an
     Atari. These ROMs can be found in an archive called "xf25.zip" which
     is another emulator.
     You can find that archive on the XL-it! homepage (see chapter "The
     Author").
     Please place these ROMS in the same directory as the emulator is
     placed.
        o XL-ROM: atarixl.rom (16384 Bytes)
        o BASIC-ROM: ataribas.rom (8192 Bytes)
        o OLD-ROM: atariosb.rom (10240 Bytes)

     Sorry for this inconvenience but I am not sure who owns the rights for
     these ROMs and therefore I do not include them.

   * Sound

     All you have to do is to set the "BLASTER" environement in your
     "autoexec.bat". Please refer to the documentation of your soundcard
     for more details.

     Attention: If you have an older Soundblaster or compatible card that
     doesn't support autoreload-DMA, then you have to use "-oldsb". Of
     course it's also possible to use the user-interface for that.

---------------------------------------------------------------------------

Starting the emulator

     The executable file is called "atari.exe". It is a 32-bit
     DOS-executable that runs under plain DOS, Windows 95, Windows NT and
     OS/2. For maximal performance (above all if you use sound) I suggest
     that you use plain DOS! This means that you get a very slow emulation
     if you use Windows 95 and sound-support.

     By starting "atari.exe" without any option you will be prompted by the
     user-interface. This user-interface is intended to be used instead of
     the command-line options. This means that using any command-line
     option disables the user-interface at start-up (it still works within
     the emulator [F8]). Therefore you can still use your favourite
     emulator-launch utility.

     Anyway, I don't think that you need to stick around with the
     command-line options anymore. The user-interface is much more
     convienient and it saves your setup on exit.

     Commandline Options:

           -nobasic   Disables BASIC
           -nosound   Disables SOUND
           -nopatch   Disables all OS-patches
           -joyswap   Emulate joystick in port 2
           -cart fnameLoad 8k or 16k cartridge-image
           -oldmode   Atari 800 emulation
           -modex     320x240 resolution
           -german    German keyboard-layout
           -lock50    50Hz lock (PAL)
           -lock60    60Hz lock (NTSC)
           -frame x   Displays every x.frame
           -oldsb     Needed for older Soundcards
           -hd dir    Use H: to access directory
           -artifact  Enable color-artifacting

---------------------------------------------------------------------------

User-interface options

   * Menu: System
        o Emulator
          Starts the emulation. You can leave the emulation by pressing F8.
        o About
          Copyright
        o DOS-Shell
          Enter the DOS-Shell. With "exit" you can exit this mode.
        o Exit
          Exits XL-it!
   * Menu: Devices
        o Diskdrives
          You can insert disk-images into the virtual DD-diskdrives of
          XL-it!
          .XFD and .ATR images (single, enhanced and double density) are
          supported. The drives are called D1: through D8: on the Atari.
        o Harddrives
          This powerfull feature of XL-it! allows you to access directories
          of your PC.
          This means that you can access the selected directories with H1:
          through H8:
        o Insert ROM
          XL-it! supports 8k and 16k ROM cartridges. If you have an image
          of such a cartridge you can load it here (this only works on
          start-up; not while the emulator is running).
        o Eject ROM
          Removes the ROM that you inserted.
   * Menu: Setup
        o Environement
          This menu is only available at start-up. It defines the general
          behaviour of XL-it!. Options are:
             + Sound
               Selects whether sound should be emulated or not.
             + Old soundblaster
               Check this mark if you have an older soundcard (see
               Installation).
             + XE-Emulation
               If this mark is checked you have an 130XE with 128kB RAM.
               Of course this only works as long as you don't invoke Atari
               800 emulation.
             + 800er Emulation
               Enables the emulation of an Atari800. This disables the
               emulation of the MMU and loads another OS-ROM. This is
               needed for older Atari software.
             + Basic-cart.
               Enables/Disables the BASIC-cartridge. As a matter of fact
               you have to disable BASIC for nearly every game. This is a
               common problem for Atari-beginners !
             + Patch OS
               XL-it! patches the OS to support high-speed disk I/O, access
               to your PC-directories and other things. This may lead to
               problems and therefore you can disable that here. Anyway:
               you'll lose many feature if you disable OS-patching.
             + Swap-Joysticks
               This option is only available if you don't have a
               PC-Joystick connected. It means that the joystick is no
               longer emulated in Port 1 but in Port 2 because there are a
               few games that need that (mostly C64 ports). If you have a
               PC-joystick connected it's always in Port 1 and Port 2 is
               emulated (keyboard).
             + Deutsche Tastatur
               This enables the German keyboard-layout.
        o Video&Speed
             + Framerate 1-10
               If you have a slower PC then it's most likely that XL-it!
               runs slower than a real Atari. To archive more speed you can
               skip frames. A side-effect is that the collision-detection
               may fail in a few games.
               Hint:Even if XL-it! runs fast enough try to use this
               function if you use utilities (e.g. Assembler, BASIC etc.).
               You'll like the speed !
             + 320x240 resolution
               The standard low-resolution of your VGA-card is 320x200
               pixels. The Atari 8bit can display more than 200 lines on
               the screen. If you run into a program that lacks parts of
               the screen enable this option. Due to the nature of the
               320x240 video-mode this slows XL-it! down.
             + Color-Artifacting
               This feature is introduced by v0.19. Have you ever wondered
               why you saw colors in games like Loderunner or Ultima ? The
               answer is color-artifacting. This technique makes use of the
               lower resolution of NTSC-TVs (On Pal-TVs [like mine] this
               doesn't look as good as on NTSC-TVs). Anyway this feature
               tries to simulate this behaviour. It's in an early stage
               though.
             + 50 Hz speed-lock, 60 Hz speed-lock
               If XL-it! runs too fast on your system then you can lock the
               speed at 50 Hz (PAL) or 60Hz (NTSC). This probably only
               works good if your system is about 15-20 frames faster than
               a real Atari.
        o Calibrate Joysticks
               XL-it! supports a PC-joystick. Unluckily the programming of
               support for a PC-joystick is a nightmare. In fact it's
               pretty easy but the hard part are all those different
               joysticks out there.
               Therefore it's necessary that you calibrate your joystick
               before you use it. A sign for a wrong calibration are
               "ghost-moves". E.g. you don't move the joystick but the
               player moves on the screen.
               The calibration-setup is saved of course.

---------------------------------------------------------------------------

Keyboard

     XL-it! uses it's own keyboard-handler to gather full control of the
     PC-keyboard. Therefore there is no support for your country-specific
     keyboard-layout (except Germany).
     The default is the US/UK keyboard layout.

     Special key-assignements:

      F1      Option
      F2      Select
      F3      Start
      F4      Help
      F5      Break
      F6      Toggle joystick-mode
      F7      Enter Monitor
      F8      Enter User-interface
      Shift F8Exit XL-it!
      F9      Switch your virtual Atari off and on again
      F10     Reset
      Alt     Atari/INVERS

     Switching your virtual Atari on and off again is very useful if a
     program needs the option key pressed down while your Atari powers up.
     Just press down Option (F1), keep it pressed and then hit F9. You can
     release F1 if the system is booting (like an original Atari XL/XE). Of
     course you can also use the user-interface instead of this procedure.

     If you press F6, the ALT-keys will be used as fire and the cursor-keys
     will be used as the stick. By pressing F6 again, these keys will work
     as before. By default the joystick is emulated in port 1. Some games
     need the joystick in port 2. Therefore it is possible to use port2
     with "Swap-Joysticks". If you have a PC-joystick connected and it's
     detected by XL-it! then this PC-joystick will be used to emulate the
     Atari joystick. Please calibrate your joystick (userinterface ->
     "Calibrate Joystick").

---------------------------------------------------------------------------

Monitor

     When you enter the monitor (F7), the actual CPU-status is displayed.
     In addition the average frame-rate since the last monitor-session (or
     since the start of the emulator) is displayed. If you want to measure
     the frame-rate for a certain screen, then this procedure delivers a
     more exact value:

        o enter the monitor
        o leave the monitor
        o wait 5-10 sec's
        o enter the monitor again

     Attention: disk-access and switching to the user-interface heavily
     disturbs the measurement !

     The following is an overview of the monitor-commands. The goal of this
     document can't be to explain you how machine-code monitors work. The
     monitor is mainly a debugging tool for myself but it can be very
     usefull for expierenced users, too.

     Monitor-Commands

      a xxxx            Assemble starting at $xxxx
      d xxxx            Disassemble starting at $xxxx
      m xxxx            Dump the memory at $xxxx
      D xxxx            Disassemble the displaylist at $xxxx
      : xxxx yy ...     Set memory at $xxxx to $yy ...
      s xxxx yyyy zz ...Search from $xxxx to $yyyy for $zz ...
      r reg xx          Set a 6502-register to $xx
      t                 Trace (single-step)
      g xxxx            Go until PC==$xxxx
      p xxxx            Set PC to $xxxx
      c                 Display the contents of some custom-chip registers
      T newval oldval   Trainermaker-Assistent
      L name xxxx       Loads the file "name" at $xxxx
      ?                 Display command-overview
      x                 Leave monitor-mode

     Some words about the Trainermaker-Assistent:

     Everytime you enter "T newval oldval" the contents of the memory are
     compared with the contents of a backup-buffer and then the new value
     is copied to the backup-buffer. This means that you find positions
     that changed from the old value to the new value.

     Example:
        o You start Boulder Dash and you have 3 lives
        o Enter the monitor and give this command "T 3 3" to initialize the
          backup-buffer
        o When you die enter the monitor again and make "T 2 3"
        o You will see the memory-positions that changed from 3 to 2
        o Enter ": memoryposition 8" and you'll notice that you have 7
          lives (=8-1) when you die the next time!

     All in all it's not as complicated as it looks like. Of course the
     above method doesn't work with every game !

---------------------------------------------------------------------------

The Author

I am a German college-student of computer science. In 1998 I will finish
the college with a master's degree.
I developed this emulator because I always wanted to write an emulator. As
I liked my Atari 800 XL that machine was the way to go. After a few days
(the 6502 emulation was working and some basic graphic-functions were
working, too) I noticed that this machine was great because of its
abilities and it is by far not as easy to emulate this system as I thought.
In addition I noticed that I forgot a lot in the 7 years I had not used my
Atari. Therefore I want to say thanks to all people on the Net who helped
me with their hints (please refer the file "credits" for some special
thanks).

If you want to contact me (for feedback, questions or why ever), try one of
these Internet- addresses:

   * iig05-1@htw.uni-sb.de
   * magi@stud.uni-sb.de
   * WWW: http://myst.slcc.edu/~markus

I try to answer every mail but please make sure that your reply-address is
correct ! It happened several times that my answer was bounced !

If you do not have access to the Internet, you can reach me via "normal"
mail:

        Markus Gietzen
        Ludweilerstr. 126
        66352 Grossrosseln 1
        Germany

Donations

I develop XL-it! in my leisure-time. If you use it on a regular basis, I
would appreciate to get a small (or not so small :-) gift from you.

---------------------------------------------------------------------------

Frequently Asked Questions - FAQ

Please read this section before you ask me or before you post to a
newsgroup. Anway this doesn't mean that I'd kill you if you ask a question
that is answered here.

Q:
What about .PRO format ?
A:
The .PRO format is an image-format that is used by APE. This format is not
supported and will not be supported.

Q:
What are .BIN, .COM or .EXE files ?
A:
These files can be everything. In the most cases these are programs that
must be loaded from DOS. You may transfer them to an .ATR or .XFD image but
you can also use the virtual harddrive feature of XL-it! Mount the
directory (with the user-interface) and then load the files from DOS. I had
good experiences with DOS2.5.
SpartaDOS and MyDOS actually can't load the files from virtual harddrives.
Normally you will need to disable BASIC first.

Q:
The program XYZ does not work although I was told that it works.
A:
Many programs need a disabled BASIC or Option pressed down while the
power-up phase. If this does not help, make sure that you have the same
version as the people who told you that the program work.

Q:
How can I transfer files from my Atari to my PC?
A:
You need APE or SIO2PC. This means that you have to build a simple cable
that connects your Atari or your Atari-periphery with your PC. XL-it! will
support this cable in a future version, as well. (to be exact: it will
support the same cable that APE uses to access Atari periphery ! The
so-called XFORMER-cable will not work.)

Q:
When will the next version of XL-it! be available?
A:
As XL-it! is not my main project I cannot say when the next version will be
available. Therefore I suggest that you read the newsgroup
"comp.sys.atari.8bit" and check the XL-it! homepage on a regular basis.

Q:
There are some lines missing at the top or at the bottom !
A:
Enable the 320x240 resolution. This mode is not the default mode because it
is slower than the 320x200 resolution.

Q:
I can't create a character disk with XYZ and formatting does not work.
A:
Formatting disks is not yet supported.

Q:
How can I play games from a 2600 or 5200 ?
A:
The 2600 is completely different from the Atari home-computer and therefore
there will be no support for the 2600. The 5200 is very similar to the
Atari 800 system. I do not want to say that I will never support it but
surely not at the moment. But there are several emulators for these systems
out. (e.g. VSS by Dan Boris)

Q:
Why is there no source available ?
A:
I made bad experiences with releasing sources of my programs to the public.
There are always some guys who start making money with my work. Therefore I
only share code with people who showed me that they are able to program and
that I can trust their words.

Q:
(for Germans): Weshalb sind die Tasten x, y usw. vertauscht ?
A:
Seit Version 0.14 ist die amerikanische Tastatur vorgegeben. Mit "-german"
kann die deutsche Tastaturuntersttzung aktiviert werden. Oder einmal im
User-Interface einstellen und dann merkt XL-it! sich das.

Q:
How can I change disks ?
A:
You can change the actual disk-images in the monitor (F7) but I suggest
that you use the user-interface (F8).

Q:
The cursor-keys don't work !
A:
XL-it! emulates the real cursorkeys of an Atari. Many programs (e.g.
SpartaDOS) use "- = + *" to make life easier on real Ataris without
seperate cursorkeys. Just use "- = + *" and it will work.

---------------------------------------------------------------------------
(c) 1997 by Markus Gietzen
