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 Tastaturunterstützung 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