4

                               4
                               
                 XL-it!  Atari 8-bit Emulator

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                         Version 0.16

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                                        1996 BY MARKUS GIETZEN




                           Contents



1 Introduction                                                3
2 Copyright                                                   3
3 Features                                                    3
4 Installation                                                4
 4.1 Sound                                                   4
5 Working with the emulator                                   4
 5.1 Command-line Options                                    5
 5.2 Keyboard                                                5
 5.3 Joystick                                                6
6 Monitor                                                     6
 6.1 Commands                                                6
7 The Author                                                  7
 7.1 Donations                                               8
 



1   Introduction
XL-it! emulates the Atari 8-bit home-computer series.

It is developed with Watcom C/C++ and needs at least a 386 CPU.
The   emulator   is  optimized  for  the  use  with   PentiumTM
processors. Parts of the emulation are written in assembly  and
the number of this parts will grow in the future.

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!.


2   Copyright
XL-it! is  1996 by Markus Gietzen.

XL-it!  is  free  as  long as it is not used  in  a  commercial
matter. Donations are very welcomed!

  I  still have the right to forbid the use of the emulator  at
any time.

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

3   Features
The actual version of XL-it! supports the following features:

     Player and Missiles with collisions
     
   GTIA-Modes
   Displaylist-Interrupts
   Sound-Support (via Soundblaster)
   Fine-Scrolling
   Overscan, underscan and "normal"-scan supported
   XL/XE and "old" Atari 800 emulation
   4 normal 1050 drives (with real emulation of the serial
port)!
   .XFD and .ATR disk-images
   Built-in Monitor
   User-Interface
  
  

4   Installation
As you are able to read this document you have probably already
decompressed the XL-it! archive. 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.

     XL-ROM: atarixl.rom (16384 Bytes)
     
   BASIC-ROM: ataribas.rom (8192 Bytes)
   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.

4.1 Sound
Starting  with version 0.14 XL-it! used real samples. Therefore
there  must  be  a directory called "samples"  in  your  XL-it!
directory. If nothing went wrong, you should already have  such
a directory where you can find the WAV-files.

Due  to the fact that I moved over to a new sound-library there
is  now a Soundblaster-detection. This means that there  is  no
need to setup anything else.

Unfortunately this auto-detection leads to non-working sound on
some  systems.  I'm sorry but I can't help  you.  I'm  not  the
author of that library !

There are new samples in this version ! Make sure that you have
really replaced your old samples with the new ones !


5   Working with 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]).

  Any  command-line option that is not preceded  by  a  '-'  is
considered to be a disk-image.

    atari disks\dungeon1.xfd disks\dungeon2.xfd
    
 This uses "dungeon1.xfd" as "D1:" and "dungeon2.xfd" as "D2:".

In addition you should read the "Frequently Asked Questions" at
the end of this document!

Hint: Every image that doesn't end with ".atr" is assumed to be
an  ".xfd"  image ! Therefore please don't rename your  ".atr"-
images.

5.1 Command-line Options
In  addition  to the disk-images you can use these command-line
switches to configure the behavior of XL-it!:

     "-nobasic"            Disables the BASIC-cartridge
     
   "-nosound"            Disables SOUND-support
   "-nopatch"            Disables all patches (not really
needed)
   "-joyswap"            Emulates a joystick in port 2
instead of  port 1
   "-cart filename"       Loads the given 8k or 16k
cartridge-image
   "-oldmode"            Atari 800 emulation.
   "-modex"         Use 320x240 pixels (slower!)
   "-german"             Use German keyboard-layout
   "-lock50"        Lock the emulator at 50Hz (=PAL)
   "-lock60"        Lock the emulator at 60Hz (=NTSC)
   "-frame x"            Displays every x. frame
5.2 Keyboard
Special Atari-keys:

        Key  Function
             
        F1   Option
             
        F2   Select
             
        F3   Start
             
        F4   Help
             
        F5   Break
             
        F6   Toggle Joystick-mode
             
        F7   Enter Monitor
             
        F8   Enter User-Interface
             
        Shi  Exit XL-it!
        ftF  
        8
        
        F9   Switch your virtual  Atari
             off and on again
             
        F10  Reset
             
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).  Of course you can  also  use  "-nobasic"
instead of this procedure.

5.3 Joystick
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 "-joyswap".

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.

The  PC-joystick routine has been tested with several joysticks
and  joypads but it can still happen that your joystick doesn't
work (esp. with old analog  "beasts").


6   Monitor
If  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:

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


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

I  got  reports that a frame-rate of 35-40 fps already reflects
the  original speed of an ATARI. I think this is caused by  the
DMA.  If  someone  knows the exact fractions of  time  that  is
stolen  from  the CPU when the DMA is enabled then  contact  me
please.

6.1 Commands


Command       Functionality
              
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 Search  from $xxxx to  $yyyy  for
zz ...        $zz ...
              
r reg xx      Set a 6502-register to $xx
              
t             Trace
              
g xxxx        Go until PC==$xxxx
              
p xxxx        Set PC to $xxxx
              
c             Display  the  contents  of   some
              custom-chip registers
              
X name        Set   the  disk-image  for  drive
              1,2,3 or 4.
where         
X{1,2,3,4}    For         example:           "1
              disks\dungeon3.xfd"
              
?             Display command-overview
              
x             Leave monitor-mode
              
T      newval Trainermaker-Assistent. You  give
oldval        it  the  new  value and  the  old
              value.  All corresponding memory-
              positions are reported.
              
L name xxxx   Loads the file "name" at $xxxx
              


Some words about the Trainermaker-Assistent:

Every  time  you  enter "T newval oldval" the contents  of  the
memory  is  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   You start Boulder Dash and have 3 lives

         n   Enter the monitor and give this command "T 3 3" to
           initialize the backup-buffer
           
n   When you die enter the monitor again and make "T 2 3"
n   You will see the memory-positions that changed from 3 to 2
         n   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 !


7   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 some day (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://www.htw.uni-sb.de/people/mgietzen.html
   WWW: http://www.htw.uni-sb.de/people/mgietzen/atari/xl-
it.html
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

7.1 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.

It  depends  on  these  donations if I'll release  any  further
versions of XL-it!



                  Frequently Asked Questions

Q: XL-it! runs too slow on my computer.
   
A: Speed  is  still a problem. I suggest that you  disable  the
   sound-support  and  that you do not use  "-modex".  You  can
   also  use "-frame x" to drop several frames. This speeds  up
   the  emulation  but can also lead to some collision-problems
   in the PM-graphic.
   
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 or .COM files ?
   
A: These  files can be everything. In the most cases these  are
   programs  that must be loaded from DOS. Before  you  can  do
   this  you  must transfer the files into .XFD or .ATR  images
   with  a  tool like imageman. There is no way to  load  these
   files directly with XL-it! at the moment. (but in work)
   
Q: The  program XYZ does not work although I was told  that  it
   works.
A: 
   Many  programs need "-nobasic" 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: The program XYZ does not work at all.
   
A: Please  do not forget that this is an early version  of  XL-
   it!  I  am aware that several programs do not work with  the
   emulator. I try my best to improve XL-it!. If you  can  find
   out why a program does not work, do not hesitate to send  me
   a mail.
   
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.
   
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:  "http://www.htw.uni-
   sb.de/people/mgietzen/atari/xl-it.html".  Furthermore   it's
   not  sure  if  there will be any new versions  in  the  near
   future.
   
Q: There are some lines missing at the top or at the bottom !
   
A: Use "-modex" to 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.
   
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.
   
Q: I  am  tired of typing "-modex" every time. How can  I  make
   this switch permanent ?
A: 
   Write  an  xlit.bat. This batch-file could  look  like  this
   one:
   
   atari.exe -modex -nosound %1 %2 %3 %4 %5 %6
   
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 emulator cannot find the wav-files.
   
A: Please  read the installation-chapter again! You  must  make
   sure  that there is a directory "samples" that contains  the
   wav-files.
   




