
				  VSS V0.82
			   (Virtual Super System)

	   copyright 1996-2004 by Daniel Boris (dboris@comcast.net)
	   		http://www.atarihq.com/danb

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

Acknowledgments:

I would like to thank the following people for their help and encouragement:


	Keita Iida (Keita/Pooka/Fygar)
		for his enthusiasm for the 5200 beta testing and
		general encouragement.
	Markus Gietzen
		for ideas on improving the emulation.
	Bo Krogsgaard (Therion23)
		for his support of the project and his ASM coding and
		beta testing.
	Kevin Horton
		for figuring out the Bounty Bob bank switching.
	Ron Fries
		for his excellent pokey sound library.
	Jeffery Johnson (calamari), and Lepper.
		for help in beta testing
	John Swidensky and Ronen Habot 
		for the 64K bank switching scheme

	everyone on EFNET IRC channels #emulate and #rgvc.
	and all the 5200 developers on AtariAge

---------------------------------------------------------------------------
Copyright:
VSS is copyright 1996-2004 by Daniel Boris.
POKEY Sound is copyright 1996 by Ron Fries.

VSS is free as long as it is not used in a commercial matter and not
altered in any way. The contents of this archive should not be
added to or changed in any way. 

I maintain the right to forbid the use of the emulator  at
any time. I am not responsible for any damage caused by the use
of this program. This program is distributed "as-is". I make no
guarantees as to it's accuracy, performance, or compatibility with
the users hardware.

VSS is not to be included in CD collections of any sort.
---------------------------------------------------------------------------

VSS was written using DJGPP a free 32bit C/C++ development system:

	http://www.delorie.com/djgpp/ 

VSS uses Allegro, an excellent game programming library for djgpp by Shawn
Hargreaves:

	http://www.talula.demon.co.uk/allegro/

POKEY sound emulation was done with POKEY sound V1.2 by Ron Fries.


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

Setup:

	Before you can run VSS you need a copy of the 5200 BIOS ROM. For
copyright reasons I am not including this ROM image in this archive, but
it can be found at:

	http://www.atariage.com/

Once you get the image rename it to 5200.bin and put it in the same directory
as the emulator.

If you are running under MSDOS you must copy the file CWSDPMI.EXE to your
root directory.

You will also need cartridge images, but again for copyright reasons I cannot
provide these. PLEASE DO NOT E-mail me asking for ROM images! All messages
asking for ROM images will be promptly deleted.

The following games run almost perfectly:
Pac-man,Ms. Pac-man, K-razy Shoot Out, Frogger, Frogger II, Jungle Hunt
Astrochase, Berzerk, Blue Print, Centipede, Defender, Gorf, Gremlins,
Kaboom, Missile Command, Pengo, Space Dungeon, Super Breakout, Bounty Bob

A note on bad images: If an image does not run on the emulator it is possible that the ROM 
image is bad. I had a working Q-Bert image, and got another one that worked OK, but the top
of the screen was messed up. If the Atari logo comes up, and the title of the game is 
corrupt or missing, then the image is probably bad. If an image crashes out to the debugger,
then the image is probably bad. 
-----------------------------------------------------------------------------
Sound

VSS works with Sound Blaster and compatible cards. Be sure to have you
BLASTER environment variable set (see your sound card manual for more info).
If you are having problems with the sound under Windows NT, 2000 or XP, try 
VDMSound:


http://www.ece.mcgill.ca/~vromas/vdmsound/

Using VDMsound I can get clear sound running under Windows XP, without it I get
an annoying clicking sound during playback. 


-----------------------------------------------------------------------------
Basic Usage:

VSS runs from a DOS command prompt. There should be a command prompt option on 
the Windows Start menu, sometimes it's under Accessories.

To start VSS change the directory to the VSS directory and type 5200 followed by 
the name of the ROM file you want to load. For example to load a file called 
pac-man.bin you would type:

5200 PAC-MAN.BIN


-----------------------------------------------------------------------------
Config file:

VSS supports a default configuration file. This file (5200.cfg) will be
automatically created the first time you run the emulator. The config file
specifies all the default configurations that are to be used by the emulator.
Most of the options in the [config] section of the file corresponds to the 
command line options. For example "fr = 1" in the config file means to use a 
frame skip rate of 1. Any command line options you use when running the emulator 
will override the setting in the config file. So, for example, if you start 
the emulator with:

5200 pac-man.bin -frame=3

the emulator will use a frame skip rate of 3 instead of 1. If there is no config
file entry for an option and you don't specify a command line option for it, then
the emulator will use and internal default.

The only config option that does not correspond to a command line option is
the 'path' option. Path sets the directory to use when loading ROMs. So if
you have 'path = c:/vss/roms/' in the config file, and you type:

5200 pac-man.bin

the file: c:/vss/roms/pac-man.bin will be loaded. If you put a path in the
command line then it will override the config file:

5200 c:/vss/pac-man.bin

will load the file c:/vss/pac-man.bin.

-----------------------------------------------------------------------------
Command line options:

5200 file -[options]

	file - 5200 file to load. This must be a raw binary file, either
	16K or 32K long. If you supply a path name with the file name,
	for example: 5200 C:/VSS/ROMS/PAC-MAN.BIN then it will be loaded
	from that path, and the path option in the config file will be
	overridden.

	-frame=# - Sets frame skip rate. The emulator will display 1 out of
	every # frames. The higher the number, the faster the emulation, but
	more frames are skipped. I find that a frame rate of -frame=4 works
	good for most games. Some games display things every other frame,
	(e.g. Pengo, Wizard of Wor). In this case an even frame skip number will
	not work, but an odd number will. Please note that due to the way frame skipping
	is handled, the color scrolling Atari logo will appear to scroll at
	the same speed, but it will disappear faster.

	-pengo - Enables special keyboard joystick emulation for use in
	Pengo, Super Breakout, Missile Command and probably some others. 


 	-bb - Run Bounty Bob. If you use this switch Bounty Bob will be loaded from 
 	the following files no matter what file name you put on the command line:

         BB_A0_BF.bin   -   fixed bank at A000 to BFFF
         BB_40_4F.bin   -   4 banks at 4000 to 4FFF
         BB_50_5F.bin   -   4 banks at 5000 to 5FFF
	
	You can also run Bounty Bob by specifying any of the above files, in this case
	you don't need the -bb option.
	
	-map16k = Use single ROM 16K mapping mode
	
	-control =
	    This configures what type of control you wish to use. After the
	equals put one of the following options:

	   key    - Disables all other controls and uses the keyboard.

	   stickd - Enables a real joystick to be used in digital mode. This
		    mode works good for most games.
	    
	   sticka - Enables a real joystick to be used in analog mode. The
		    first time you use this option you will be prompted through
		    calibrating your joystick. Once you have done this once, it will
		    be saved in a file called 5200.cfg. If you ever need to
		    re-calibrate the stick start the emulator with the joystick
		    enabled and the -cal option.

	   mouse -  Enables joystick emulation via the mouse.

	 -cal - Forces re-calibration of the joystick. This must be used
	  in conjunction with -control=sticka or -control=stickd.

	 -nostick - Disables real joystick. This will override any other
	  joystick command line options.

	-mouse=# - Sets the mouse sensitivity. This option should be 
	 a value from 1 to 10. A value around 2 seems to work OK.
	 The 5200's joysticks are analog as opposed to digital. Most
	 games treat them as digital sticks, and these games work fine
	 with the keyboard controls. Some games like Missile Command,
	 and Gorf, use the 'analogness' of the sticks and work better
	 with the mouse.

	-nosound - Disables sound emulation.

	-nolimit - Turns off the speed limiter
	
	-debug	- Start in debug mode. (Only works in debug version of VSS)

----------------------------------------------------------------------------
Keyboard Controls:

Default controls

    Controller 1:
    
    Arrow keys 	     = Joystick
    Right Alt        = Top Fire Button 
    Right Ctrl       = Bottom Fire Button 
    Keypad 0..9      = Keypad number kets
    Keypad * 	     = Keypad *
    Keypad /	     = Keypad #
    Keypad -	     = Reset
    Keypad + 	     = Pause
    Keypad Enter     = Start
    
    Controller 2:
    
    A,D,S,W    	     = Joystick 
    Left Alt         = Top Fire Button 
    Left Ctrl        = Bottom Fire Button
    1-9,0            = keypad number keys
    -                = Key pad *   
    =                = Key pad # 
    F3               = Reset 
    F2               = Pause
    F1         	     = Start 
    
    General:
    Q          = Leave the emulator
    F8         = Enter debugger

Reconfiguring controls
----------------------

You can re-configure the keyboard controls in the [keyboard] section of the 
config file. The left side of each entry corresponds to a control on the 5200:

Controller 1:
K_P1_UP, K_P1_DOWN ,K_P1_LEFT ,K_P1_RIGHT - Stick
K_P1_BTOP, K_P1_BBOT - Fire buttons
K_PAD1_1, K_PAD1_2,K_PAD1_3,K_PAD1_4 ,K_PAD1_5 ,K_PAD1_6 ,K_PAD1_7,K_PAD1_8 - Keypad
K_PAD1_9, K_PAD1_*, K_PAD1_0, K_PAD1_#,K_PAD1_RESET,K_PAD1_PAUSE ,K_PAD1_START - Keypad

Controller 2:
K_P2_UP, K_P2_DOWN, K_P2_LEFT, K_P2_RIGHT  - Stick
K_P2_BTOP, K_P2_BBOT  - Fire buttons
K_PAD2_1, K_PAD2_2,K_PAD2_3,K_PAD2_4 ,K_PAD2_5 ,K_PAD2_6 ,K_PAD2_7,K_PAD2_8 - Keypad
K_PAD2_9, K_PAD2_*, K_PAD2_0, K_PAD2_#,K_PAD2_RESET,K_PAD2_PAUSE ,K_PAD2_START - Keypad

K_QUIT - Quit VSS
K_DEBUG - Enter Debugger 

The right side of each entry is the keyboard key to map to the 5200 control:

KEY_A - KEY_Z - Letter Keys
KEY_0 - KEY_9 - Number Keys
KEY_0_PAD - KEY_9_PAD - Number keys on keypad
KEY_F1-KEY_F12 - Function Keys
KEY_UP,KEY_DOWN,KEY_LEFT-KEY_RIGHT - Arrow Keys

KEY_ESC,KEY_TILDE, KEY_MINUS, KEY_EQUALS, KEY_BACKSPACE
KEY_TAB,KEY_OPENBRACE,KEY_CLOSEBRACE,KEY_ENTER
KEY_COLON,KEY_QUOTE,KEY_BACKSLASH,KEY_BACKSLASH2
KEY_COMMA,KEY_STOP,KEY_SLASH,KEY_SPACE
KEY_INSERT,KEY_DEL,KEY_HOME,KEY_END
KEY_PGUP,KEY_PGDN - Misc keys

KEY_SLASH_PAD,KEY_ASTERISK
KEY_MINUS_PAD,KEY_PLUS_PAD,KEY_DEL_PAD,KEY_ENTER_PAD - Misc keypad keys

KEY_LSHIFT,KEY_RSHIFT,KEY_LCONTROL,KEY_RCONTROL
KEY_ALT,KEY_ALTGR,KEY_LWIN,KEY_RWIN,KEY_MENU - Special keys

----------------------------------------------------------------------------
ROM Loading

VSS loads ROM images as follows:

8K roms - Loaded at $A000-$BFFF and mirrored at $8000-$9FFF
16K roms - 
	Most 16K cartridges used two ROM chips and are loaded as follows:
		First 8K at $4000-$5FFF, mirrored at $6000-$7FFF
		Second 8K at $8000-$9FFF, mirrored at $A000-$BFFF
	Some 16K cartridges used a a single ROM and are loaded as follows:
		Full 16K at $8000-$BFFF
	
	The emulator can identify most existing ROMS that use the second method,
	but you can force a 16K ROM to be loaded like this with the -map16k command 
	line switch.
32K roms - Loaded at $4000-$BFFF
40K roms - Bounty Bob bank switch scheme

	Files can be merged together in this order to for a single 40K image:

	 1. BB_A0_BF.bin   -   fixed bank at A000 to BFFF
         2. BB_40_4F.bin   -   4 banks at 4000 to 4FFF
         3. BB_50_5F.bin   -   4 banks at 5000 to 5FFF
         
        Here is the how bounty bob works:

	- Four 4 KB banks (A,B,C,D) are mapped into $4000-$4FFF. An access to $4FF6 
	selects bank A, $4FF7 - bank B, $4FF8 - bank C, $4FF9 - bank D. 

	- Four 4 KB banks (E,F,G,H) are mapped into $5000-$5FFF. An access to $5FF6 
	selects bank E, $5FF7 - bank F, $5FF8 - bank G, $5FF9 - bank H. 

	- The remaining 8 KB is mapped to upper 16 KB of cartridge address space 
	in Atari 5200. That is, $8000-$9FFF and $A000-$BFFF contain same data.
 
         
64K roms - 64K bankswitch scheme developed by John Swidensky
	Two 32K banks mapped to $4000-$BFFF
	Access $3FF8 or $BFF8 switches to first bank
	Access $3FF9 or $BFF9 switches to second bank
	Cartridge starts in second bank.
	

----------------------------------------------------------------------------
Known ROM issues:

Mr Do's Castle - Currently available ROM dump does not work, I believe it is
    corrupt.
Decathlon - Major graphics problems
Pole Position - Cannot steer
Micro-gammon SB, Miniature Golf - The 32K ROM images that are available for these
   will not work with VSS, since these are incorrect dumps. They can be converted
   to 16K version that will work by removing the upper 16K of data ROM the image 
   which contains no data.
Looney Toons Hotel - 16K version of this will work. I am not sure yet what's up
   with the 32K version. 
Berzerk - No voice
Choplifter - Flickers badly
Meteorites - Glitchy graphics


____________________________________________________________________________

Limitations
	 - no GTIA graphics modes 17
	 - no ANTIC mode 3 (I have never seen it used)
	 - vertical fine scrolling not implemented in every mode
	 - no mode 15 alising
	 - color palette isn't quite right
	 
------------------------------------------------------------------------------
Debugger:

Note: The debugging functions only work in the debug version of VSS, not the normal
version. 

To enter the debugger at the start of emulation, start VSS with the -debug option.
To enter the debugger at any other time press the debug key (F8 by default)

Commands:
	
	s	Single step execution
	antic	Display the ANTIC registers
	pokey	Display the POKEY registers
	gtia	Display the GTIA registers
	cpu 	Display the CPU registers
	quit 	Exit the emulator
	rf 	Run emulator until start of next video frame
	
	dl [addr]	  Shows a dis-assembly of the display list. If you don't specify 
	and address the current display list is shown
	
	md [addr]	  Show hex data starting at a specific address
	
	r [addr] 	  Run emulator until a specific address. If you don't specify 
	an address the emulator will resume normal execution.
	
	di [addr]	  Disassemble starting at a specific address
	
	dif [start] [end] [file] 	Disassemble to file
	
	wa [addr] 	  Set a watch on a specific address. While single stepping the watch
	will be displayed after the CPU registers. This command can also be used to break 
	execution when a specific address in RAM changes. Once the set the watch address and use
	the 'r' command to restart execution a break back to the debugger will occur when the value 
	at the watch address changes. NOTE: This does NOT watch for writes to that address, it only
	look for changes. So if an address contain $55 and the program writes $55 to that address 
	a break will not occur.
	
	If you don't specify an address
	the watch will be disabled. 
	
	mm [addr] [data] 	Write data to a specific address
	
	
	display			Display current screen
	colorpal		Display standard color palette
        colorpalgtia	  	Display full GTIA palette
	
	h,help,?	Display commands
	
	
	Hitting the Enter key will repeat the last s, md, or di command at the next address.

PM disable keys (default):
	
	G = Player 0
	H = Player 1
	J = Player 2
	K = Player 3
	
	V = Missile 0
	B = Missile 1
	N = Missile 2
	M = Missile 3
	
	Holding a key down will disable the corresponding player or missile until the key is released.
	
	
------------------------------------------------------------------------------
Version History:
V0.82  04/04/2004
	- Support for Bounty Bob put back in
	- PRIOR bit 5 implemented. Causes overlapping players to produce a third color
          in the overlapped area.
	- Updgraded to Allegro 4.0
	- Switched back to Allegro Sound library
	- Bit 0 of PM color registers is now dropped as it should be.
	- Added full support for 2 controllers 
	- Re-arranged some of the default keys
	- Compensated for stolen CPU cycles during DMA. River Raid now works.
	- Fixed display list handling, Blaster now works
	- Bounty Bob will now load if you try to load any of the three files that 
	  make it up. -BB switch not needed but still works.
	- Support for loading 40K Bounty Bob File
	- Support for 64K bank switch mode
	- New command line option -map16k to select 16K single ROM mode
	
	
	New to the debug version:
		New commands:
		colorpal - show the full 128 color pallette
		colorpalgtia - show the full 256 GTIA color pallette
		display - shows the last display the was rendered
		dif - Disassemble to a file
		wa - expanded the watch function break when the value at the watch address changes

v0.80  10/09/2001
	- Support for Bounty Bob Strikes Back not currently functioning.
	- Replaced CPU core with Neil Bradley's M6502 core
	- Cleaned up hardware startup and shut down to prevent memory leaks.
	- Using SEAL audio library instead of Allegro's for better sound
	  card support
	- Upgraded to Allegro 3.9.36
	- Added alternate 16K cart loading mode for Tempest, Super Pac-man, 
	  Track and Field and Millipede
	- Added support for 8K carts
	- Speed limiter now on by default. Use -nolimit to turn it off
	- Now uses VGA ModeX exclusively. Removed -modex and -top options.
	- Keys can now be re-configured in config file
	- Fixed colors in MODE 15. (Miniature Golf, Micro-gammon)



v0.77  04/12/98
	- Added GTIA modes 9,11 (Fractalus and Ballblazer)
	- Fixed DLI handling in mode 2 (fixed little quirk in pac-man)
	- Cleaned up the startup and shutdown routines. This should help
	  prevent memory leaks that may have caused people problems.
       -  Added -nostick option. This was requested for use with frontends.
       -  Improved speed limiter so games run smoother on high speed machines.
       -  Fixed color handling of ANTIC modes 2,4,5.
       -  Tweaked color palette.
       -  Enemies in Wizard of Wor are visible again. (I have no idea why!)
       -  Fixed DLI bug in mode ANTIC mode 15, Galaxian now runs.
       -  Added support for a default configuration file.
       -  Made command line options for selecting controllers a little simpler.
       -  Added better support for pathname handling.
       -  Added support for VGA modex.

v0.75  12/25/97
	- Added speed limiter, enable with -limit.
	- Fixed ANTIC address decoding, Bounty Bob now works.
	- Adjusted keyboard joystick values, Bounty Bob fix.
	- Bounty bob can now be run with just the -BB option.
	  Filename and first_line are set automatically.
	- Now using Allegro 3.0 game library.
	- Switched to Allegro streaming audio functions, which
	  increased the sound quality.

v0.71: 3/5/97
	- Fixed a major bug in the sound card initialization
	- Fixed a bug in the trigger handling with the mouse
	- Fixed bugs in Debugger. Program can now be stopped and
	  restarted more the once.
	- Added some error handling to the debugger commands.

v0.70: 2/18/97
	- Added horizontal fine scrolling
	- Added vertical fine scrolling to mode 4 and 5
	- Added support for Bounty Bob bankswitching
	- Added sound support
	- Size of cart images is now checked
	- Many speed optimizations
	- Fixed handling of bit 6 in SKSTAT
	- ANTIC writes are now fully decoded
	- The random number generator is now seeded properly

v0.60: 10/15/96
	- Ported to DJGPP for increased speed.
	- Fixed problems with frame skip mode.
	- Replaced interactive debugger with a new one with more features
	- Added joystick emulation.
	- Added second joystick emulation keyboard.
	- Fixed bug that locked up Star Raiders.

v0.50: 9/03/96 First Public Release

