Add Atari 2600 documentation

diff --git a/doc/atari2600.sgml b/doc/atari2600.sgml
new file mode 100644 (file)
index 0000000..ae1b6cb
--- /dev/null
+++ b/doc/atari2600.sgml
@@ -0,0 +1,124 @@
+<!doctype linuxdoc system>
+
+<article>
+
+<title>Atari 2600 specific information for cc65
+<author>
+<url url="mailto:contact@florentflament.com" name="Florent Flament"><newline>
+<date>2017-01-11
+
+<abstract>
+An overview over the Atari 2600 runtime system as it is implemented
+for the cc65 C compiler.
+</abstract>
+
+<!-- Table of contents -->
+<toc>
+
+<!-- Begin the document -->
+
+<sect>Overview<p>
+
+This file contains an overview of the Atari 2600 runtime system as it
+comes with the cc65 C compiler. It describes the memory layout, Atari
+2600 specific header files and any pitfalls specific to that platform.
+
+<sect>Binary format<p>
+
+The default binary output format generated by the linker for the Atari
+2600 target is a 4K cartridge image.
+
+<sect>Memory layout<p>
+
+cc65 generated programs with the default setup can use RAM from
+&dollar;0080 to &dollar;00FF - __STACKSIZE__, where __STACKSIZE__ is
+the size of the system stack with a default value of 16 bytes. The
+size of the system stack can be customized by defining the
+__STACKSIZE__ linker variable.
+
+Special locations:
+
+<descrip>
+  <tag/Stack/ The C runtime stack is located at &dollar;00FF -
+    __STACKSIZE__ and growing downwards.
+
+  <tag/Heap/ The C heap is located at &dollar;0080 and grows upwards.
+
+</descrip><p>
+
+<sect>Start-up condition<p>
+
+When powered-up, the Atari 2600 TIA registers contain random
+values. During the initialization phase, the start-up code needs to
+initialize the TIA registers to sound values (or else the console has
+an unpredictable behavior). In this implementation, zeros are written
+to all of TIA registers during the start-up phase.
+
+Note that RIOT registers (mostly timers) are left uninitialized, as
+they don't have any consequence on the console behavior.
+
+<sect>Platform specific header files<p>
+
+Programs containing Atari 2600 specific code may use the
+<tt/atari2600.h/ header file.
+
+The following pseudo variables declared in the <tt/atari2600.h/ header
+file allow access to the Atari 2600 TIA & RIOT chips registers.
+
+<descrip>
+
+  <tag><tt/TIA/</tag> The <tt/TIA/ structure allows read/write access
+  to the Atari 2600 TIA chip registers. See the <tt/_tia.h/ header
+  file located in the include directory for the declaration of the
+  structure. Also refer to the Stella Programmer's Guide by Steve
+  Wright for a detailed description of the chip and its registers.
+
+  <tag><tt/RIOT/</tag> The <tt/RIOT/ structure allows read/write
+  access to the Atari 2600 RIOT chip registers. See the
+  <tt/_riot.h/ header file located in the include directory for the
+  declaration of the structure. Also refer to the Stella Programmer's
+  Guide by Steve Wright for a detailed description of the chip and its
+  registers.
+
+</descrip><p>
+
+
+<sect>Loadable drivers<p>
+
+There are no drivers for the Atari 2600.
+
+
+<sect>Limitations<p>
+
+TBD
+
+
+<sect>Other hints<p>
+
+One may write a custom linker configuration file to tune the memory
+layout of a program. See the <tt/atari2600.cfg/ file in the cfg
+directory as a starting point.
+
+
+<sect>License<p>
+
+This software is provided 'as-is', without any expressed or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+<enum>
+<item> The origin of this software must not be misrepresented; you must not
+       claim that you wrote the original software. If you use this software
+       in a product, an acknowledgment in the product documentation would be
+       appreciated but is not required.
+<item> Altered source versions must be plainly marked as such, and must not
+       be misrepresented as being the original software.
+<item> This notice may not be removed or altered from any source
+       distribution.
+</enum>
+
+</article>

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 2c43a9b50534cffac49f777244e182b3f2f60573..da0233c62a6c67539e97fbba08298e02bb2ac35e 100644 (file)
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -4583,6 +4583,7 @@ compiler, depending on the target system selected:
 <itemize>
 <item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/
 <item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/
+<item><tt/__ATARI2600__/ - Target system is <tt/atari2600/
 <item><tt/__ATARI5200__/ - Target system is <tt/atari5200/
 <item><tt/__ATARI__/ - Target system is <tt/atari/ or <tt/atarixl/
 <item><tt/__ATARIXL__/ - Target system is <tt/atarixl/

diff --git a/doc/cc65.sgml b/doc/cc65.sgml
index 3e59d4cf09f45ed5c00f55448716813a59e2bddb..80dba89b8b492e1ca85675a1f67b0c91fcf803ca 100644 (file)
--- a/doc/cc65.sgml
+++ b/doc/cc65.sgml
@@ -752,6 +752,10 @@ The compiler defines several macros at startup:
 
   This macro is defined if the target is the enhanced Apple //e (-t apple2enh).
 
+  <tag><tt>__ATARI2600__</tt></tag>
+
+  This macro is defined if the target is the Atari 2600 game console.
+
   <tag><tt>__ATARI5200__</tt></tag>
 
   This macro is defined if the target is the Atari 5200 game console.

diff --git a/doc/index.sgml b/doc/index.sgml
index 44b58ef5e62af7785bdff32b8551d710744abcc1..9b7ab794e47f60021adf993866fb5b31956794f9 100644 (file)
--- a/doc/index.sgml
+++ b/doc/index.sgml
@@ -116,6 +116,9 @@
   <tag><htmlurl url="atari.html" name="atari.html"></tag>
   Topics specific to the Atari 8-bit machines.
 
+  <tag><htmlurl url="atari2600.html" name="atari2600.html"></tag>
+  Topics specific to the Atari 2600 Game Console.
+
   <tag><htmlurl url="atari5200.html" name="atari5200.html"></tag>
   Topics specific to the Atari 5200 Game Console.
 

diff --git a/doc/intro.sgml b/doc/intro.sgml
index d92fd1d20f2216d48338a9137a0a93c2a4e4b07d..bb8965c60c5b0f84483159ce0e045c035cc4d5d7 100644 (file)
--- a/doc/intro.sgml
+++ b/doc/intro.sgml
@@ -335,6 +335,35 @@ your harddrive directly.
 to the DOS menu.  Your C program should wait for a keypress if you want to see
 any output.
 
+<sect2>Stella<p>
+Available at <url
+url="http://stella.sourceforge.net">:
+
+Stella is a multi-platform Atari 2600 VCS emulator. The latest version
+is available on the emulator's website. It is also available through
+the package manager of most Linux distributions (Fedora, Ubuntu, ..).
+
+Compile the Atari 2600 sample with
+
+<tscreen><verb>
+make SYS=atari2600 samples
+</verb></tscreen>
+
+Then execute it with
+
+<tscreen><verb>
+stella samples/atari2600hello
+</verb></tscreen>
+
+<sect2>Harmony Cartridge<p>
+Available at <url
+url="http://harmony.atariage.com/Site/Harmony.html">:
+
+The Harmony Cartridge allows running any Atari 2600 binary on real
+hardware. The binary must be copied on an SD card, to be inserted in
+the Harmony Cartridge. It can then be inserted on an Atari 2600
+console, and run any binary on the SD card.
+
 
 <sect1>Atmos
 

diff --git a/doc/ld65.sgml b/doc/ld65.sgml
index 448157ce08e2eb662a428985e4d6488ca5e1eaaf..5687aa8abc851bd57202e99f7dcc35b0aad253c1 100644 (file)
--- a/doc/ld65.sgml
+++ b/doc/ld65.sgml
@@ -156,6 +156,7 @@ Here is a description of all of the command-line options:
   <item>module
   <item>apple2
   <item>apple2enh
+  <item>atari2600
   <item>atari
   <item>atarixl
   <item>atmos