<!doctype linuxdoc system>
<article>
-
<title>Atari specific information for cc65
-<author>Shawn Jefferson, <htmlurl
-url="mailto:shawnjefferson@24fightingchickens.com"
-name="shawnjefferson@24fightingchickens.com"> and
-Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org">
-<date>03-Jan-2006
+<author>
+<url url="mailto:shawnjefferson@24fightingchickens.com" name="Shawn Jefferson"> and<newline>
+<url url="mailto:chris@groessler.org" name="Christian Groessler">
<abstract>
An overview over the Atari runtime system as it is implemented for the cc65 C
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 - $D7FFF. Since the
-<tt/atarixl/ runtime has some <ref name="limitations" id="limitations">, it is
+exception of the I/O area at $D000 - $D7FF. Since the
+<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.
Please note that Atari specific functions are just mentioned here, they are
-described in detail in the separate <htmlurl url="funcref.html" name="function
+described in detail in the separate <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
sufficient to know that the first load chunk(s) do preparation work and the
main part of the program is in the last load chunk.
-The values determining the size of the main part of the program (the only load
+The values determining the size of the main part of the program (the second load
chunk for <tt/atari/, the third load chunk for <tt/atarixl/) are calculated in
the crt0.s file from the __STARTUP_LOAD__ and __BSS_LOAD__ values.
Be aware of that if you create a custom linker config file and start moving segments around (see section
</enum>
With the default load address of $2400 this gives a usable memory range of
-[$2400-$CFFF]. Note that the default load address for <tt/atarixl/ is
-different (and lower) that the default load address for <tt/atari/. This is no problem since
-on the <tt/atarixl/ target the first load chunk makes sure that the loaded prgram won't overwrite
-memory below MEMLO. See <ref name="atarixl load chunks" id="xlchunks">.
+[$2400-$CFFF].
+Please note that the first load chunk (which checks the system
+compatibilty and available memory) will always be loaded at
+$2E00, regardless of the specified start address. This address
+can only be changed by a custom linker config file.
Special locations:
($58).
<tag/Stack/
- The C runtime stack is located at end of the RAM memory area ($CFFF)
+ The C runtime stack is located at end of the MAIN memory area ($CFFF)
and grows downwards.
<tag/Heap/
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
The option byte will be located at address $BFFD. For more information
about its use, see e.g. "Mapping the Atari".
+<sect2><tt/atari-cassette.cfg/<p>
+
+This config file can be used to create cassette boot files. It's suited both
+for C and assembly language programs.
+
+The size of a cassette boot file is restricted to 32K. Larger programs
+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>
<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>
The functions and global variable listed below are special for the Atari.
-See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage.
+See the <url url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>get_ostype
<item>_getcolor
<item>_getdefdev
<item>_graphics
+<item>_is_cmdline_dos
<item>_rest_vecs
<item>_save_vecs
<item>_scroll
</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>
it doesn't have at least one byte available. This seems to be a bug of
the Atari ROM code.
+Default drivers: <tt/atr8.tgi (atr8_tgi)/ and <tt/atrx8.tgi (atrx8_tgi)/.
+
<sect1>Extended memory drivers<p>
Currently there is only one extended memory driver. It manages the second 64K of a 130XE.
<tt/atrstd.joy (atrstd_joy)/|<tt/atrxstd.joy (atrxstd_joy)/|Supports up to two/four standard joysticks connected to the joystick ports of the Atari. (Four on the pre-XL systems, two on XL or newer.)@
<tt/atrmj8.joy (atrmj8_joy)/|<tt/atrxmj8.joy (atrxmj8_joy)/|Supports up to eight standard joysticks connected to a MultiJoy adapter.
</tabular>
-<caption>
</table>
+Default drivers: <tt/atrstd.joy (atrstd_joy)/ and <tt/atrxstd.joy (atrxstd_joy)/.
<sect1>Mouse drivers<p>
<tt/atrtrk.mou (atrtrk_mou)/|<tt/atrxtrk.mou (atrxtrk_mou)/|Supports an Atari trakball.@
<tt/atrtt.mou (atrtt_mou)/|<tt/atrxtt.mou (atrxtt_mou)/|Supports an Atari touch tablet.
</tabular>
-<caption>
</table>
All mouse devices connect to joystick port #0.
+Default drivers: <tt/atrst.mou (atrst_mou)/ and <tt/atrxst.mou (atrxst_mou)/.
+
+<sect2>Mouse callbacks<p>
+
+There are two mouse callbacks available.
+<p>
+The "text mode" callbacks (<tt/mouse_txt_callbacks/) display the mouse cursor as a "diamond" character
+on the standard "GRAPHICS 0" text mode screen. The mouse cursor character can be changed by an
+assembly file defining the character by exporting the zeropage symbol <tt/mouse_txt_char/.
+The default file looks like this:
+<tscreen><verb>
+ .export mouse_txt_char : zp = 96 ; 'diamond' screen code
+</verb></tscreen>
+<p>
+The "P/M" callbacks (<tt/mouse_pm_callbacks/) use Player-Missile graphics for the mouse cursor.
+The cursor shape can be changed, too, by an assembly file. Here's the default shape definition:
+<tscreen><verb>
+ .export mouse_pm_bits
+ .export mouse_pm_height : zeropage
+ .export mouse_pm_hotspot_x : zeropage
+ .export mouse_pm_hotspot_y : zeropage
+ .rodata
+mouse_pm_bits:
+ .byte %11110000
+ .byte %11000000
+ .byte %10100000
+ .byte %10010000
+ .byte %10001000
+ .byte %00000100
+ .byte %00000010
+mouse_pm_height = * - mouse_pm_bits
+; hot spot is upper left corner
+mouse_pm_hotspot_x = 0
+mouse_pm_hotspot_y = 0
+</verb></tscreen>
+<p>
+<tt/mouse_pm_bits/ defines the shape of the cursor, <tt/mouse_pm_height/ defines the number of
+bytes in <tt/mouse_pm_bits/. <tt/mouse_pm_hotspot_x/ and <tt/mouse_pm_hotspot_y/ define the
+position in the shape where "the mouse points to". When using this callback page #6 ($600
+ - $6FF) is used for the P/M graphics data and no P/M graphics can otherwise be used
+by the program. The height of the shape (<tt/mouse_pm_height/)
+must not exceed 32 lines since the callback routines cannot handle more than 32 lines.
+<p>
+The default callbacks definition (<tt/mouse_def_callbacks/) is an alias for the "P/M" callbacks.
<sect1>RS232 device drivers<p>
<sect>Limitations<p>
-<sect1><tt/atarixl/<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
<sect>Technical details<label id="techdetail"><p>
-<sect1><tt/atari/<p>
+<sect1><tt/atari/<#if output="info|latex2e"> details</#if><p>
-<sect2>Load chunks<p>
+<sect2>
<#if output="info|latex2e"><tt/atari/ </#if>Load chunks<p>
An <tt/atari/ program contains two load chunks.
<item>main program&nl;
This load chunk is loaded at the selected program start address (default $2000) and
contains all of the code and data of the program.&nl;
-The contents of this chunk come from the RAM memory area of the linker config file.
+The contents of this chunk come from the MAIN memory area of the linker config file.
</enum>
-<sect1><tt/atarixl/<p>
+<sect1><tt/atarixl/<#if output="info|latex2e"> details</#if><p>
<sect2>General operation<p>
For ROM functions which require input or output buffers, the wrappers
copy the data as required to buffers in low memory.
-<sect2>Load chunks<label id="xlchunks"><p>
+<sect2>
<#if output="info|latex2e"><tt/atarixl/ </#if>Load chunks<label id="xlchunks"><p>
An <tt/atarixl/ program contains three load chunks.
<sect1>Passing arguments to the program<p>
-Command line arguments can be passed to <tt/main()/ when DOS supports it.
+Command line arguments can be passed to <tt/main()/ when the used DOS supports it.
<enum>
<item>Arguments are separated by spaces.
<item>Leading and trailing spaces around an argument are ignored.
<item>The first argument passed to <tt/main/ is the program name.
<item>A maximum number of 16 arguments (including the program name) are
- supported.
+ supported.
</enum>
interrupt handlers. Such routines must be written as simple machine language
subroutines and will be called automatically by the VBI handler code
when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
+feature in the <url url="ca65.html" name="assembler manual">.
+Please note that on the Atari targets the <tt/.INTERRUPTOR/s are being
+run in NMI context. The other targets run them in IRQ context.
<sect1>Reserving a memory area inside a program<label id="memhole"><p>
<p>
The main problem is that the EXE header generated by the cc65 runtime
lib is wrong. It defines a single load chunk with the sizes/addresses
-of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments, in
+of the STARTUP, LOWCODE, ONCE, CODE, RODATA, and DATA segments, in
fact, the whole user program (we're disregarding the "system check"
load chunk here).
<p>
NEXEHDR: load = FSTHDR, type = ro; # first load chunk
STARTUP: load = RAMLO, type = ro, define = yes;
LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes;
- INIT: load = RAMLO, type = ro, optional = yes;
+ ONCE: load = RAMLO, type = ro, optional = yes;
CODE: load = RAMLO, type = ro, define = yes;
CHKHDR: load = SECHDR, type = ro; # second load chunk
AUTOSTRT: load = RAM, type = ro; # defines program entry point
}
FEATURES {
- CONDES: segment = RODATA,
+ CONDES: segment = ONCE,
type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__;
<p>
The newly added NEXEHDR segment defines the correct chunk header for the
first intended load chunk. It
-puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the
+puts the STARTUP, LOWCODE, ONCE, and CODE segments, which are the
segments containing only code, into load chunk #1 (RAMLO memory area).
<p>
The header for the second load chunk comes from the new CHKHDR
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
<sect2>Low data and high code example<p>
-Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT,
+Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, ONCE,
CODE, BSS, ZPSAVE into high memory (split2.cfg):
<tscreen><verb>
CHKHDR: load = SECHDR, type = ro; # second load chunk
STARTUP: load = RAM, type = ro, define = yes;
- INIT: load = RAM, type = ro, optional = yes;
+ ONCE: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro, define = yes;
BSS: load = RAM, type = bss, define = yes;
AUTOSTRT: load = RAM, type = ro; # defines program entry point
}
FEATURES {
- CONDES: segment = RODATA,
+ CONDES: segment = ONCE,
type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__;
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