Update atari.sgml

[cc65] / doc / atari.sgml

diff --git a/doc/atari.sgml b/doc/atari.sgml
index f37b43929a6fca199c2579f99b32185b5a553007..6cbff6208abe5e2711a6b8546625c36fc79ce383 100644 (file)
--- a/doc/atari.sgml
+++ b/doc/atari.sgml
@@ -148,7 +148,7 @@ Special locations:
   ($58).
 
   <tag/Stack/
-  The C runtime stack is located at end of the RAM memory area (&dollar;CFFF)
+  The C runtime stack is located at end of the MAIN memory area (&dollar;CFFF)
   and grows downwards.
 
   <tag/Heap/
@@ -229,8 +229,8 @@ for C and assembly language programs.
 The size of a cassette boot file is restricted to 32K. Larger programs
 would need to be split in more parts and the parts to be loaded manually.
 
-To write the generated file to a cassette, a utility to run
-on an Atari is provided in the <tt/targetutil/ directory (<tt/w2cas.com/).
+To write the generated file to a cassette, a utility (<tt/w2cas.com/) to run
+on an Atari is provided in the <tt/util/ directory of <tt/atari/ target dir.
 
 <sect1><tt/atarixl/ config files<p>
 
@@ -275,6 +275,7 @@ See the <url url="funcref.html" name="function reference"> for declaration and u
 <item>_getcolor
 <item>_getdefdev
 <item>_graphics
+<item>_is_cmdline_dos
 <item>_rest_vecs
 <item>_save_vecs
 <item>_scroll
@@ -316,6 +317,101 @@ chip registers.
 
 </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)&amp;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>
+
+The Atari has two representations for characters:
+<enum>
+<item> ATASCII is character mapping which is similar to ASCII and used
+by the CIO system of the OS. This is the default mapping of cc65 when
+producing code for the atari target.
+<item> The internal/screen mapping represents the real value of the
+screen ram when showing a character.
+</enum>
+
+For direct memory access (simplicity and speed) enabling the internal
+mapping can be useful. This can be achieved by including the
+"<tt/atari_screen_charmap.h/" header.
+
+A word of caution: Since the <tt/0x00/ character has to be mapped in an
+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 (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/"
+package delivers the same feature.</em>
+
+You can switch back to the ATASCII mapping by including
+"<tt/atari_atascii_charmap.h/".
+
+A final note: Since cc65 has currently some difficulties with string merging
+under different mappings, defining remapped strings works only flawlessly
+with static array initialization:
+
+<verb>
+#include &lt;atari\_screen\_charmap.h&gt;
+char pcScreenMappingString[] = "Hello Atari!";
+
+#include &lt;atari_atascii_charmap.h&gt;
+char pcAtasciiMappingString[] = "Hello Atari!";
+</verb>
+
+delivers correct results, while
+
+<verb>
+#include &lt;atari_screen_charmap.h&gt;
+char* pcScreenMappingString = "Hello Atari!";
+
+#include &lt;atari_atascii_charmap.h&gt;
+char* pcAtasciiMappingString = "Hello Atari!";
+</verb>
+
+does not.
 
 
 <sect>Loadable drivers<p>
@@ -561,7 +657,7 @@ The contents of this chunk come from the SYSCHKCHNK memory area of the linker co
 <item>main program&nl;
 This load chunk is loaded at the selected program start address (default &dollar;2000) and
 contains all of the code and data of the program.&nl;
-The contents of this chunk come from the RAM memory area of the linker config file.
+The contents of this chunk come from the MAIN memory area of the linker config file.
 </enum>