10

                              10
                               
                 XL-it!  Atari 8-bit Emulator

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                         Version 0.15

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                               

                                        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++ 10.6 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

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.


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 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 the emulator starts
as  if you switch on your Atari without a disk in a drive.  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 (faster
emulation!)
   "-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
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
             
        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".

There is actually no support for a PC-Joystick (but in work) .


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 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) if 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.



                  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".  If  it  is
   still too slow, try a newer version when it is available.
   
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".
   
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.
   
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: 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.
   
Q: Why  is there no User-Interface ? Why is there no 4711 ? Why
   is there no ...
A: 
   XL-it!  is a free product and the emulation fits my needs  !
   Actually the Atari 8-bit scene is a disappointment  for  me.
   It  seems that many people (luckily not everyone)   want  to
   have  a  perfect product (even when it's version  0.01)  for
   free  and  they  count  freeware-developers  as  a  kind  of
   slaves.  Therefore I will slow-down the development  of  XL-
   it!  and  start  another commercial emulator project  (hint:
   68k based game console).
   




