<!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-10
<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.
($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 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 to run
-on an Atari is provided in the <tt/targetutil/ directory (<tt/w2cas.com/).
+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>
<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>
<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)/.
<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.
<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
<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>
<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