1 <!doctype linuxdoc system>
4 <title>Atari specific information for cc65
6 <url url="mailto:shawnjefferson@24fightingchickens.com" name="Shawn Jefferson"> and<newline>
7 <url url="mailto:chris@groessler.org" name="Christian Groessler">
10 An overview over the Atari runtime system as it is implemented for the cc65 C
14 <!-- Table of contents -->
17 <!-- Begin the document -->
21 This file contains an overview of the Atari runtime system as it comes
22 with the cc65 C compiler. It describes the memory layout, Atari specific
23 header files, available drivers, and any pitfalls specific to that
26 The Atari runtime support comes in two flavors: <tt/atari/ and <tt/atarixl/.
27 The <tt/atari/ target supports all Atari 8-bit computers, the <tt/atarixl/ only
28 supports XL type or newer machines (excluding the 600XL).
30 The <tt/atarixl/ runtime makes the whole 64K of memory available, with the
31 exception of the I/O area at $D000 - $D7FF. Since the
32 <tt/atarixl/ runtime has some <ref name="limitations" id="xllimitations">, it is
33 recommended to use the <tt/atari/ target unless lack of memory dictates the
34 use of the <tt/atarixl/ target.
36 Please note that Atari specific functions are just mentioned here, they are
37 described in detail in the separate <url url="funcref.html" name="function
38 reference">. Even functions marked as "platform dependent" may be available on
39 more than one platform. Please see the function reference for more
43 <sect>Binary format<p>
45 The Atari DOS executable file format supports more than one load block (<it/chunk/).
47 The default binary output format generated by the linker for the
48 Atari target is a machine language program with a standard executable
49 header (FF FF <load chunk #1> ... <load chunk #n>).
50 A load chunk has the format [<2 byte start address> <2 bytes end address>
51 <chunk data>].
52 A run vector is added to the end of the
53 file ($02E0 $02E1 <run vector>) and is calculated using
54 the <tt/start/ label in crt0.s. (Technically the run vector is also a load chunk,
55 but is not regarded as such here.)
57 An <tt/atari/ program has two load chunks, an <tt/atarixl/ program has three load
58 chunks. The load chunks are defined in the linker configuration files. For more
59 detailed information about the load chunks see the chapter
60 <ref name="Technical details" id="techdetail">. For the discussion here it's
61 sufficient to know that the first load chunk(s) do preparation work and the
62 main part of the program is in the last load chunk.
64 The values determining the size of the main part of the program (the second load
65 chunk for <tt/atari/, the third load chunk for <tt/atarixl/) are calculated in
66 the crt0.s file from the __STARTUP_LOAD__ and __BSS_LOAD__ values.
67 Be aware of that if you create a custom linker config file and start moving segments around (see section
68 <ref name="Reserving a memory area inside the program" id="memhole">).
71 <sect>Memory layout<p>
73 <sect1><tt/atari/ target<p>
75 The default linker config file assumes that the BASIC ROM is disabled (or
76 the BASIC cartridge unplugged). This gives a usable memory range of
77 [$2000-$BC1F]. The library startup code examines the
78 current memory configuration, which depends on the size of the
79 installed memory and cartridges. It does so by using the value in
80 the MEMTOP ($2E5) variable as highest memory address the program
81 can use. The initial stack pointer, which is the upper bound of
82 memory used by the program, is set to this value, minus an optionally
83 defined __RESERVED_MEMORY__ value.
85 The default load address of $2000 can be changed by creating a custom
86 linker config file or by using the "--start-addr" cl65 command line
87 argument or the "--start-addr" or "-S" ld65 command line arguments.
89 Please note that the first load chunk (which checks the available memory)
90 will always be loaded at $2E00, regardless of the specified start
91 address. This address can only be changed by a custom linker config file.
97 The text screen depends on the installed memory size and cartridges
98 and can be obtained from the SAVMSC variable ($58).
101 The C runtime stack is located at MEMTOP and grows downwards,
102 regardless of how your linker config file is setup. This
103 accommodates the different memory configurations of the Atari
104 machines, as well as having a cartridge installed. You can override
105 this behaviour by writing your own crt0.s file and linking it to
106 your program (see also <ref name="Final note"
107 id="memhole_final_note">).
110 The C heap is located at the end of the program and grows towards the C
115 <sect1><tt/atarixl/ target<p>
117 The startup code rearranges the memory as follows:
120 <item>Sceen memory and display list are moved below the program start address.
121 <item>The ROM is disabled, making the memory in the areas [$C000-$CFFF]
122 and [$D800-$FFF9] available.
123 <item>Character generator data is copied from ROM to the CHARGEN location specified in the
124 linker config file. This is (in the default <tt/atarixl.cfg/ file) at the same address as
125 where it is in ROM ($E000, it can be changed, see <ref name="atarixl chargen location"
126 id="chargenloc">). With the character generator at $E000, there are two upper memory
127 areas available, [$D800-$DFFF] and [$E400-$FFF9].
130 With the default load address of $2400 this gives a usable memory range of
131 [$2400-$CFFF].
133 Please note that the first load chunk (which checks the system
134 compatibilty and available memory) will always be loaded at
135 $2E00, regardless of the specified start address. This address
136 can only be changed by a custom linker config file.
142 The text screen depends on the selected load address ($2400
143 by default), and resides directly before that address, rounded to the next
145 The screen memory's start address can be obtained from the SAVMSC variable
149 The C runtime stack is located at end of the MAIN memory area ($CFFF)
153 The C heap is located at the end of the program (end of BSS segment) and
154 grows towards the C runtime stack.
158 <sect>Linker configurations<p>
160 The ld65 linker comes with default config files for the Atari. There
161 are two targets for the Atari, <tt/atari/ and <tt/atarixl/.
162 The default config file for <tt/atari/ is selected with
163 <tt/-t atari/, and the default config file for <tt/atarixl/ is selected with
165 The Atari package comes with additional secondary linker config files which
166 can be used via <tt/-t atari -C <configfile>/ (for <tt/atari/ target) or
167 <tt/-t atarixl -C <configfile>/ (for <tt/atarixl/ target).
169 <sect1><tt/atari/ config files<p>
171 <sect2>default config file (<tt/atari.cfg/)<p>
173 The default configuration is tailored to C programs. It creates files
174 which have a default load address of $2000.
176 The files generated by this config file include the
177 <ref name="&dquot;system check&dquot;" id="syschk"> load chunk. It can
178 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
180 <sect2><tt/atari-asm.cfg/<p>
182 This config file aims to give the assembler programmer maximum
183 flexibility. All program segments (<tt/CODE/, <tt/DATA/, etc.) are
186 By default it creates regular DOS executable files, which have a default
187 load address of $2E00. It's also possible to generate an image of
188 just the program data without EXE header, load address, or (auto-)start address.
189 To you so, you have to define the symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
190 when linking the program. Therefore, to generate a "plain" binary file, pass the
191 options "<tt/-D__AUTOSTART__=1 -D__EXEHDR__=1/" to the linker.
192 It's also possible to create a non auto-starting program file, by defining
193 only the <tt/__AUTOSTART__/ symbol. Such a program has to be run manually
194 after being loaded by DOS (for example by using the "M" option of DOS 2.5).
195 Defining only the <tt/__EXEHDR__/ symbol will create a (useless) file which
196 doesn't conform to the DOS executable file format (like a "plain" binary file)
197 but still has the "autostart" load chunk appended.
199 The sections of the file which the defines refer to (<tt/__AUTOSTART__/ for
200 the autostart trailer, <tt/__EXEHDR__/ for the EXE header and load address)
201 is <it/left out/, keep this in mind.
203 The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
206 <sect2><tt/atari-asm-xex.cfg/<p>
208 This config file allows writing multi segment binaries easily, without having to
209 write the header explicitly on each segment.
211 It is similar to the <tt/atari-asm.cfg/ above, but uses the ATARI (xex) file
212 format support on LD65 instead of the standard binary output, so it does not
213 have the <tt/__AUTOSTART/ nor the <tt/__EXEHDR__/ symbols.
215 Note that each <tt/MEMORY/ area in the configuration file will have it's own
216 segment in the output file with the correct headers, and you can specify and
217 init address INITAD) for each memory area.
219 <sect2><tt/atari-cart.cfg/<p>
221 This config file can be used to create 8K or 16K cartridges. It's suited both
222 for C and assembly language programs.
224 By default, an 8K cartridge is generated. To create a 16K cartridge, pass the
225 size of the cartridge to the linker, like "<tt/-D__CARTSIZE__=0x4000/".
226 The only valid values for <tt/__CARTSIZE__/ are 0x2000 and 0x4000.
228 The option byte of the cartridge can be set with the <tt/__CARTFLAGS__/
229 value, passed to the linker. The default value is $01, which means
230 that the cartridge doesn't prevent the booting of DOS.
232 The option byte will be located at address $BFFD. For more information
233 about its use, see e.g. "Mapping the Atari".
235 <sect2><tt/atari-cassette.cfg/<p>
237 This config file can be used to create cassette boot files. It's suited both
238 for C and assembly language programs.
240 The size of a cassette boot file is restricted to 32K. Larger programs
241 would need to be split in more parts and the parts to be loaded manually.
243 To write the generated file to a cassette, a utility (<tt/w2cas.com/) to run
244 on an Atari is provided in the <tt/util/ directory of <tt/atari/ target dir.
246 <sect2><tt/atari-xex.cfg/<p>
248 This config file shows how to write a binary using the ATARI (xex) file format
249 support on LD65, this simplifies the memory areas and allows to add new memory
250 areas easily without writing new headers and trailers.
252 Note that the default C library includes the system-check chunk, so in this
253 linker configuration we suppress the importing of the header and trailer for
254 this chunk by defining the standard import symbols to a 0 value. For the
255 initialization address of the system-check chunk, the INITAD is set directly in
258 <sect1><tt/atarixl/ config files<p>
260 <sect2>default config file (<tt/atarixl.cfg/)<p>
262 The default configuration is tailored to C programs. It creates files
263 which have a default load address of $2400.
265 The files generated by this config file include the
266 <ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
267 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
269 <sect2><tt/atarixl-largehimem.cfg/<p>
271 This is the same as the default config file, but it rearranges the
272 high memory beneath the ROM into one large block. In order for this
273 config file to work, the runtime library has to be recompiled with a
274 special define. See the file <tt/libsrc/atari/Makefile.inc/ in the
277 The files generated by this config file include the
278 <ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
279 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
281 <sect2><tt/atarixl-xex.cfg/<p>
283 Similar to the <tt/atari-xex.cfg/ above, this config file shows how to write a
284 binary using the ATARI (xex) file format support on LD65.
286 In addition to the suppressing of the system-check headers and trailers, this
287 also suppresses the shadow-ram-preparation headers and trailers, but does this
288 by defining an "UNUSED" memory area that is not written to the output file.
291 <sect>Platform specific header files<p>
293 Programs containing Atari specific code may use the <tt/atari.h/
296 This also includes access to operating system locations (e.g. hardware shadow registers) by a structure called
298 The names are the usual ones you can find in system reference manuals. Example:
302 OS.savmsc = ScreenMemory;
303 OS.color4 = 14; // white frame
304 if (OS.stick0 != 15 || OS.ch != 255) // key or stick input?
308 Please note that memory location 762/$2FA is called "<tt/char_/" while the orignal name "<tt/char/" conflicts with the C keyword.
310 If you like to use the OS names and locations for the original Atari 800 operating system, please "<tt/#define OSA/" before including the
311 <tt/atari.h/ header file.
312 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/.
314 Access to the Basic programming language zero page variables is established by the structure "<tt/BASIC/".
316 <sect1>Atari specific functions<p>
318 The functions and global variable listed below are special for the Atari.
319 See the <url url="funcref.html" name="function reference"> for declaration and usage.
329 <item>_is_cmdline_dos
338 <sect1>Hardware access<p>
340 The following pseudo variables declared in the <tt/atari.h/ header
341 file do allow access to hardware located in the address space. Some
342 variables are structures, accessing the struct fields will access the
347 <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
348 The <tt/GTIA_READ/ structure allows read access to the GTIA. The
349 <tt/GTIA_WRITE/ structure allows write access to the GTIA.
350 See the <tt/_gtia.h/ header file located in the include directory
351 for the declaration of the structure.
353 <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
354 The <tt/POKEY_READ/ structure allows read access to the POKEY. The
355 <tt/POKEY_WRITE/ structure allows write access to the POKEY.
356 See the <tt/_pokey.h/ header file located in the include directory
357 for the declaration of the structure.
359 <tag><tt/ANTIC/</tag>
360 The <tt/ANTIC/ structure allows read access to the ANTIC.
361 See the <tt/_antic.h/ header file located in the include directory
362 for the declaration of the structure.
365 The <tt/PIA/ structure allows read access to the PIA 6520.
366 See the <tt/_pia.h/ header file located in the include directory
367 for the declaration of the structure.
371 <sect1>Display lists<p>
373 A major feature of the Atari graphics chip "ANTIC" is to
374 process instructions for the display generation.
375 cc65 supports constructing these display lists by offering defines
376 for the instructions. In conjunction with the "void"-variable extension
377 of cc65, display lists can be created quite comfortable:
381 unsigned char ScreenMemory[100];
388 DL_LMS(DL_CHR20x8x2),
399 OS.sdlst = &DisplayList;
403 Please inspect the <tt/_antic.h/ header file to detemine the supported
404 instruction names. Modifiers on instructions can be nested without need
407 <tt/DL_LMS(DL_HSCROL(DL_VSCROL(DL_DLI(DL_MAP80x4x2))))/
409 Please mind that ANTIC has memory alignment requirements for "player
410 missile graphics"-data, font data, display lists and screen memory. Creation
411 of a special linker configuration with appropriate aligned segments and
412 switching to that segment in the c-code is usually neccessary. A more memory
413 hungry solution consists in using the "<tt/posix_memalign()/" function in
414 conjunction with copying your data to the allocated memory.
416 <sect1>Character mapping<p>
418 The Atari has two representations for characters:
420 <item> ATASCII is character mapping which is similar to ASCII and used
421 by the CIO system of the OS. This is the default mapping of cc65 when
422 producing code for the atari target.
423 <item> The internal/screen mapping represents the real value of the
424 screen ram when showing a character.
427 For direct memory access (simplicity and speed) enabling the internal
428 mapping can be useful. This can be achieved by including the
429 "<tt/atari_screen_charmap.h/" header.
431 A word of caution: Since the <tt/0x00/ character has to be mapped in an
432 incompatible way to the C-standard, the usage of string functions in
433 conjunction with internal character mapped strings delivers unexpected
434 results regarding the string length. The end of strings are detected where
435 you may not expect them (too early or (much) too late). Internal mapped
436 strings typically support the "<tt/mem...()/" functions.
438 <em>For assembler sources the macro "<tt/scrcode/" from the "<tt/atari.mac/"
439 package delivers the same feature.</em>
441 You can switch back to the ATASCII mapping by including
442 "<tt/atari_atascii_charmap.h/".
444 A final note: Since cc65 has currently some difficulties with string merging
445 under different mappings, defining remapped strings works only flawlessly
446 with static array initialization:
449 #include <atari_screen_charmap.h>
450 char pcScreenMappingString[] = "Hello Atari!";
452 #include <atari_atascii_charmap.h>
453 char pcAtasciiMappingString[] = "Hello Atari!";
456 delivers correct results, while
459 #include <atari_screen_charmap.h>
460 char* pcScreenMappingString = "Hello Atari!";
462 #include <atari_atascii_charmap.h>
463 char* pcAtasciiMappingString = "Hello Atari!";
468 <sect1>Keyboard codes<p>
470 For direct keyboard scanning in conjunction with e.g. the OS location "CH" (764/$2FC),
471 all keyboard codes are available as defined values on C and assembler side.
489 You can find the C defines in the file "<tt/atari.h/" or "<tt/atari.inc/" for the assembler variant.
492 <sect>Loadable drivers<p>
494 The names in the parentheses denote the symbols to be used for static linking of the drivers.
497 <sect1>Graphics drivers<p>
499 <table><tabular ca="rrrr">
500 <tt/atari/|<tt/atarixl/|screen resolution|display pages@<hline>
501 <tt/atr3.tgi (atr3_tgi)/|<tt/atrx3.tgi (atrx3_tgi)/|40x24x4 (CIO mode 3, ANTIC mode 8)|1@
502 <tt/atr4.tgi (atr4_tgi)/|<tt/atrx4.tgi (atrx4_tgi)/|80x48x2 (CIO mode 4, ANTIC mode 9)|1@
503 <tt/atr5.tgi (atr5_tgi)/|<tt/atrx5.tgi (atrx5_tgi)/|80x48x4 (CIO mode 5, ANTIC mode A)|1@
504 <tt/atr6.tgi (atr6_tgi)/|<tt/atrx6.tgi (atrx6_tgi)/|160x96x2 (CIO mode 6, ANTIC mode B)|1@
505 <tt/atr7.tgi (atr7_tgi)/|<tt/atrx7.tgi (atrx7_tgi)/|160x96x4 (CIO mode 7, ANTIC mode D)|1@
506 <tt/atr8.tgi (atr8_tgi)/|<tt/atrx8.tgi (atrx8_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|1@
507 <tt/atr8p2.tgi (atr8p2_tgi)/|<tt/atrx8p2.tgi (atrx8p2_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|2@
508 <tt/atr9.tgi (atr9_tgi)/|<tt/atrx9.tgi (atrx9_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|1@
509 <tt/atr9p2.tgi (atr9p2_tgi)/|<tt/atrx9p2.tgi (atrx9p2_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|2@
510 <tt/atr10.tgi (atr10_tgi)/|<tt/atrx10.tgi (atrx10_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|1@
511 <tt/atr10p2.tgi (atr10p2_tgi)/|<tt/atrx10p2.tgi (atrx10p2_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|2@
512 <tt/atr11.tgi (atr11_tgi)/|<tt/atrx11.tgi (atrx11_tgi)/|80x192x16h (CIO mode 11, ANTIC mode F, GTIA mode $C0)|1@
513 <tt/atr14.tgi (atr14_tgi)/|<tt/atrx14.tgi (atrx14_tgi)/|160x192x2 (CIO mode 14, ANTIC mode C)|1@
514 <tt/atr15.tgi (atr15_tgi)/|<tt/atrx15.tgi (atrx15_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|1@
515 <tt/atr15p2.tgi (atr15p2_tgi)/|<tt/atrx15p2.tgi (atrx15p2_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|2
517 <!-- <caption>bla bla -->
521 Many graphics modes require more memory than the text screen which is
522 in effect when the program starts up. Therefore the programmer has to
523 tell the program beforehand the memory requirements of the graphics
524 modes the program intends to use.
526 On the <tt/atari/ target his can be done by using the __RESERVED_MEMORY__
527 linker config variable. The number specified there describes the number
528 of bytes to subtract from the top of available memory as seen from the
529 runtime library. This memory is then used by the screen buffer.
531 On the <tt/atarixl/ target the screen memory resides below the program
532 load address. In order to reserve memory for a graphics mode, one
533 simply uses a higher program load address. There are restrictions on
534 selectable load addresses,
535 see <ref name="Selecting a good program load address" id="loadaddr">.
537 The numbers for the different graphics modes presented below should
538 only be seen as a rule of thumb. Since the screen buffer memory needs
539 to start at specific boundaries, the numbers depend on the current top
541 The following numbers were determined by a BASIC program.
545 graphics mode|reserved memory@<hline>
579 <caption>reserved memory required for different graphics modes
582 The values of "1" are needed because the graphics command crashes if
583 it doesn't have at least one byte available. This seems to be a bug of
586 Default drivers: <tt/atr8.tgi (atr8_tgi)/ and <tt/atrx8.tgi (atrx8_tgi)/.
588 <sect1>Extended memory drivers<p>
590 Currently there is only one extended memory driver. It manages the second 64K of a 130XE.
594 <tt/atari/|<tt/atarixl/@<hline>
595 <tt/atr130.emd (atr130_emd)/|<tt/atrx130.emd (atrx130_emd)/
599 <sect1>Joystick drivers<p>
601 Currently there are two joystick drivers available:
605 <tt/atari/|<tt/atarixl/|description@<hline>
606 <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.)@
607 <tt/atrmj8.joy (atrmj8_joy)/|<tt/atrxmj8.joy (atrxmj8_joy)/|Supports up to eight standard joysticks connected to a MultiJoy adapter.
611 Default drivers: <tt/atrstd.joy (atrstd_joy)/ and <tt/atrxstd.joy (atrxstd_joy)/.
613 <sect1>Mouse drivers<p>
615 Currently there are five mouse drivers available:
619 <tt/atari/|<tt/atarixl/|description@<hline>
620 <tt/atrjoy.mou (atrjoy_mou)/|<tt/atrxjoy.mou (atrxjoy_mou)/|Supports a mouse emulated by a standard joystick.@
621 <tt/atrst.mou (atrst_mou)/|<tt/atrxst.mou (atrxst_mou)/|Supports an Atari ST mouse.@
622 <tt/atrami.mou (atrami_mou)/|<tt/atrxami.mou (atrxami_mou)/|Supports an Amiga mouse.@
623 <tt/atrtrk.mou (atrtrk_mou)/|<tt/atrxtrk.mou (atrxtrk_mou)/|Supports an Atari trakball.@
624 <tt/atrtt.mou (atrtt_mou)/|<tt/atrxtt.mou (atrxtt_mou)/|Supports an Atari touch tablet.
628 All mouse devices connect to joystick port #0.
630 Default drivers: <tt/atrst.mou (atrst_mou)/ and <tt/atrxst.mou (atrxst_mou)/.
632 <sect2>Mouse callbacks<p>
634 There are two mouse callbacks available.
636 The "text mode" callbacks (<tt/mouse_txt_callbacks/) display the mouse cursor as a "diamond" character
637 on the standard "GRAPHICS 0" text mode screen. The mouse cursor character can be changed by an
638 assembly file defining the character by exporting the zeropage symbol <tt/mouse_txt_char/.
639 The default file looks like this:
641 .export mouse_txt_char : zp = 96 ; 'diamond' screen code
644 The "P/M" callbacks (<tt/mouse_pm_callbacks/) use Player-Missile graphics for the mouse cursor.
645 The cursor shape can be changed, too, by an assembly file. Here's the default shape definition:
647 .export mouse_pm_bits
648 .export mouse_pm_height : zeropage
649 .export mouse_pm_hotspot_x : zeropage
650 .export mouse_pm_hotspot_y : zeropage
660 mouse_pm_height = * - mouse_pm_bits
661 ; hot spot is upper left corner
662 mouse_pm_hotspot_x = 0
663 mouse_pm_hotspot_y = 0
666 <tt/mouse_pm_bits/ defines the shape of the cursor, <tt/mouse_pm_height/ defines the number of
667 bytes in <tt/mouse_pm_bits/. <tt/mouse_pm_hotspot_x/ and <tt/mouse_pm_hotspot_y/ define the
668 position in the shape where "the mouse points to". When using this callback page #6 ($600
669 - $6FF) is used for the P/M graphics data and no P/M graphics can otherwise be used
670 by the program. The height of the shape (<tt/mouse_pm_height/)
671 must not exceed 32 lines since the callback routines cannot handle more than 32 lines.
673 The default callbacks definition (<tt/mouse_def_callbacks/) is an alias for the "P/M" callbacks.
675 <sect1>RS232 device drivers<p>
677 Currently there is one RS232 driver. It uses the R: device (therefore
678 an R: driver needs to be installed) and was tested with the 850
683 <tt/atari/|<tt/atarixl/@<hline>
684 <tt/atrrdev.ser (atrrdev_ser)/|<tt/atrxrdev.ser (atrxrdev_ser)/
691 <sect1><tt/Realtime clock/<label id="realtimeclock"<p>
693 Access to the realtime clock is supported only when running on SpartaDOS-X.
694 There needs to be a realtime clock driver installed. This is normally the case
695 in the default installation (CONFIG.SYS) of SpartaDOS-X.
696 A missing realtime clock driver in SpartaDOS-X is not supported, and the program
697 may crash when calling the <tt/clock_settime()/ or <tt/clock_gettime()/
700 The resolution of the realtime clock driver is 1 second.
702 <sect1><tt/atarixl target/<#if output="info|latex2e"> limitations</#if><label id="xllimitations"<p>
705 <item>The display is cleared at program start and at program termination. This is a side
706 effect of relocating the display memory below the program start address.
707 <item>Not all possible CIO and SIO functions are handled by the runtime stub code which banks
708 the ROM in and out. All functions used by the runtime library are handled, though.
709 <item>The <tt/_sys()/ function is not supported.
710 <item>It is not compatible with DOSes or other programs using the memory below the ROM.
713 <sect>DIO implementation<label id="dio"><p>
715 The Atari supports disk drives with either 128 or 256 byte sectors.
716 The first three sectors of any disk are always 128 bytes long though. This is
717 because the system can only boot from 128 bytes sectors.
719 Therefore the DIO read and write functions transfer only 128 bytes
720 for sectors 1 to 3, regardless of the type of diskette.
723 <sect>CONIO implementation<label id="conio"><p>
725 The console I/O is speed optimized therefore support for XEP80 hardware
726 or f80.com software is missing. Of course you may use stdio.h functions.
729 <sect>Technical details<label id="techdetail"><p>
731 <sect1><tt/atari/<#if output="info|latex2e"> details</#if><p>
733 <sect2><#if output="info|latex2e"><tt/atari/ </#if>Load chunks<p>
735 An <tt/atari/ program contains two load chunks.
738 <item>"system check"<label id="syschk">&nl;
739 This load chunk is always loaded at address $2E00, and checks if the system has
740 enough memory to run the program. It also checks if the program start address is not
741 below MEMLO. If any of the checks return false, the loading of the program is aborted.&nl;
742 The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.
743 <item>main program&nl;
744 This load chunk is loaded at the selected program start address (default $2000) and
745 contains all of the code and data of the program.&nl;
746 The contents of this chunk come from the MAIN memory area of the linker config file.
750 <sect1><tt/atarixl/<#if output="info|latex2e"> details</#if><p>
752 <sect2>General operation<p>
754 The <tt/atarixl/ target banks out the ROM while the program is running in
755 order to make more memory available to the program.
757 The screen memory is by default located at the top of available memory,
758 $BFFF if BASIC is not enabled, $9FFF if BASIC is enabled.
759 Therefore, in order to create a largest possible continuous memory area,
760 the screen memory is moved below the program load address. This gives
761 a memory area from <program load addr> to $CFFF.
763 The startup code installs wrappers for interrupt handlers and ROM routines.
764 When an interrupt or call to a ROM routine happens, the wrappers enable the
765 ROM, call the handler or routine, and disable the ROM again.
767 The "wrapping" of the ROM routines is done by changing the ROM entry
768 point symbols in <tt/atari.inc/ to point to the wrapper functions.
770 For ROM functions which require input or output buffers, the wrappers
771 copy the data as required to buffers in low memory.
773 <sect2><#if output="info|latex2e"><tt/atarixl/ </#if>Load chunks<label id="xlchunks"><p>
775 An <tt/atarixl/ program contains three load chunks.
778 <item>"system check"<label id="syschkxl">&nl;
779 This load chunk is always loaded at address $2E00, and checks if the system is
780 suitable for running the program. It also checks if there is enough room between MEMLO
781 and the program start address to move the text mode screen buffer there. If any of the
782 checks return false, the loading of the program is aborted.&nl;
783 The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.
784 <item>"shadow RAM prepare"&nl;
785 The second load chunk gets loaded to the selected program load address (default $2400).
786 It moves the screen memory below the program load address, copies the character generator
787 from ROM to its new place in RAM, and copies the parts of the program which reside in
788 high memory below the ROM to their place. The high memory parts are included in this load chunk.&nl;
789 At the beginning of this load chunk there is a .bss area, which is not part of the
790 EXE file. Therefore the on-disk start address of this load chunk will be higher than the
791 selected start address. This .bss area (segment LOWBSS) contains the buffers for the
792 double buffering of ROM input and output data. If you add contents to this segment be aware
793 that the contents won't be zero initialized by the startup code.&nl;
794 The contents of this chunk come from the SRPREPCHNK memory area of the linker config file.
795 <item>main program&nl;
796 This load chunk is loaded just above the LOWBSS segment, replacing the code of
797 the previous load chunk. It contains all remaining code and data sections of the program,
798 including the startup code.&nl;
799 The contents of this chunk come from the RAM memory area of the linker config file.
802 <sect2>Moving screen memory below the program start address<p>
804 When setting a graphics mode, the ROM looks at the RAMTOP location. RAMTOP
805 describes the amount of installed memory in pages (RAMTOP is only one byte).
806 The screen memory and display list are placed immediately below RAMTOP.
808 Now in order to relocate the screen memory to lower memory, the startup code
809 puts a value into RAMTOP which causes the ROM routines to allocate the display
810 memory below the program start address and then it issues a ROM call to setup
811 the regular text mode.
813 <sect2>Selecting a good program load address<label id="loadaddr"><p>
815 Due to the movement of the screen memory below the program start, there are some
816 load addresses which are sub-optimal because they waste memory or prevent a
817 higher resolution graphics mode from being enabled.
819 There are restrictions at which addresses screen memory (display buffer and display
820 list) can be placed. The display buffer cannot cross a 4K boundary and a display
821 list cannot cross a 1K boundary.
823 The startup code takes this into account when moving the screen memory down.
824 If the program start address (aligned to the next lower page boundary) minus
825 the screen buffer size would result in a screen buffer which spans a 4K
826 boundary, the startup code lowers RAMTOP to this 4K boundary.&nl;
827 The size of the screen buffer in text mode is 960 ($3C0) bytes. So, for
828 example, a selected start address of $2300 would span the 4K boundary
829 at $2000. The startup code would adjust the RAMTOP value in such way that
830 the screen memory would be located just below this boundary (at $1C40).
831 This results in the area [$2000-$22FF] being wasted.
832 Additionally, the program might fail to load since the lowest address used
833 by the screen memory could be below MEMLO. (The lowest address used in this
834 example would be at $1C20, where the display list would allocated.)
836 These calculations are performed by the startup code (in the first two
837 load chunks), but the startup code only takes the default 40x24 text mode
838 into account. If the program later wants to load TGI drivers which set
839 a more memory consuming graphics mode, the user has to pick a higher
841 Using higher resolution modes there is a restriction in the ROM that it
842 doesn't expect RAMTOP to be at arbitrary values. The Atari memory modules
843 came only in 8K or 16K sizes, so the ROM expects RAMTOP to only have
844 values in 8K steps. Therefore, when using the highest resolution modes
845 the program start address must be at an 8K boundary.
848 <sect2>Character generator location<label id="chargenloc"><p>
850 The default <tt/atarixl/ linker config file (<tt/atarixl.cfg/) leaves the
851 character generator location at the same address where it is in ROM
852 ($E000). This has the disadvatage to split the upper memory into
853 two parts ([$D800-$DFFF] and
854 [$E400-$FFF9]). For applications which
855 require a large continuous upper memory area, an alternative linker
856 config file (<tt/atarixl-largehimem.cfg/) is provided. It relocates the
857 character generator to $D800, providing a single big upper
858 memory area at [$DC00-$FFF9].
860 With the character generator at a different address than in ROM, the routines
861 which enable and disable the ROM also have to update the chargen pointer.
862 This code is not enabled by default. In order to enable it,
863 uncomment the line which sets CHARGEN_RELOC in <tt/libsrc/atari/Makefile.inc/
864 and recompile the <tt/atarixl/ runtime library.
869 <sect1>Function keys<p>
871 Function keys are mapped to Atari + number key.
874 <sect1>Passing arguments to the program<p>
876 Command line arguments can be passed to <tt/main()/ when the used DOS supports it.
879 <item>Arguments are separated by spaces.
880 <item>Leading and trailing spaces around an argument are ignored.
881 <item>The first argument passed to <tt/main/ is the program name.
882 <item>A maximum number of 16 arguments (including the program name) are
889 The runtime for the Atari uses routines marked as <tt/.INTERRUPTOR/ for
890 interrupt handlers. Such routines must be written as simple machine language
891 subroutines and will be called automatically by the VBI handler code
892 when they are linked into a program. See the discussion of the <tt/.CONDES/
893 feature in the <url url="ca65.html" name="assembler manual">.
895 Please note that on the Atari targets the <tt/.INTERRUPTOR/s are being
896 run in NMI context. The other targets run them in IRQ context.
898 <sect1>Reserving a memory area inside a program<label id="memhole"><p>
900 (This section is primarily applicable to the <tt/atari/ target, but the
901 principles apply to <tt/atatixl/ as well.)
903 The Atari 130XE maps its additional memory into CPU memory in 16K
904 chunks at address $4000 to $7FFF. One might want to
905 prevent this memory area from being used by cc65. Other reasons to
906 prevent the use of some memory area could be to reserve space for the
907 buffers for display lists and screen memory.
909 The Atari executable format allows holes inside a program, e.g. one
910 part loads into $2E00 to $3FFF, going below the reserved
911 memory area (assuming a reserved area from $4000 to
912 $7FFF), and another part loads into $8000 to
915 Each load chunk of the executable starts with a 4 byte header which
916 defines its load address and size. In the following linker config files
917 these headers are named HEADER and SECHDR (for the MEMORY layout), and
918 accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout).
920 <sect2>Low code and high data example<p>
921 Goal: Create an executable with 2 load chunks which doesn't use the
922 memory area from $4000 to $7FFF. The CODE segment of
923 the program should go below $4000 and the DATA and RODATA
924 segments should go above $7FFF.
926 The main problem is that the EXE header generated by the cc65 runtime
927 lib is wrong. It defines a single load chunk with the sizes/addresses
928 of the STARTUP, LOWCODE, ONCE, CODE, RODATA, and DATA segments, in
929 fact, the whole user program (we're disregarding the "system check"
932 The contents of the EXE header come from the EXEHDR and MAINHDR segments.
933 The EXEHDR segment just contains the $FFFF value which is required
934 to be the first bytes of the EXE file.&nl;
935 The MAINHDR are defined in in crt0.s. This cannot be changed without
936 modifying and recompiling the cc65 atari runtime library. Therefore
937 the original contents of this segment must be discarded and be
938 replaced by a user created one. This discarding is done by assigning the
939 MAINHDR segment to the (new introduced) DISCARD memory area. The DISCARD memory area is
940 thrown away in the new linker config file (written to file "").
941 We add a new FSTHDR segment for the chunk header of the first chunk.
943 The user needs to create a customized linker config file which adds
944 new memory areas and segments to hold the new header data for the first load
945 chunk and the header data for the second load chunk. Also an assembly source file
946 needs to be created which defines the contents of the new header data
947 for the two load chunks.
950 This is an example of a modified cc65 Atari linker configuration file
954 __STACKSIZE__: value = $800 type = weak; # 2K stack
955 __RESERVED_MEMORY__: value = $0000, type = weak;
958 STARTADDRESS: default = $2E00;
961 ZP: start = $82, size = $7E, type = rw, define = yes;
963 HEADER: start = $0000, size = $2, file = %O; # first load chunk
965 FSTHDR: start = $0000, size = $4, file = %O; # second load chunk
966 RAMLO: start = %S, size = $4000 - %S, file = %O;
968 DISCARD: start = $4000, size = $4000, file = "";
970 SECHDR: start = $0000, size = $4, file = %O; # second load chunk
971 RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
974 EXEHDR: load = HEADER, type = ro;
976 MAINHDR: load = DISCARD, type = ro;
978 NEXEHDR: load = FSTHDR, type = ro; # first load chunk
979 STARTUP: load = RAMLO, type = ro, define = yes;
980 LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes;
981 ONCE: load = RAMLO, type = ro, optional = yes;
982 CODE: load = RAMLO, type = ro, define = yes;
984 CHKHDR: load = SECHDR, type = ro; # second load chunk
985 RODATA: load = RAM, type = ro, define = yes;
986 DATA: load = RAM, type = rw, define = yes;
987 BSS: load = RAM, type = bss, define = yes;
989 ZEROPAGE: load = ZP, type = zp;
990 AUTOSTRT: load = RAM, type = ro; # defines program entry point
993 CONDES: segment = ONCE,
995 label = __CONSTRUCTOR_TABLE__,
996 count = __CONSTRUCTOR_COUNT__;
997 CONDES: segment = RODATA,
999 label = __DESTRUCTOR_TABLE__,
1000 count = __DESTRUCTOR_COUNT__;
1005 A new memory area DISCARD was added.
1006 It gets loaded with the contents of the (now unused) MAINHDR segment. But the
1007 memory area isn't written to the output file. This way the contents of
1008 the MAINHDR segment get discarded.
1010 The newly added NEXEHDR segment defines the correct chunk header for the
1011 first intended load chunk. It
1012 puts the STARTUP, LOWCODE, ONCE, and CODE segments, which are the
1013 segments containing only code, into load chunk #1 (RAMLO memory area).
1015 The header for the second load chunk comes from the new CHKHDR
1016 segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load
1017 chunk #2 (RAM memory area).
1020 The contents of the new NEXEHDR and CHKHDR segments come from this
1023 .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
1024 .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
1027 .word __STARTUP_LOAD__
1028 .word __CODE_LOAD__ + __CODE_SIZE__ - 1
1031 .word __RODATA_LOAD__
1032 .word __BSS_LOAD__ - 1
1037 cl65 -t atari -C split.cfg -o prog.com prog.c split.s
1040 <sect2>Low data and high code example<p>
1043 Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, ONCE,
1044 CODE, BSS, ZPSAVE into high memory (split2.cfg):
1048 __STACKSIZE__: value = $800 type = weak; # 2K stack
1049 __RESERVED_MEMORY__: value = $0000, type = weak;
1052 STARTADDRESS: default = $2E00;
1055 ZP: start = $82, size = $7E, type = rw, define = yes;
1057 HEADER: start = $0000, size = $2, file = %O; # first load chunk
1059 FSTHDR: start = $0000, size = $4, file = %O; # second load chunk
1060 RAMLO: start = %S, size = $4000 - %S, file = %O;
1062 DISCARD: start = $4000, size = $4000, file = "";
1064 SECHDR: start = $0000, size = $4, file = %O; # second load chunk
1065 RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
1068 EXEHDR: load = HEADER, type = ro; # discarded old EXE header
1070 MAINHDR: load = DISCARD, type = ro;
1072 NEXEHDR: load = FSTHDR, type = ro; # first load chunk
1073 RODATA: load = RAMLO, type = ro, define = yes;
1074 DATA: load = RAMLO, type = rw, define = yes;
1076 CHKHDR: load = SECHDR, type = ro; # second load chunk
1077 STARTUP: load = RAM, type = ro, define = yes;
1078 ONCE: load = RAM, type = ro, optional = yes;
1079 CODE: load = RAM, type = ro, define = yes;
1080 BSS: load = RAM, type = bss, define = yes;
1082 ZEROPAGE: load = ZP, type = zp;
1083 AUTOSTRT: load = RAM, type = ro; # defines program entry point
1086 CONDES: segment = ONCE,
1088 label = __CONSTRUCTOR_TABLE__,
1089 count = __CONSTRUCTOR_COUNT__;
1090 CONDES: segment = RODATA,
1092 label = __DESTRUCTOR_TABLE__,
1093 count = __DESTRUCTOR_COUNT__;
1097 New contents for NEXEHDR and CHKHDR are needed (split2.s):
1099 .import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__
1100 .import __DATA_LOAD__, __RODATA_LOAD__
1103 .word __RODATA_LOAD__
1104 .word __DATA_LOAD__ + __DATA_SIZE__ - 1
1107 .word __STARTUP_LOAD__
1108 .word __BSS_LOAD__ - 1
1113 cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s
1116 <sect2>Final note<label id="memhole_final_note"><p>
1118 There are two other memory areas which don't appear directly in the
1119 linker config file. They are the stack and the heap.
1121 The cc65 runtime lib places the stack location at the end of available
1122 memory. This is dynamically set from the MEMTOP system variable at
1123 startup. The heap is located in the area between the end of the BSS
1124 segment and the top of the stack as defined by __STACKSIZE__.
1126 If BSS and/or the stack shouldn't stay at the end of the program,
1127 some parts of the cc65 runtime lib need to be replaced/modified.
1129 common/_heap.s defines the location of the heap and atari/crt0.s
1130 defines the location of the stack by initializing sp.
1133 <sect1>Upgrading from an older cc65 version<p>
1135 If you are using a customized linker config file you might get some errors
1136 regarding the MAINHDR segment. Like this:
1139 ld65: Error: Missing memory area assignment for segment 'MAINHDR'
1142 The old "HEADER" memory description contained six bytes: $FFFF
1143 and the first and last memory addess of the program. For the "system
1144 check" load chunk this had to be split into two memory assigments. The
1145 "HEADER" now only contains the $FFFF. The main program's first
1146 and last memory address were moved to a new segment, called "MAINHDR",
1147 which in the new linker config file goes into its own memory area (also
1148 called "MAINHDR").&nl;&nl;
1149 A simple way to adapt your old linker config file is to add the
1150 following line to the "SEGMENTS" section:
1153 MAINHDR: load = HEADER, type = ro;
1158 <sect1>Getting rid of the "system check" load chunk<label id="nosyschk"><p>
1160 If, for some reason, you don't want to include the "system check" load
1161 chunk, you can do so by defining the symbol <tt/__SYSTEM_CHECK__/ when linking the
1162 program. The "system check" chunk doesn't include vital parts of the
1163 program. So if you don't want the system checks, it is save to leave them out.
1164 This is probably mostly interesting for debugging.
1166 When using cl65, you can leave it out with this command line:
1169 cl65 -Wl -D__SYSTEM_CHECK__=1 <arguments>
1172 The value you assign to <tt/__SYSTEM_CHECK_/ doesn't matter. If the
1173 <tt/__SYSTEM_CHECK__/ symbol is defined, the load chunk won't be included.
1178 This software is provided 'as-is', without any expressed or implied
1179 warranty. In no event will the authors be held liable for any damages
1180 arising from the use of this software.
1182 Permission is granted to anyone to use this software for any purpose,
1183 including commercial applications, and to alter it and redistribute it
1184 freely, subject to the following restrictions:
1187 <item> The origin of this software must not be misrepresented; you must not
1188 claim that you wrote the original software. If you use this software
1189 in a product, an acknowledgment in the product documentation would be
1190 appreciated but is not required.
1191 <item> Altered source versions must be plainly marked as such, and must not
1192 be misrepresented as being the original software.
1193 <item> This notice may not be removed or altered from any source