XL-it!  Atari 8-bit Emulator
Version 0.16

© 1996 by Markus Gietzen

Contents

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

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	
ShiftF8	Exit XL-it!	
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 zz ...	Search from $xxxx to $yyyy for $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
where X{1,2,3,4}	Set the disk-image for drive 1,2,3 or 4.
For example:  “1 disks\dungeon3.xfd”	
?	Display command-overview	
x	Leave monitor-mode	
T newval oldval	Trainermaker-Assistent. You give 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
•	Enter the monitor and give this command “T 3 3” to initialize the backup-buffer
•	When you die enter the monitor again and make “T 2 3”
•	You will see the memory-positions that changed from 3 to 2
•	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:
A:	XL-it! runs too slow on my computer.
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:
A:	What about .PRO format ?
The .PRO format is an image-format that is used by APE. This format is not supported and will not be supported.	
Q:
A:	What are .BIN or .COM files ?
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:
A:	The program XYZ does not work although I was told that it works.
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:
A:	The program XYZ does not work at all.
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:
A:	How can I transfer files from my Atari to my PC?
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:
A:	When will the next version of  XL-it! be available?
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:
A:	There are some lines missing at the top or at the bottom !
Use “-modex” to enable the 320x240 resolution. This mode is not the default mode because it is slower than the 320x200 resolution.	
Q:
A:	I can’t create a character disk with XYZ and formatting does not work.
Formatting disks is not yet supported.	
Q:
A:	How can I play games from a 2600 or 5200 ?
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:
A:	Why is there no source available ?
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:
A:	(for Germans): Weshalb sind die Tasten x, y usw. vertauscht ?
Seit Version 0.14 ist die amerikanische Tastatur vorgegeben. Mit “-german”  kann die deutsche Tastaturunterstützung aktiviert werden.	
Q:
A:	I am tired of typing “-modex” every time. How can I make this switch permanent ?
Write an xlit.bat. This batch-file could look like this one:
atari.exe -modex -nosound %1 %2 %3 %4 %5 %6	
Q:
A:	How can I change disks ?
You can change the actual disk-images in the monitor (F7) but I suggest that you use the user-interface (F8).	
Q:
A:	The emulator cannot find the wav-files. 
Please read the installation-chapter again! You must make sure that there is a directory “samples” that contains the wav-files.