Moved documentation to funcref.

[cc65] / doc / atari.sgml

diff --git a/doc/atari.sgml b/doc/atari.sgml
index 42b06d83eaef09ebe369bb3874667ba5cef85e88..eecd1b803e913eaa89b48b8e751ac61a5fb4b63b 100644 (file)
--- a/doc/atari.sgml
+++ b/doc/atari.sgml
@@ -293,6 +293,25 @@ by defining an "UNUSED" memory area that is not written to the output file.
 Programs containing Atari specific code may use the <tt/atari.h/
 header file.
 
+This also includes access to operating system locations (e.g. hardware shadow registers) by a structure called
+"<tt/OS/".
+The names are the usual ones you can find in system reference manuals. Example:
+
+<tscreen><verb>
+...
+    OS.savmsc = ScreenMemory;
+    OS.color4 = 14;                         // white frame
+    if (OS.stick0 != 15 || OS.ch != 255)    // key or stick input?
+...
+</verb></tscreen>
+
+Please note that memory location 762/$2FA is called "<tt/char_/" while the orignal name "<tt/char/" conflicts with the C keyword.
+
+If you like to use the OS names and locations for the original Atari 800 operating system, please "<tt/#define OSA/" before including the
+<tt/atari.h/ header file.
+If you like to target the floating point register model of revision 2 machines, put a "<tt/#define OS_REV2/" before including <tt/atari.h/.
+
+Access to the Basic programming language zero page variables is established by the structure "<tt/BASIC/".
 
 <sect1>Atari specific functions<p>
 
@@ -357,7 +376,7 @@ 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>
+<tscreen><verb>
 ...
 unsigned char ScreenMemory[100];
 
@@ -373,12 +392,13 @@ void DisplayList =
     DL_CHR20x8x2,
     DL_BLK4,
     DL_CHR20x8x2,
-    DL_JVB
+    DL_JVB,
+    &amp;DisplayList
 };
 ...
-POKEW(560,(unsigned int)&amp;DisplayList);      // SDLSTL
+OS.sdlst = &amp;DisplayList;
 ...
-</verb>
+</verb></tscreen>
 
 Please inspect the <tt/_antic.h/ header file to detemine the supported
 instruction names. Modifiers on instructions can be nested without need
@@ -425,23 +445,23 @@ 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>
+<tscreen><verb>
 #include &lt;atari_screen_charmap.h&gt;
 char pcScreenMappingString[] = "Hello Atari!";
 
 #include &lt;atari_atascii_charmap.h&gt;
 char pcAtasciiMappingString[] = "Hello Atari!";
-</verb>
+</verb></tscreen>
 
 delivers correct results, while
 
-<verb>
+<tscreen><verb>
 #include &lt;atari_screen_charmap.h&gt;
 char* pcScreenMappingString = "Hello Atari!";
 
 #include &lt;atari_atascii_charmap.h&gt;
 char* pcAtasciiMappingString = "Hello Atari!";
-</verb>
+</verb></tscreen>
 
 does not.
 
@@ -451,10 +471,10 @@ For direct keyboard scanning in conjunction with e.g. the OS location "CH" (764/
 all keyboard codes are available as defined values on C and assembler side.
 
 Example:
-<verb>
+<tscreen><verb>
 ...
     while (!kbhit());
-    switch (PEEK(764))
+    switch (OS.ch)
     {
         case KEY_RETURN:
         ...
@@ -464,7 +484,7 @@ Example:
         ...
     }
 ...
-</verb>
+</verb></tscreen>
 
 You can find the C defines in the file "<tt/atari.h/" or "<tt/atari.inc/" for the assembler variant.