Add target atari7800

doc/atari7800.sgml

@@ -0,0 +1,122 @@
+<!doctype linuxdoc system>
+
+<article>
+<title>Atari 7800 specific information for cc65
+<author>
+<url url="mailto:contact@florentflament.com" name="Florent Flament"><newline>
+
+<abstract>
+An overview over the Atari 7800 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 7800 runtime system as it
+comes with the cc65 C compiler. It describes the memory layout, Atari
+7800 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
+7800 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 7800 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 7800 specific code may use the
+<tt/atari7800.h/ header file.
+
+The following pseudo variables declared in the <tt/atari7800.h/ header
+file allow access to the Atari 7800 TIA & RIOT chips registers.
+
+<descrip>
+
+  <tag><tt/TIA/</tag> The <tt/TIA/ structure allows read/write access
+  to the Atari 7800 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 7800 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 7800.
+
+
+<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/atari7800.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>