first version, most text by Shawn

git-svn-id: svn://svn.cc65.org/cc65/trunk@2536 b7a2c559-68d2-44c3-8de9-860c34a00d81

diff --git a/doc/atari.sgml b/doc/atari.sgml
new file mode 100644 (file)
index 0000000..a564cf8
--- /dev/null
+++ b/doc/atari.sgml
@@ -0,0 +1,203 @@
+<!doctype linuxdoc system>
+
+<article>
+
+<title>Atari specific information for cc65
+<author>Shawn Jefferson, <htmlurl url="mailto:shawnjefferson@24fightingchickens.com" name="shawnjefferson@24fightingchickens.com">
+Christian Groessler, <htmlurl url="cpg@aladdin.de" name="cpg@aladdin.de">
+<date>16-Oct-2003
+
+<abstract>
+An overview over the Atari 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 runtime system as it comes
+with the cc65 C compiler. It describes the memory layout, Atari specific
+header files, available drivers, and any pitfalls specific to that
+platform.
+
+Please note that Atari specific functions are just mentioned here, they are
+described in detail in the separate <htmlurl url="funcref.html" name="function
+reference">. Even functions marked as "platform dependent" may be available on
+more than one platform. Please see the function reference for more
+information.
+
+
+<sect>Binary format<p>
+
+The standard binary output format generated by the linker for the
+Atari target is a machine language program with a standard executable
+header (FF FF &lt;start address&gt; &lt;end address&gt;). These values are
+calculated in the crt0.s file from the __CODE_LOAD__ and __BSS_LOAD__
+values, so keep this in mind if you create a custom linker config file
+and start moving segments around.  You can override this behaviour by
+creating your own crt0.s file and linking it into your program.  A run
+vector is added to the end of the file (&dollar;02E0 &lt;run vector&gt;)
+and is calculated using __CODE_LOAD__ in crt0.s also.
+
+
+<sect>Memory layout<p>
+
+The default linker script assumes that the BASIC ROM is disabled (or
+the BASIC cartridge unplugged). This gives a unsable memory range from
+&dollar;2E00 - &dollar;BC1F. The library startup code examines the
+current memory configuration, which depends on the size of the
+installed memory and cartridges present, by inspecting the value in
+the MEMTOP (&dollar;2E5) variable. Then the initial stack pointer,
+which indicates the upper bound of memory used, is adjusted. The load
+address of &dollar;2E00 was chosen to accommodate having a DOS loaded
+and a driver that resides in low memory such as the 850 R: handler.
+You can override this behaviour by creating a custom linker config
+file.
+
+Special locations:
+
+<descrip>
+  <tag/Text screen/
+  The text screen depends on the installed memory size and cartridges
+  and can be obtained from the SAVMSC variable (&dollar;58).
+
+  <tag/Stack/
+  The C runtime stack is located at MEMTOP and grows downwards,
+  regardless of how your linker config file is setup.  This
+  accomodates the different memory configurations of the Atari
+  machines, as well as having a cartridge installed.  You can override
+  this behaviour by writing your own crt0.s file and linking it to
+  your program.
+
+  <tag/Heap/
+  The C heap is located at the end of the program and grows towards the C
+  runtime stack.
+
+</descrip><p>
+
+
+
+<sect>Platform specific header files<p>
+
+Programs containing Atari specific code may use the <tt/atari.h/
+header file.
+
+
+<sect1>Atari specific functions<p>
+
+The functions listed below are special for the Atari. See the <htmlurl
+url="funcref.html" name="function reference"> for declaration and usage.
+
+<!-- TODO: the other functions -->
+<itemize>
+<item>get_ostype
+<item>graphics
+</itemize>
+
+
+<sect1>Hardware access<p>
+
+The following pseudo variables declared in the <tt/atari.h/ header
+file do allow access to hardware located in the address space. Some
+variables are structures, accessing the struct fields will access the
+chip registers.
+
+<descrip>
+
+  <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
+  The <tt/GTIA_READ/ structure allows read access to the GTIA. The
+  <tt/GTIA_WRITE/ structure allows write access to the GTIA.
+  See the <tt/_gtia.h/ header file located in the include directory
+  for the declaration of the structure.
+
+  <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
+  The <tt/POKEY_READ/ structure allows read access to the POKEY. The
+  <tt/POKEY_WRITE/ structure allows write access to the POKEY.
+  See the <tt/_pokey.h/ header file located in the include directory
+  for the declaration of the structure.
+
+  <tag><tt/ANTIC/</tag>
+  The <tt/ANTIC/ structure allows read access to the ANTIC.
+  See the <tt/_antic.h/ header file located in the include directory
+  for the declaration of the structure.
+
+<!-- TODO: the other things from atari.h -->
+
+</descrip><p>
+
+
+
+<sect>Loadable drivers<p>
+
+<sect1>Graphics drivers<p>
+
+Currently there are no graphics drivers available for the Atari platform.
+
+<sect1>Extended memory drivers<p>
+
+Currently there are no extended memory drivers available for the Atari
+platform.
+
+<sect1>Joystick drivers<p>
+
+<descrip>
+
+  <tag><tt/atari-stdjoy.joy/</tag>
+  Supports up to four standard joysticks connected to the joystick ports of
+  the Atari.
+
+</descrip><p>
+
+
+
+<sect1>Mouse drivers<p>
+
+Currently no drivers available (in fact, the API for loadable mouse drivers
+does not exist). There is a static driver you can use.
+
+
+<sect1>RS232 device drivers<p>
+
+Currently there are no RS232 loadable drivers available for the Atari
+platform. There is a static driver you can use.
+
+
+<sect>Other hints<p>
+
+
+
+<sect>Bugs/Feedback<p>
+
+If you have problems using the library, if you find any bugs, or if you're
+doing something interesting with it, I would be glad to hear from you. Feel
+free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
+name="uz@cc65.org">).
+
+
+
+<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>