git.sur5r.net Git - cc65/blob - doc/atari.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <title>Atari specific information for cc65
   6 <author>Shawn Jefferson, <htmlurl url="mailto:shawnjefferson@24fightingchickens.com" name="shawnjefferson@24fightingchickens.com">
   7 Christian Groessler, <htmlurl url="mailto:cpg@aladdin.de" name="cpg@aladdin.de">
   8 <date>16-Oct-2003
   9
  10 <abstract>
  11 An overview over the Atari runtime system as it is implemented for the cc65 C
  12 compiler.
  13 </abstract>
  14
  15 <!-- Table of contents -->
  16 <toc>
  17
  18 <!-- Begin the document -->
  19
  20 <sect>Overview<p>
  21
  22 This file contains an overview of the Atari runtime system as it comes
  23 with the cc65 C compiler. It describes the memory layout, Atari specific
  24 header files, available drivers, and any pitfalls specific to that
  25 platform.
  26
  27 Please note that Atari specific functions are just mentioned here, they are
  28 described in detail in the separate <htmlurl url="funcref.html" name="function
  29 reference">. Even functions marked as "platform dependent" may be available on
  30 more than one platform. Please see the function reference for more
  31 information.
  32
  33
  34 <sect>Binary format<p>
  35
  36 The standard binary output format generated by the linker for the
  37 Atari target is a machine language program with a standard executable
  38 header (FF FF &lt;start address&gt; &lt;end address&gt;). These values are
  39 calculated in the crt0.s file from the __CODE_LOAD__ and __BSS_LOAD__
  40 values, so keep this in mind if you create a custom linker config file
  41 and start moving segments around.  You can override this behaviour by
  42 creating your own crt0.s file and linking it into your program.  A run
  43 vector is added to the end of the file (&dollar;02E0 &lt;run vector&gt;)
  44 and is calculated using __CODE_LOAD__ in crt0.s also.
  45
  46
  47 <sect>Memory layout<p>
  48
  49 The default linker script assumes that the BASIC ROM is disabled (or
  50 the BASIC cartridge unplugged). This gives a usable memory range from
  51 &dollar;2E00 - &dollar;BC1F. The library startup code examines the
  52 current memory configuration, which depends on the size of the
  53 installed memory and cartridges present, by inspecting the value in
  54 the MEMTOP (&dollar;2E5) variable. Then the initial stack pointer,
  55 which indicates the upper bound of memory used, is adjusted. The load
  56 address of &dollar;2E00 was chosen to accommodate having a DOS loaded
  57 and a driver that resides in low memory such as the 850 R: handler.
  58 You can override this behaviour by creating a custom linker config
  59 file.
  60
  61 Special locations:
  62
  63 <descrip>
  64   <tag/Text screen/
  65   The text screen depends on the installed memory size and cartridges
  66   and can be obtained from the SAVMSC variable (&dollar;58).
  67
  68   <tag/Stack/
  69   The C runtime stack is located at MEMTOP and grows downwards,
  70   regardless of how your linker config file is setup.  This
  71   accomodates the different memory configurations of the Atari
  72   machines, as well as having a cartridge installed.  You can override
  73   this behaviour by writing your own crt0.s file and linking it to
  74   your program.
  75
  76   <tag/Heap/
  77   The C heap is located at the end of the program and grows towards the C
  78   runtime stack.
  79
  80 </descrip><p>
  81
  82
  83
  84 <sect>Platform specific header files<p>
  85
  86 Programs containing Atari specific code may use the <tt/atari.h/
  87 header file.
  88
  89
  90 <sect1>Atari specific functions<p>
  91
  92 The functions listed below are special for the Atari. See the <htmlurl
  93 url="funcref.html" name="function reference"> for declaration and usage.
  94
  95 <itemize>
  96 <item>get_ostype
  97 <item>get_tv
  98 <item>_gtia_mkcolor
  99 <item>_getcolor
 100 <item>_getdefdev
 101 <item>_graphics
 102 <item>_rest_vecs
 103 <item>_save_vecs
 104 <item>_scroll
 105 <item>_setcolor
 106 <item>_setcolor_low
 107 </itemize>
 108
 109
 110 <sect1>Hardware access<p>
 111
 112 The following pseudo variables declared in the <tt/atari.h/ header
 113 file do allow access to hardware located in the address space. Some
 114 variables are structures, accessing the struct fields will access the
 115 chip registers.
 116
 117 <descrip>
 118
 119   <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
 120   The <tt/GTIA_READ/ structure allows read access to the GTIA. The
 121   <tt/GTIA_WRITE/ structure allows write access to the GTIA.
 122   See the <tt/_gtia.h/ header file located in the include directory
 123   for the declaration of the structure.
 124
 125   <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
 126   The <tt/POKEY_READ/ structure allows read access to the POKEY. The
 127   <tt/POKEY_WRITE/ structure allows write access to the POKEY.
 128   See the <tt/_pokey.h/ header file located in the include directory
 129   for the declaration of the structure.
 130
 131   <tag><tt/ANTIC/</tag>
 132   The <tt/ANTIC/ structure allows read access to the ANTIC.
 133   See the <tt/_antic.h/ header file located in the include directory
 134   for the declaration of the structure.
 135
 136   <tag><tt/PIA/</tag>
 137   The <tt/PIA/ structure allows read access to the PIA 6520.
 138   See the <tt/_pia.h/ header file located in the include directory
 139   for the declaration of the structure.
 140
 141 </descrip><p>
 142
 143
 144
 145 <sect>Loadable drivers<p>
 146
 147 <sect1>Graphics drivers<p>
 148
 149 Currently there are no graphics drivers available for the Atari platform.
 150
 151 <sect1>Extended memory drivers<p>
 152
 153 Currently there are no extended memory drivers available for the Atari
 154 platform.
 155
 156 <sect1>Joystick drivers<p>
 157
 158 <descrip>
 159
 160   <tag><tt/atari-stdjoy.joy/</tag>
 161   Supports up to four standard joysticks connected to the joystick ports of
 162   the Atari.
 163
 164 </descrip><p>
 165
 166
 167
 168 <sect1>Mouse drivers<p>
 169
 170 Currently no drivers available (in fact, the API for loadable mouse drivers
 171 does not exist). There is a static driver you can use.
 172
 173
 174 <sect1>RS232 device drivers<p>
 175
 176 Currently there are no RS232 loadable drivers available for the Atari
 177 platform. There is a static driver you can use.
 178
 179
 180 <sect>Limitations<p>
 181
 182
 183
 184 <sect>Other hints<p>
 185
 186 <sect1>Function keys<p>
 187
 188 These are defined to be Atari + number key.
 189
 190
 191
 192 <sect>Bugs/Feedback<p>
 193
 194 If you have problems using the library, if you find any bugs, or if you're
 195 doing something interesting with it, I would be glad to hear from you. Feel
 196 free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
 197 name="uz@cc65.org">).
 198
 199
 200
 201 <sect>License<p>
 202
 203 This software is provided 'as-is', without any expressed or implied
 204 warranty.  In no event will the authors be held liable for any damages
 205 arising from the use of this software.
 206
 207 Permission is granted to anyone to use this software for any purpose,
 208 including commercial applications, and to alter it and redistribute it
 209 freely, subject to the following restrictions:
 210
 211 <enum>
 212 <item>  The origin of this software must not be misrepresented; you must not
 213         claim that you wrote the original software. If you use this software
 214         in a product, an acknowledgment in the product documentation would be
 215         appreciated but is not required.
 216 <item>  Altered source versions must be plainly marked as such, and must not
 217         be misrepresented as being the original software.
 218 <item>  This notice may not be removed or altered from any source
 219         distribution.
 220 </enum>
 221
 222 </article>