Replace hard returns with an "else", add an error for non-IDENT tokens, and test...

[cc65] / doc / atari.sgml

diff --git a/doc/atari.sgml b/doc/atari.sgml
index 346377b36493519e48a5ff477de9253ae1d818e1..eecd1b803e913eaa89b48b8e751ac61a5fb4b63b 100644 (file)
--- a/doc/atari.sgml
+++ b/doc/atari.sgml
@@ -203,7 +203,7 @@ is <it/left out/, keep this in mind.
 The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
 don't matter.
 
 The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
 don't matter.
 

-<sect2><tt/atari-xex.cfg/<p>
+<sect2><tt/atari-asm-xex.cfg/<p>

 
 This config file allows writing multi segment binaries easily, without having to
 write the header explicitly on each segment.
 
 This config file allows writing multi segment binaries easily, without having to
 write the header explicitly on each segment.


@@ -213,7 +213,8 @@ format support on LD65 instead of the standard binary output, so it does not
 have the <tt/__AUTOSTART/ nor the <tt/__EXEHDR__/ symbols.
 
 Note that each <tt/MEMORY/ area in the configuration file will have it's own
 have the <tt/__AUTOSTART/ nor the <tt/__EXEHDR__/ symbols.
 
 Note that each <tt/MEMORY/ area in the configuration file will have it's own

-segment in the output file with the correct headers.
+segment in the output file with the correct headers, and you can specify and
+init address INITAD) for each memory area.

 
 <sect2><tt/atari-cart.cfg/<p>
 
 
 <sect2><tt/atari-cart.cfg/<p>
 


@@ -242,6 +243,18 @@ 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 (<tt/w2cas.com/) to run
 on an Atari is provided in the <tt/util/ directory of <tt/atari/ target dir.
 
 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.
 

+<sect2><tt/atari-xex.cfg/<p>
+
+This config file shows how to write a binary using the ATARI (xex) file format
+support on LD65, this simplifies the memory areas and allows to add new memory
+areas easily without writing new headers and trailers.
+
+Note that the default C library includes the system-check chunk, so in this
+linker configuration we suppress the importing of the header and trailer for
+this chunk by defining the standard import symbols to a 0 value. For the
+initialization address of the system-check chunk, the INITAD is set directly in
+the configuration.
+

 <sect1><tt/atarixl/ config files<p>
 
 <sect2>default config file (<tt/atarixl.cfg/)<p>
 <sect1><tt/atarixl/ config files<p>
 
 <sect2>default config file (<tt/atarixl.cfg/)<p>


@@ -265,12 +278,40 @@ The files generated by this config file include the
 <ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
 
 <ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
 

+<sect2><tt/atarixl-xex.cfg/<p>
+
+Similar to the <tt/atari-xex.cfg/ above, this config file shows how to write a
+binary using the ATARI (xex) file format support on LD65.
+
+In addition to the suppressing of the system-check headers and trailers, this
+also suppresses the shadow-ram-preparation headers and trailers, but does this
+by defining an "UNUSED" memory area that is not written to the output file.
+

 
 <sect>Platform specific header files<p>
 
 Programs containing Atari specific code may use the <tt/atari.h/
 header file.
 
 
 <sect>Platform specific header files<p>
 
 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>
 
 
 <sect1>Atari specific functions<p>
 


@@ -335,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:
 
 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];
 
 ...
 unsigned char ScreenMemory[100];
 


@@ -351,12 +392,13 @@ void DisplayList =
     DL_CHR20x8x2,
     DL_BLK4,
     DL_CHR20x8x2,
     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
 
 Please inspect the <tt/_antic.h/ header file to detemine the supported
 instruction names. Modifiers on instructions can be nested without need


@@ -403,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:
 
 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!";
 #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
 
 
 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!";
 #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.
 
 
 does not.
 


@@ -429,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:
 all keyboard codes are available as defined values on C and assembler side.
 
 Example:

-<verb>
+<tscreen><verb>

 ...
     while (!kbhit());
 ...
     while (!kbhit());

-    switch (PEEK(764))
+    switch (OS.ch)

     {
         case KEY_RETURN:
         ...
     {
         case KEY_RETURN:
         ...


@@ -442,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.
 
 
 You can find the C defines in the file "<tt/atari.h/" or "<tt/atari.inc/" for the assembler variant.