X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fatari.sgml;h=1affc8362a049e171245427973a072ad68edb931;hb=f94a125f30e561419fb731635403aa7b103b0c00;hp=e65a7869e3d26a766df6f61b9fe49d976fd659d5;hpb=89329f1519d167684a2802e32cd929e74d3ea7f3;p=cc65 diff --git a/doc/atari.sgml b/doc/atari.sgml index e65a7869e..1affc8362 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,19 @@ 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-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 @@ -232,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. +<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> @@ -255,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">. +<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: + +<verb> +... + OS.savmsc = ScreenMemory; + OS.color4 = 14; // white frame + if (OS.stick0 != 15 || OS.ch != 255) // key or stick input? +... +</verb> + +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> @@ -317,6 +368,125 @@ 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, + &DisplayList +}; +... +OS.sdlst = &DisplayList; +... +</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 <atari_screen_charmap.h> +char pcScreenMappingString[] = "Hello Atari!"; + +#include <atari_atascii_charmap.h> +char pcAtasciiMappingString[] = "Hello Atari!"; +</verb> + +delivers correct results, while + +<verb> +#include <atari_screen_charmap.h> +char* pcScreenMappingString = "Hello Atari!"; + +#include <atari_atascii_charmap.h> +char* pcAtasciiMappingString = "Hello Atari!"; +</verb> + +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 (OS.ch) + { + 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> @@ -518,7 +688,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 @@ -839,16 +1020,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 @@ -915,16 +1096,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 @@ -955,7 +1136,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 @@ -1003,14 +1184,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>