X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fatari.sgml;h=346377b36493519e48a5ff477de9253ae1d818e1;hb=e767c8990d07003d9c91a6151cc61f0ea28639ea;hp=a0dbe2f471a4f9c84cdcc99cc8f8ce96071d7869;hpb=3531bcbf3e3aac04b8967949bcc77e8e13395418;p=cc65 diff --git a/doc/atari.sgml b/doc/atari.sgml index a0dbe2f47..346377b36 100644 --- a/doc/atari.sgml +++ b/doc/atari.sgml @@ -1,12 +1,10 @@
- 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 @@ -31,7 +29,7 @@ supports XL type or newer machines (excluding the 600XL). 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. @@ -205,6 +203,18 @@ is <it/left out/, keep this in mind. The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/ don't matter. +<sect2><tt/atari-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. + <sect2><tt/atari-cart.cfg/<p> This config file can be used to create 8K or 16K cartridges. It's suited both @@ -317,6 +327,49 @@ 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)&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> @@ -351,7 +404,7 @@ under different mappings, defining remapped strings works only flawlessly with static array initialization: <verb> -#include <atari\_screen\_charmap.h> +#include <atari_screen_charmap.h> char pcScreenMappingString[] = "Hello Atari!"; #include <atari_atascii_charmap.h> @@ -370,6 +423,29 @@ char* pcAtasciiMappingString = "Hello Atari!"; 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> @@ -570,7 +646,18 @@ interface module. <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 @@ -891,16 +978,16 @@ chunk #2 (RAM memory area). 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 @@ -967,16 +1054,16 @@ FEATURES { 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 @@ -1007,7 +1094,7 @@ If you are using a customized linker config file you might get some errors 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 @@ -1055,14 +1142,14 @@ including commercial applications, and to alter it and redistribute it 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>