ACE: Atari Computer Emulator  v0.01
Copyright (c) 1993,1994	by Frank Barrus

This documentation was written on 4/21/96
And revised on 4/25/96

DISCLAIMER:
	Run this program at your own risk!
	I take _NO_ responsibility for anything it does to your
 	computer.  It shouldn't cause any problems, but then
	I've never run it on any machine other than my own
	(and an Alpha at R.I.T.) so I don't know what strange
	bugs might be lurking.  Therefore, you must be willing
	to accept the consequences of anything that happens from 
	running it.  (i.e. make sure you have backups, etc...)
	The SVGA version needs to run as root to use the SVGAlib,
	so that's why this warning is here.


This is an Atari 800/XL/XE emulator I wrote back in 1993, 
and briefly updated in 1994, but never released.  I've had this
thing sitting in my archives for several years, and I keep saying
that someday I'm going to find the time to finish it up and 
officially release it.   (In fact, years ago, I kept telling
people in the comp.sys.atari.8bit newsgroup that I was going to
release this program soon... oops)

Well, it does it least run, and can handle a lot of things
other emulators can't (even though not to my standards of
perfection for things I write myself)
and since it can be a good reference for others who want to work
on similar emulators, I figured it's about time I released it, AS IS.
The only changes I made were to give it a quick recompile with
the latest version of GCC (2.7.2) to make sure everything still
builds, and to fix a couple minor mistakes that the new compiler caught.
Other than that (and this file) everything is as it was over two 
years ago, so don't expect everything to work perfectly.

So, if something doesn't work, you can tell me if you want,
and I'll certainly take note of it, but I probably won't have
time to do anything about it in the immediate future.  
If you want to fix it yourself, feel free to go ahead and do so,
(and document the changes with what you did, where, and who
you are) and if you send me the changes, I'll try to update the version
I've made available.

If you want to use parts of this emulator as the core of an emulator
of your own, feel free to do so, as long as you make sure that your
program gives proper credit for the parts I wrote. (I would be
sure to do the same for others if they add things and want me
to release their code-- just common courtesy )


And, yes, it does do player/missile graphics, and collision detection.
It doesn't support GTIA modes at the moment, though. (only CTIA)
And it handles DLI's, although there might be some timing problems with them.
Sound is a bit cheezy too (simple PC-speaker sound, with the loudest
channel being the one played)


To build it:

For text only:  (VT100 type terminals)
	make ace

For SVGA (Linux):
	make vace

For X-Windows:
	make xace

And one other little thing you'll need to do, just so I don't get in
any legal trouble...  you'll need to get your own copy of the 
Atari OS ROM's, as well as any cartridges you want to run.
Rename the OS ROM to:
	OSREVA.rom	for old revision 'A' ROM's (400/800)  (10K)
	OSREVB.rom	for old revision 'B' ROM's (400/800)  (10K)
	OSREVC.rom	for 800xl/xe/etc...		      (16K)
	OSREVD.rom	for 1200xl?  (not sure on this one)   (16K)
However, by default the program will actually use either OSREVB.rom
for the 800 emulation, or OSREVC.rom for the XL/XE emulation, so
rename it (or make a link) if you actually have a different version,
but remember that A and B are not compatible with C and D.

As far as how to create the ROM files, please don't ask me-- lots
of other people have written emulators and had these requirements, so
either check the other emulators, or post to comp.sys.atari.8bit for help.
You need to get a dump of the Atari's memory from 
D800-FFFF for the 10K ROMs (OSREVA.rom, OSREVB.rom) and
from C000-FFFF for the 16K ROMs (OSREVC.rom, OSREVD.rom).
Note that the area from D000-D7FF can't be read from that location
on the Atari, since the registers reside there.  You need to either
read the chips directly, or map in the SELF-TEST routine into lower
memory (some register on the XL/XE lets you do this, and it's been
too long since I've done it, so I don't remember) at 5000-57FF
(I think that's right, but I could be wrong, since it's from my
distant memory from over two years ago)
and read it from there.  So, the XL/XE ROM files actually consist of:
		file offset:	Atari memory offset:
		0000-0FFF	C000-CFFF
		1000-17FF	5000-57FF
		1800-3FFF	D800-FFFF

For Basic, create an 8K ROM file called BASIC.rom from A000-BFFF.

Both .ATR and .XFD disk formats can be read.


For help, type 'vace -h' or 'ace -h' or 'xace -h' for a list of options
for that particular program.
When you run it, it will initially pop you into a little monitor
program.  Just type '$h' for help there, or ':g' if you just want
to run the emulator.
As far as keys go, look at the file 'console.key' and,
for starters, F9 exits from the emulator.  

So, get yourself the OS roms, BASIC roms, and type: 
	ace BASIC.rom
or:
	vace BASIC.rom
or:
	xace BASIC.rom
or even:
	vace StarRaiders.rom
and fire it up and relive the fun of Atari computers!

-------------
IMPORTANT NOTES:

	Okay, from my limited testing, it appears that
'ace', the text-only version, does not currently function.
I'll try to look into it sometime.
'vace' seems to run fine, however.
and 'xace' runs, but I realized that the key mappings are different,
so you'll have to play around with it or look at the source.

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

At the moment, I don't have time to document this any more than it is,
so you'll have to rely on the help that is built in, or look through
the source code.
Perhaps someday I'll finish the code and the documentation.
Although I'll guarantee one thing-- it's not going to happen until
after I graduate (May, 1996 - the ceremony at least)
and finish my Master's Thesis (sometime after that.. :)

In the meantime, email me and let me know what you think,
and keep in mind that enough support and enthusiasm might give me more
reason to make time to work on this once again.
(and, of course, donations don't hurt any either!   In fact, they
might increase the likelihood that I'll work on this project again!
Although I'd probably want to start converting it to C++, since I
don't really program in C anymore, unless people really had
a strong reason to want it in C still...)

Well, I hope you find it useful/interesting/entertaining/whatever...

Good luck!

	- Frank


p.s.  take a look at the PSIOX stuff too... that's for using
the parallel port to talk to an Atari or Atari peripherals.  Once
upon a time I built a cable for this, so I could use the PC as
a file server for my real Atari, or hook up Atari disk drives 
to the PC to read the disks... or, even use the Atari disk drives
directly with the emulator.

Also, note that you can access disks (real ones through PSIOX,
or ones that are in virtual disk files) directly from the emulator.
There are commands built in to get a directory and copy files and such.

------------------------
CHANGES:

v0.01: First public release
v0.02: Fixed a bug in the disk routines.  Disks now boot properly.

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

email: 	shaggy@csh.rit.edu		USmail: Frank Barrus
URL:	http://www.csh.rit.edu			4435 River Rd. Apt #3
						Scottsville, NY  14546

