
Dear Reader,

This package provides you with the possibility to produce the ROM images
as required for Atari 8-bit emulators, from a source version. The resulting
ROM images are byte-for-byte equal to the ROMs as found in the original Ataris.

This version of the ROM sources can faithfully reproduce the following ROMs:

BASIC                  version A, B, and C
OS/10K (400/800)       version B/NTSC
OS/16K (xl/xe series)  1200 XL, XL/XE rev 1/2/3/4, XL/arabic
5200                   ROM

===== Release History =====

This is the third incarnation of this package.

The first version, released on January 13th 2000, used the rather outdated
TASM assembler.

From version 2 (released on July 23rd, 2000) onward, the free CC65 assembler
is used instead, which is much better in every respect. For example, since a
real linker is available, there is no ordering problem on symbols that are
defined and used between source-files. In the first version, this necessitated
the inclusion of the generated "export" files in the previous release. In this
respect, things are much cleaner now.

The sources themselves changed very little between version 1 and 2. The most
obvious change is that I elected to change all 6502 mnemonics to lower case.
Porting the code to CC65 took only about two hours.

This third version focusses on supporting more types of ROMs. A grand total of
11 different images can be produced now (compared to two in the second release)
spanning a wide range of Atari machines and ROM versions. Now it is possible to
produce all three known BASIC versions, an OS-B/NTSC 400/800 ROM image, a
1200 XL OS-ROM image, and four versions of regular XL/XE ROMS. As an encore,
two peculiar ROMs are included: the Arabic-language XL/XE ROM which comes from
a very rare type of Atari that was targetted at Arabic-speaking countries,
featuring an Arabic character set, and the 5200 XEGS ROM.

All this compares rather favorably with the previous release's capabilities,
which only supported BASIC version C and the XL/XE rev.2 ROM.

There is a downside to this, of course... The source code itself has become
rather messy in places due to conditional compilation based on the type of
ROM being assembled. Furthermore, there are still quite large memory areas
(especially of 1200 XL-specific code) that are not yet tidied up.

One of the basic problems encountered is that rather large areas of code
have moved between OS releases. The best solution for this would be to use
the linker to sort this out, but it's quite difficult (for me, at least) to
figure out an elegant way of achieving this. For now, I have resorted to
conditionally including these code-areas from files named "*.inc". It works,
but I am not completely satisfied with the esthetics of this.

A lot of work remains to be done with respect to commenting the source. Also,
the process of "make'ing" the ROMs and the code shuffling problem mentioned in
the previous paragraph are in dire need of some cleaning up. If you like to
help in either of these areas, please let me know.

===== The Manual =====

To be able to produce the ROM images, you will have to use the freeware
"cc65" package, provided by Ullrich von Bassewitz. This system gives you
a great C programming environment for 8-bit systems (not only Ataris,
but also CBM-64, Apple-II, etcetera); for the purpose of producing the
ROM images, you will only need the assembler and linker.

Note that the Atari ROM sources use features that are not directly supported
by the current mainstream release of the cc65 package (as of this writing,
version 2.5.0). You will either have to wait for a new release or try your
luck at the "snapshot" version (as I do).

Furthermore, as the process of building the sources has become quite
complicated due to the many different ROM versions supported, it is now
assumed that you are working on a unix-like platform; Linux works fine
for me, but Solaris or even WIN32/CygWin should be fine as well.

The following steps need to be taken to produce the ROM images:

(1) Download the latest CC65 compiler suite. You can get there
    via "http://www.cc65.org/"; download either the source package
    and compile it, or get the pre-built binaries for your favourite
    platform. [note: the snapshot version is only distributed in
    source form.]

(2) After installing the compiler suite, make sure that both the
    assembler ("ca65") and the linker ("ld65") are executable, by
    adding the directory in which they reside to your PATH.

(3) Now do...

      cd BASIC  ; make check
      cd OS-10K ; make check
      cd OS-16K ; make check
      cd 5200   ; make check

    This should run the appropriate assembler and linker commands to
    produce the ROM images, then run an MD5 check on the resulting
    files. You should only encounter "OK's" in this stage!

    One note: executing make in the OS-16K directory produces six
    rom images called atarixl-rev<n>.rom ... The meaning of the <n>
    is as follows:

      0     : 1200 XL
      1..4  : XL/XE OS-ROM rev. 1 .. 4 (2 is most common, by the way)
      59    : Arabic ROM.

    Why 59? Good question! If anybody knows why on earth these ROMs
    are labelled with revision ID '59', I'd be interested to hear!

(4) Step four ... There is no step four!

=========================

-- Many thanks go to Ullrich von Bassewitz for producing the GREAT
   cc65 compiler suite. I'm not easily impressed with somebody else's
   programming efforts, but I can only stand in awe of this tremendous
   achievement.

Best regards,

  Sidney Cadot
  Tuesday, December 12th, 2000
  sidney@ch.twi.tudelft.nl

==========================
