<!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.
The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
don't matter.
+<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.
+
+It is similar to the <tt/atari-asm.cfg/ above, but uses the ATARI (xex) file
+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
+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>
This config file can be used to create 8K or 16K cartridges. It's suited both
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>
<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.
+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>Display lists<p>
-An major feature of the Atari graphics chip "ANTIC" is to
+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>
+<tscreen><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
+ DL_BLK8,
+ DL_BLK8,
+ DL_BLK8,
+ DL_LMS(DL_CHR20x8x2),
+ ScreenMemory,
+ DL_CHR20x8x2,
+ DL_CHR20x8x2,
+ DL_CHR20x8x2,
+ DL_BLK4,
+ DL_CHR20x8x2,
+ DL_JVB,
+ &DisplayList
};
...
-POKEW(560,(unsigned int)&DisplayList); // SDLSTL
+OS.sdlst = &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
under different mappings, defining remapped strings works only flawlessly
with static array initialization:
-<verb>
-#include <atari\_screen\_charmap.h>
+<tscreen><verb>
+#include <atari_screen_charmap.h>
char pcScreenMappingString[] = "Hello Atari!";
#include <atari_atascii_charmap.h>
char pcAtasciiMappingString[] = "Hello Atari!";
-</verb>
+</verb></tscreen>
delivers correct results, while
-<verb>
+<tscreen><verb>
#include <atari_screen_charmap.h>
char* pcScreenMappingString = "Hello Atari!";
#include <atari_atascii_charmap.h>
char* pcAtasciiMappingString = "Hello Atari!";
-</verb>
+</verb></tscreen>
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:
+<tscreen><verb>
+...
+ while (!kbhit());
+ switch (OS.ch)
+ {
+ case KEY_RETURN:
+ ...
+ case KEY_SPACE:
+ ...
+ case KEY_1:
+ ...
+ }
+...
+</verb></tscreen>
+
+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
regarding the MAINHDR segment. Like this:
<tscreen><verb>
-ld65: Error: Missing memory area assignment for segment `MAINHDR'
+ld65: Error: Missing memory area assignment for segment 'MAINHDR'
</verb></tscreen>
The old "HEADER" memory description contained six bytes: $FFFF
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>
projects / cc65 / blobdiff