<!doctype linuxdoc system>
<article>
-
<title>Atari specific information for cc65
<author>
<url url="mailto:shawnjefferson@24fightingchickens.com" name="Shawn Jefferson"> and<newline>
<url url="mailto:chris@groessler.org" name="Christian Groessler">
-<date>2014-04-24
<abstract>
An overview over the Atari runtime system as it is implemented for the cc65 C
The <tt/atarixl/ runtime makes the whole 64K of memory available, with the
exception of the I/O area at $D000 - $D7FF. Since the
-<tt/atarixl/ runtime has some <ref name="limitations" id="limitations">, it is
+<tt/atarixl/ runtime has some <ref name="limitations" id="xllimitations">, it is
recommended to use the <tt/atari/ target unless lack of memory dictates the
use of the <tt/atarixl/ target.
</descrip><p>
+<sect1>Display lists<p>
+
+A major feature of the Atari graphics chip "ANTIC" is to
+process instructions for the display generation.
+cc65 supports constructing these display lists by offering defines
+for the instructions. In conjunction with the "void"-variable extension
+of cc65, display lists can be created quite comfortable:
+
+<verb>
+...
+unsigned char ScreenMemory[100];
+
+void DisplayList =
+{
+ DL_BLK8,
+ DL_BLK8,
+ DL_BLK8,
+ DL_LMS(DL_CHR20x8x2),
+ ScreenMemory,
+ DL_CHR20x8x2,
+ DL_CHR20x8x2,
+ DL_CHR20x8x2,
+ DL_BLK4,
+ DL_CHR20x8x2,
+ DL_JVB
+};
+...
+POKEW(560,(unsigned int)&DisplayList); // SDLSTL
+...
+</verb>
+
+Please inspect the <tt/_antic.h/ header file to detemine the supported
+instruction names. Modifiers on instructions can be nested without need
+for an order:
+
+<tt/DL_LMS(DL_HSCROL(DL_VSCROL(DL_DLI(DL_MAP80x4x2))))/
+
+Please mind that ANTIC has memory alignment requirements for "player
+missile graphics"-data, font data, display lists and screen memory. Creation
+of a special linker configuration with appropriate aligned segments and
+switching to that segment in the c-code is usually neccessary. A more memory
+hungry solution consists in using the "<tt/posix_memalign()/" function in
+conjunction with copying your data to the allocated memory.
<sect1>Character mapping<p>
incompatible way to the C-standard, the usage of string functions in
conjunction with internal character mapped strings delivers unexpected
results regarding the string length. The end of strings are detected where
-you may not expect them (to early or (much) to late). Internal mapped
+you may not expect them (too early or (much) too late). Internal mapped
strings typically support the "<tt/mem...()/" functions.
<em>For assembler sources the macro "<tt/scrcode/" from the "<tt/atari.mac/"
with static array initialization:
<verb>
-#include <atari\_screen\_charmap.h>
+#include <atari_screen_charmap.h>
char pcScreenMappingString[] = "Hello Atari!";
#include <atari_atascii_charmap.h>
does not.
+<sect1>Keyboard codes<p>
+
+For direct keyboard scanning in conjunction with e.g. the OS location "CH" (764/$2FC),
+all keyboard codes are available as defined values on C and assembler side.
+
+Example:
+<verb>
+...
+ while (!kbhit());
+ switch (PEEK(764))
+ {
+ case KEY_RETURN:
+ ...
+ case KEY_SPACE:
+ ...
+ case KEY_1:
+ ...
+ }
+...
+</verb>
+
+You can find the C defines in the file "<tt/atari.h/" or "<tt/atari.inc/" for the assembler variant.
+
<sect>Loadable drivers<p>
<sect>Limitations<p>
-<sect1><tt/atarixl/<#if output="info|latex2e"> limitations</#if><label id="limitations"<p>
+<sect1><tt/Realtime clock/<label id="realtimeclock"<p>
+
+Access to the realtime clock is supported only when running on SpartaDOS-X.
+There needs to be a realtime clock driver installed. This is normally the case
+in the default installation (CONFIG.SYS) of SpartaDOS-X.
+A missing realtime clock driver in SpartaDOS-X is not supported, and the program
+may crash when calling the <tt/clock_settime()/ or <tt/clock_gettime()/
+functions.
+
+The resolution of the realtime clock driver is 1 second.
+
+<sect1><tt/atarixl target/<#if output="info|latex2e"> limitations</#if><label id="xllimitations"<p>
<itemize>
<item>The display is cleared at program start and at program termination. This is a side
The contents of the new NEXEHDR and CHKHDR segments come from this
file (split.s):
<tscreen><verb>
- .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
- .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
+ .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
+ .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
- .segment "NEXEHDR"
- .word __STARTUP_LOAD__
- .word __CODE_LOAD__ + __CODE_SIZE__ - 1
+ .segment "NEXEHDR"
+ .word __STARTUP_LOAD__
+ .word __CODE_LOAD__ + __CODE_SIZE__ - 1
- .segment "CHKHDR"
- .word __RODATA_LOAD__
- .word __BSS_LOAD__ - 1
+ .segment "CHKHDR"
+ .word __RODATA_LOAD__
+ .word __BSS_LOAD__ - 1
</verb></tscreen>
<p>
Compile with
New contents for NEXEHDR and CHKHDR are needed (split2.s):
<tscreen><verb>
- .import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__
- .import __DATA_LOAD__, __RODATA_LOAD__
+ .import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__
+ .import __DATA_LOAD__, __RODATA_LOAD__
- .segment "NEXEHDR"
- .word __RODATA_LOAD__
- .word __DATA_LOAD__ + __DATA_SIZE__ - 1
+ .segment "NEXEHDR"
+ .word __RODATA_LOAD__
+ .word __DATA_LOAD__ + __DATA_SIZE__ - 1
- .segment "CHKHDR"
- .word __STARTUP_LOAD__
- .word __BSS_LOAD__ - 1
+ .segment "CHKHDR"
+ .word __STARTUP_LOAD__
+ .word __BSS_LOAD__ - 1
</verb></tscreen>
Compile with
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.
+<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>