1 <!doctype linuxdoc system>
5 <title>Atari specific information for cc65
6 <author>Shawn Jefferson, <htmlurl
7 url="mailto:shawnjefferson@24fightingchickens.com"
8 name="shawnjefferson@24fightingchickens.com"> and
9 Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org">
13 An overview over the Atari runtime system as it is implemented for the cc65 C
17 <!-- Table of contents -->
20 <!-- Begin the document -->
24 This file contains an overview of the Atari runtime system as it comes
25 with the cc65 C compiler. It describes the memory layout, Atari specific
26 header files, available drivers, and any pitfalls specific to that
29 The Atari runtime support comes in two flavors: <tt/atari/ and <tt/atarixl/.
30 The <tt/atari/ target supports all Atari 8-bit computers, the <tt/atarixl/ only
31 supports XL type or newer machines (excluding the 600XL).
33 The <tt/atarixl/ runtime makes the whole 64K of memory available, with the
34 exception of the I/O area at $D000 - $D7FFF. Since the
35 <tt/atarixl/ runtime has some <ref name="limitations" id="limitations">, it is
36 recommended to use the <tt/atari/ target unless lack of memory dictates the
37 use of the <tt/atarixl/ target.
39 Please note that Atari specific functions are just mentioned here, they are
40 described in detail in the separate <htmlurl url="funcref.html" name="function
41 reference">. Even functions marked as "platform dependent" may be available on
42 more than one platform. Please see the function reference for more
46 <sect>Binary format<p>
48 The Atari DOS executable file format supports more than one load block (<it/chunk/).
50 The default binary output format generated by the linker for the
51 Atari target is a machine language program with a standard executable
52 header (FF FF <load chunk #1> ... <load chunk #n>).
53 A load chunk has the format [<2 byte start address> <2 bytes end address>
54 <chunk data>].
55 A run vector is added to the end of the
56 file ($02E0 $02E1 <run vector>) and is calculated using
57 the <tt/start/ label in crt0.s. (Technically the run vector is also a load chunk,
58 but is not regarded as such here.)
60 An <tt/atari/ program has two load chunks, an <tt/atarixl/ program has three load
61 chunks. The load chunks are defined in the linker configuration files. For more
62 detailed information about the load chunks see the chapter
63 <ref name="Technical details" id="techdetail">. For the discussion here it's
64 sufficient to know that the first load chunk(s) do preparation work and the
65 main part of the program is in the last load chunk.
67 The values determining the size of the main part of the program (the only load
68 chunk for <tt/atari/, the third load chunk for <tt/atarixl/) are calculated in
69 the crt0.s file from the __STARTUP_LOAD__ and __BSS_LOAD__ values.
70 Be aware of that if you create a custom linker config file and start moving segments around (see section
71 <ref name="Reserving a memory area inside the program" id="memhole">).
74 <sect>Memory layout<p>
76 <sect1><tt/atari/ target<p>
78 The default linker config file assumes that the BASIC ROM is disabled (or
79 the BASIC cartridge unplugged). This gives a usable memory range of
80 [$2000-$BC1F]. The library startup code examines the
81 current memory configuration, which depends on the size of the
82 installed memory and cartridges. It does so by using the value in
83 the MEMTOP ($2E5) variable as highest memory address the program
84 can use. The initial stack pointer, which is the upper bound of
85 memory used by the program, is set to this value, minus an optionally
86 defined __RESERVED_MEMORY__ value.
88 The default load address of $2000 can be changed by creating a custom
89 linker config file or by using the "--start-addr" cl65 command line
90 argument or the "--start-addr" or "-S" ld65 command line arguments.
92 Please note that the first load chunk (which checks the available memory)
93 will always be loaded at $2E00, regardless of the specified start
94 address. This address can only be changed by a custom linker config file.
100 The text screen depends on the installed memory size and cartridges
101 and can be obtained from the SAVMSC variable ($58).
104 The C runtime stack is located at MEMTOP and grows downwards,
105 regardless of how your linker config file is setup. This
106 accommodates the different memory configurations of the Atari
107 machines, as well as having a cartridge installed. You can override
108 this behaviour by writing your own crt0.s file and linking it to
109 your program (see also <ref name="Final note"
110 id="memhole_final_note">).
113 The C heap is located at the end of the program and grows towards the C
118 <sect1><tt/atarixl/ target<p>
120 The startup code rearranges the memory as follows:
123 <item>Sceen memory and display list are moved below the program start address.
124 <item>The ROM is disabled, making the memory in the areas [$C000-$CFFF]
125 and [$D800-$FFF9] available.
126 <item>Character generator data is copied from ROM to the CHARGEN location specified in the
127 linker config file. This is (in the default <tt/atarixl.cfg/ file) at the same address as
128 where it is in ROM ($E000, it can be changed, see <ref name="atarixl chargen location"
129 id="chargenloc">). With the character generator at $E000, there are two upper memory
130 areas available, [$D800-$DFFF] and [$E400-$FFF9].
133 With the default load address of $2400 this gives a usable memory range of
134 [$2400-$CFFF]. Note that the default load address for <tt/atarixl/ is
135 different (and lower) that the default load address for <tt/atari/. This is no problem since
136 on the <tt/atarixl/ target the first load chunk makes sure that the loaded prgram won't overwrite
137 memory below MEMLO. See <ref name="atarixl load chunks" id="xlchunks">.
144 The text screen depends on the selected load address ($2400
145 by default), and resides directly before that address, rounded to the next
147 The screen memory's start address can be obtained from the SAVMSC variable
151 The C runtime stack is located at end of the RAM memory area ($CFFF)
155 The C heap is located at the end of the program (end of BSS segment) and
156 grows towards the C runtime stack.
160 <sect>Linker configurations<p>
162 The ld65 linker comes with default config files for the Atari. There
163 are two targets for the Atari, <tt/atari/ and <tt/atarixl/.
164 The default config file for <tt/atari/ is selected with
165 <tt/-t atari/, and the default config file for <tt/atarixl/ is selected with
167 The Atari package comes with additional secondary linker config files which
168 can be used via <tt/-t atari -C <configfile>/ (for <tt/atari/ target) or
169 <tt/-t atarixl -C <configfile>/ (for <tt/atarixl/ target).
171 <sect1><tt/atari/ config files<p>
173 <sect2>default config file (<tt/atari.cfg/)<p>
175 The default configuration is tailored to C programs. It creates files
176 which have a default load address of $2000.
178 The files generated by this config file include the
179 <ref name="&dquot;system check&dquot;" id="syschk"> load chunk. It can
180 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
182 <sect2><tt/atari-asm.cfg/<p>
184 This config file aims to give the assembler programmer maximum
185 flexibility. All program segments (<tt/CODE/, <tt/DATA/, etc.) are
188 By default it creates regular DOS executable files, which have a default
189 load address of $2E00. It's also possible to generate an image of
190 just the program data without EXE header, load address, or (auto-)start address.
191 To you so, you have to define the symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
192 when linking the program. Therefore, to generate a "plain" binary file, pass the
193 options "<tt/-D__AUTOSTART__=1 -D__EXEHDR__=1/" to the linker.
194 It's also possible to create a non auto-starting program file, by defining
195 only the <tt/__AUTOSTART__/ symbol. Such a program has to be run manually
196 after being loaded by DOS (for example by using the "M" option of DOS 2.5).
197 Defining only the <tt/__EXEHDR__/ symbol will create a (useless) file which
198 doesn't conform to the DOS executable file format (like a "plain" binary file)
199 but still has the "autostart" load chunk appended.
201 The sections of the file which the defines refer to (<tt/__AUTOSTART__/ for
202 the autostart trailer, <tt/__EXEHDR__/ for the EXE header and load address)
203 is <it/left out/, keep this in mind.
205 The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
208 <sect2><tt/atari-cart.cfg/<p>
210 This config file can be used to create 8K or 16K cartridges. It's suited both
211 for C and assembly language programs.
213 By default, an 8K cartridge is generated. To create a 16K cartridge, pass the
214 size of the cartridge to the linker, like "<tt/-D__CARTSIZE__=0x4000/".
215 The only valid values for <tt/__CARTSIZE__/ are 0x2000 and 0x4000.
217 The option byte of the cartridge can be set with the <tt/__CARTFLAGS__/
218 value, passed to the linker. The default value is $01, which means
219 that the cartridge doesn't prevent the booting of DOS.
221 The option byte will be located at address $BFFD. For more information
222 about its use, see e.g. "Mapping the Atari".
224 <sect2><tt/atari-cassette.cfg/<p>
226 This config file can be used to create cassette boot files. It's suited both
227 for C and assembly language programs.
229 The size of a cassette boot file is restricted to 32K. Larger programs
230 would need to be split in more parts and the parts to be loaded manually.
232 To write the generated file to a cassette, a utility to run
233 on an Atari is provided in the <tt/targetutil/ directory (<tt/w2cas.com/).
235 <sect1><tt/atarixl/ config files<p>
237 <sect2>default config file (<tt/atarixl.cfg/)<p>
239 The default configuration is tailored to C programs. It creates files
240 which have a default load address of $2400.
242 The files generated by this config file include the
243 <ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
244 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
246 <sect2><tt/atarixl-largehimem.cfg/<p>
248 This is the same as the default config file, but it rearranges the
249 high memory beneath the ROM into one large block. In order for this
250 config file to work, the runtime library has to be recompiled with a
251 special define. See the file <tt/libsrc/atari/Makefile.inc/ in the
254 The files generated by this config file include the
255 <ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
256 optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
259 <sect>Platform specific header files<p>
261 Programs containing Atari specific code may use the <tt/atari.h/
265 <sect1>Atari specific functions<p>
267 The functions and global variable listed below are special for the Atari.
268 See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage.
286 <sect1>Hardware access<p>
288 The following pseudo variables declared in the <tt/atari.h/ header
289 file do allow access to hardware located in the address space. Some
290 variables are structures, accessing the struct fields will access the
295 <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
296 The <tt/GTIA_READ/ structure allows read access to the GTIA. The
297 <tt/GTIA_WRITE/ structure allows write access to the GTIA.
298 See the <tt/_gtia.h/ header file located in the include directory
299 for the declaration of the structure.
301 <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
302 The <tt/POKEY_READ/ structure allows read access to the POKEY. The
303 <tt/POKEY_WRITE/ structure allows write access to the POKEY.
304 See the <tt/_pokey.h/ header file located in the include directory
305 for the declaration of the structure.
307 <tag><tt/ANTIC/</tag>
308 The <tt/ANTIC/ structure allows read access to the ANTIC.
309 See the <tt/_antic.h/ header file located in the include directory
310 for the declaration of the structure.
313 The <tt/PIA/ structure allows read access to the PIA 6520.
314 See the <tt/_pia.h/ header file located in the include directory
315 for the declaration of the structure.
321 <sect>Loadable drivers<p>
323 The names in the parentheses denote the symbols to be used for static linking of the drivers.
326 <sect1>Graphics drivers<p>
328 <table><tabular ca="rrrr">
329 <tt/atari/|<tt/atarixl/|screen resolution|display pages@<hline>
330 <tt/atr3.tgi (atr3_tgi)/|<tt/atrx3.tgi (atrx3_tgi)/|40x24x4 (CIO mode 3, ANTIC mode 8)|1@
331 <tt/atr4.tgi (atr4_tgi)/|<tt/atrx4.tgi (atrx4_tgi)/|80x48x2 (CIO mode 4, ANTIC mode 9)|1@
332 <tt/atr5.tgi (atr5_tgi)/|<tt/atrx5.tgi (atrx5_tgi)/|80x48x4 (CIO mode 5, ANTIC mode A)|1@
333 <tt/atr6.tgi (atr6_tgi)/|<tt/atrx6.tgi (atrx6_tgi)/|160x96x2 (CIO mode 6, ANTIC mode B)|1@
334 <tt/atr7.tgi (atr7_tgi)/|<tt/atrx7.tgi (atrx7_tgi)/|160x96x4 (CIO mode 7, ANTIC mode D)|1@
335 <tt/atr8.tgi (atr8_tgi)/|<tt/atrx8.tgi (atrx8_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|1@
336 <tt/atr8p2.tgi (atr8p2_tgi)/|<tt/atrx8p2.tgi (atrx8p2_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|2@
337 <tt/atr9.tgi (atr9_tgi)/|<tt/atrx9.tgi (atrx9_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|1@
338 <tt/atr9p2.tgi (atr9p2_tgi)/|<tt/atrx9p2.tgi (atrx9p2_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|2@
339 <tt/atr10.tgi (atr10_tgi)/|<tt/atrx10.tgi (atrx10_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|1@
340 <tt/atr10p2.tgi (atr10p2_tgi)/|<tt/atrx10p2.tgi (atrx10p2_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|2@
341 <tt/atr11.tgi (atr11_tgi)/|<tt/atrx11.tgi (atrx11_tgi)/|80x192x16h (CIO mode 11, ANTIC mode F, GTIA mode $C0)|1@
342 <tt/atr14.tgi (atr14_tgi)/|<tt/atrx14.tgi (atrx14_tgi)/|160x192x2 (CIO mode 14, ANTIC mode C)|1@
343 <tt/atr15.tgi (atr15_tgi)/|<tt/atrx15.tgi (atrx15_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|1@
344 <tt/atr15p2.tgi (atr15p2_tgi)/|<tt/atrx15p2.tgi (atrx15p2_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|2
346 <!-- <caption>bla bla -->
350 Many graphics modes require more memory than the text screen which is
351 in effect when the program starts up. Therefore the programmer has to
352 tell the program beforehand the memory requirements of the graphics
353 modes the program intends to use.
355 On the <tt/atari/ target his can be done by using the __RESERVED_MEMORY__
356 linker config variable. The number specified there describes the number
357 of bytes to subtract from the top of available memory as seen from the
358 runtime library. This memory is then used by the screen buffer.
360 On the <tt/atarixl/ target the screen memory resides below the program
361 load address. In order to reserve memory for a graphics mode, one
362 simply uses a higher program load address. There are restrictions on
363 selectable load addresses,
364 see <ref name="Selecting a good program load address" id="loadaddr">.
366 The numbers for the different graphics modes presented below should
367 only be seen as a rule of thumb. Since the screen buffer memory needs
368 to start at specific boundaries, the numbers depend on the current top
370 The following numbers were determined by a BASIC program.
374 graphics mode|reserved memory@<hline>
408 <caption>reserved memory required for different graphics modes
411 The values of "1" are needed because the graphics command crashes if
412 it doesn't have at least one byte available. This seems to be a bug of
415 Default drivers: <tt/atr8.tgi (atr8_tgi) and /<tt/atrx8.tgi (atrx8_tgi)/.
417 <sect1>Extended memory drivers<p>
419 Currently there is only one extended memory driver. It manages the second 64K of a 130XE.
423 <tt/atari/|<tt/atarixl/@<hline>
424 <tt/atr130.emd (atr130_emd)/|<tt/atrx130.emd (atrx130_emd)/
428 <sect1>Joystick drivers<p>
430 Currently there are two joystick drivers available:
434 <tt/atari/|<tt/atarixl/|description@<hline>
435 <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.)@
436 <tt/atrmj8.joy (atrmj8_joy)/|<tt/atrxmj8.joy (atrxmj8_joy)/|Supports up to eight standard joysticks connected to a MultiJoy adapter.
441 Default drivers: <tt/atrstd.joy (atrstd_joy)/ and <tt/atrxstd.joy (atrxstd_joy)/.
443 <sect1>Mouse drivers<p>
445 Currently there are five mouse drivers available:
449 <tt/atari/|<tt/atarixl/|description@<hline>
450 <tt/atrjoy.mou (atrjoy_mou)/|<tt/atrxjoy.mou (atrxjoy_mou)/|Supports a mouse emulated by a standard joystick.@
451 <tt/atrst.mou (atrst_mou)/|<tt/atrxst.mou (atrxst_mou)/|Supports an Atari ST mouse.@
452 <tt/atrami.mou (atrami_mou)/|<tt/atrxami.mou (atrxami_mou)/|Supports an Amiga mouse.@
453 <tt/atrtrk.mou (atrtrk_mou)/|<tt/atrxtrk.mou (atrxtrk_mou)/|Supports an Atari trakball.@
454 <tt/atrtt.mou (atrtt_mou)/|<tt/atrxtt.mou (atrxtt_mou)/|Supports an Atari touch tablet.
459 All mouse devices connect to joystick port #0.
461 Default drivers: <tt/atrst.mou (atrst_mou)/ and <tt/atrxst.mou (atrxst_mou)/.
463 <sect1>RS232 device drivers<p>
465 Currently there is one RS232 driver. It uses the R: device (therefore
466 an R: driver needs to be installed) and was tested with the 850
471 <tt/atari/|<tt/atarixl/@<hline>
472 <tt/atrrdev.ser (atrrdev_ser)/|<tt/atrxrdev.ser (atrxrdev_ser)/
479 <sect1><tt/atarixl/<#if output="info|latex2e"> limitations</#if><label id="limitations"<p>
482 <item>The display is cleared at program start and at program termination. This is a side
483 effect of relocating the display memory below the program start address.
484 <item>Not all possible CIO and SIO functions are handled by the runtime stub code which banks
485 the ROM in and out. All functions used by the runtime library are handled, though.
486 <item>The <tt/_sys()/ function is not supported.
487 <item>It is not compatible with DOSes or other programs using the memory below the ROM.
490 <sect>DIO implementation<label id="dio"><p>
492 The Atari supports disk drives with either 128 or 256 byte sectors.
493 The first three sectors of any disk are always 128 bytes long though. This is
494 because the system can only boot from 128 bytes sectors.
496 Therefore the DIO read and write functions transfer only 128 bytes
497 for sectors 1 to 3, regardless of the type of diskette.
500 <sect>CONIO implementation<label id="conio"><p>
502 The console I/O is speed optimized therefore support for XEP80 hardware
503 or f80.com software is missing. Of course you may use stdio.h functions.
506 <sect>Technical details<label id="techdetail"><p>
508 <sect1><tt/atari/<#if output="info|latex2e"> details</#if><p>
510 <sect2><#if output="info|latex2e"><tt/atari/ </#if>Load chunks<p>
512 An <tt/atari/ program contains two load chunks.
515 <item>"system check"<label id="syschk">&nl;
516 This load chunk is always loaded at address $2E00, and checks if the system has
517 enough memory to run the program. It also checks if the program start address is not
518 below MEMLO. If any of the checks return false, the loading of the program is aborted.&nl;
519 The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.
520 <item>main program&nl;
521 This load chunk is loaded at the selected program start address (default $2000) and
522 contains all of the code and data of the program.&nl;
523 The contents of this chunk come from the RAM memory area of the linker config file.
527 <sect1><tt/atarixl/<#if output="info|latex2e"> details</#if><p>
529 <sect2>General operation<p>
531 The <tt/atarixl/ target banks out the ROM while the program is running in
532 order to make more memory available to the program.
534 The screen memory is by default located at the top of available memory,
535 $BFFF if BASIC is not enabled, $9FFF if BASIC is enabled.
536 Therefore, in order to create a largest possible continuous memory area,
537 the screen memory is moved below the program load address. This gives
538 a memory area from <program load addr> to $CFFF.
540 The startup code installs wrappers for interrupt handlers and ROM routines.
541 When an interrupt or call to a ROM routine happens, the wrappers enable the
542 ROM, call the handler or routine, and disable the ROM again.
544 The "wrapping" of the ROM routines is done by changing the ROM entry
545 point symbols in <tt/atari.inc/ to point to the wrapper functions.
547 For ROM functions which require input or output buffers, the wrappers
548 copy the data as required to buffers in low memory.
550 <sect2><#if output="info|latex2e"><tt/atarixl/ </#if>Load chunks<label id="xlchunks"><p>
552 An <tt/atarixl/ program contains three load chunks.
555 <item>"system check"<label id="syschkxl">&nl;
556 This load chunk is always loaded at address $2E00, and checks if the system is
557 suitable for running the program. It also checks if there is enough room between MEMLO
558 and the program start address to move the text mode screen buffer there. If any of the
559 checks return false, the loading of the program is aborted.&nl;
560 The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.
561 <item>"shadow RAM prepare"&nl;
562 The second load chunk gets loaded to the selected program load address (default $2400).
563 It moves the screen memory below the program load address, copies the character generator
564 from ROM to its new place in RAM, and copies the parts of the program which reside in
565 high memory below the ROM to their place. The high memory parts are included in this load chunk.&nl;
566 At the beginning of this load chunk there is a .bss area, which is not part of the
567 EXE file. Therefore the on-disk start address of this load chunk will be higher than the
568 selected start address. This .bss area (segment LOWBSS) contains the buffers for the
569 double buffering of ROM input and output data. If you add contents to this segment be aware
570 that the contents won't be zero initialized by the startup code.&nl;
571 The contents of this chunk come from the SRPREPCHNK memory area of the linker config file.
572 <item>main program&nl;
573 This load chunk is loaded just above the LOWBSS segment, replacing the code of
574 the previous load chunk. It contains all remaining code and data sections of the program,
575 including the startup code.&nl;
576 The contents of this chunk come from the RAM memory area of the linker config file.
579 <sect2>Moving screen memory below the program start address<p>
581 When setting a graphics mode, the ROM looks at the RAMTOP location. RAMTOP
582 describes the amount of installed memory in pages (RAMTOP is only one byte).
583 The screen memory and display list are placed immediately below RAMTOP.
585 Now in order to relocate the screen memory to lower memory, the startup code
586 puts a value into RAMTOP which causes the ROM routines to allocate the display
587 memory below the program start address and then it issues a ROM call to setup
588 the regular text mode.
590 <sect2>Selecting a good program load address<label id="loadaddr"><p>
592 Due to the movement of the screen memory below the program start, there are some
593 load addresses which are sub-optimal because they waste memory or prevent a
594 higher resolution graphics mode from being enabled.
596 There are restrictions at which addresses screen memory (display buffer and display
597 list) can be placed. The display buffer cannot cross a 4K boundary and a display
598 list cannot cross a 1K boundary.
600 The startup code takes this into account when moving the screen memory down.
601 If the program start address (aligned to the next lower page boundary) minus
602 the screen buffer size would result in a screen buffer which spans a 4K
603 boundary, the startup code lowers RAMTOP to this 4K boundary.&nl;
604 The size of the screen buffer in text mode is 960 ($3C0) bytes. So, for
605 example, a selected start address of $2300 would span the 4K boundary
606 at $2000. The startup code would adjust the RAMTOP value in such way that
607 the screen memory would be located just below this boundary (at $1C40).
608 This results in the area [$2000-$22FF] being wasted.
609 Additionally, the program might fail to load since the lowest address used
610 by the screen memory could be below MEMLO. (The lowest address used in this
611 example would be at $1C20, where the display list would allocated.)
613 These calculations are performed by the startup code (in the first two
614 load chunks), but the startup code only takes the default 40x24 text mode
615 into account. If the program later wants to load TGI drivers which set
616 a more memory consuming graphics mode, the user has to pick a higher
618 Using higher resolution modes there is a restriction in the ROM that it
619 doesn't expect RAMTOP to be at arbitrary values. The Atari memory modules
620 came only in 8K or 16K sizes, so the ROM expects RAMTOP to only have
621 values in 8K steps. Therefore, when using the highest resolution modes
622 the program start address must be at an 8K boundary.
625 <sect2>Character generator location<label id="chargenloc"><p>
627 The default <tt/atarixl/ linker config file (<tt/atarixl.cfg/) leaves the
628 character generator location at the same address where it is in ROM
629 ($E000). This has the disadvatage to split the upper memory into
630 two parts ([$D800-$DFFF] and
631 [$E400-$FFF9]). For applications which
632 require a large continuous upper memory area, an alternative linker
633 config file (<tt/atarixl-largehimem.cfg/) is provided. It relocates the
634 character generator to $D800, providing a single big upper
635 memory area at [$DC00-$FFF9].
637 With the character generator at a different address than in ROM, the routines
638 which enable and disable the ROM also have to update the chargen pointer.
639 This code is not enabled by default. In order to enable it,
640 uncomment the line which sets CHARGEN_RELOC in <tt/libsrc/atari/Makefile.inc/
641 and recompile the <tt/atarixl/ runtime library.
646 <sect1>Function keys<p>
648 Function keys are mapped to Atari + number key.
651 <sect1>Passing arguments to the program<p>
653 Command line arguments can be passed to <tt/main()/ when DOS supports it.
656 <item>Arguments are separated by spaces.
657 <item>Leading and trailing spaces around an argument are ignored.
658 <item>The first argument passed to <tt/main/ is the program name.
659 <item>A maximum number of 16 arguments (including the program name) are
666 The runtime for the Atari uses routines marked as <tt/.INTERRUPTOR/ for
667 interrupt handlers. Such routines must be written as simple machine language
668 subroutines and will be called automatically by the VBI handler code
669 when they are linked into a program. See the discussion of the <tt/.CONDES/
670 feature in the <htmlurl url="ca65.html" name="assembler manual">.
673 <sect1>Reserving a memory area inside a program<label id="memhole"><p>
675 (This section is primarily applicable to the <tt/atari/ target, but the
676 principles apply to <tt/atatixl/ as well.)
678 The Atari 130XE maps its additional memory into CPU memory in 16K
679 chunks at address $4000 to $7FFF. One might want to
680 prevent this memory area from being used by cc65. Other reasons to
681 prevent the use of some memory area could be to reserve space for the
682 buffers for display lists and screen memory.
684 The Atari executable format allows holes inside a program, e.g. one
685 part loads into $2E00 to $3FFF, going below the reserved
686 memory area (assuming a reserved area from $4000 to
687 $7FFF), and another part loads into $8000 to
690 Each load chunk of the executable starts with a 4 byte header which
691 defines its load address and size. In the following linker config files
692 these headers are named HEADER and SECHDR (for the MEMORY layout), and
693 accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout).
695 <sect2>Low code and high data example<p>
696 Goal: Create an executable with 2 load chunks which doesn't use the
697 memory area from $4000 to $7FFF. The CODE segment of
698 the program should go below $4000 and the DATA and RODATA
699 segments should go above $7FFF.
701 The main problem is that the EXE header generated by the cc65 runtime
702 lib is wrong. It defines a single load chunk with the sizes/addresses
703 of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments, in
704 fact, the whole user program (we're disregarding the "system check"
707 The contents of the EXE header come from the EXEHDR and MAINHDR segments.
708 The EXEHDR segment just contains the $FFFF value which is required
709 to be the first bytes of the EXE file.&nl;
710 The MAINHDR are defined in in crt0.s. This cannot be changed without
711 modifying and recompiling the cc65 atari runtime library. Therefore
712 the original contents of this segment must be discarded and be
713 replaced by a user created one. This discarding is done by assigning the
714 MAINHDR segment to the (new introduced) DISCARD memory area. The DISCARD memory area is
715 thrown away in the new linker config file (written to file "").
716 We add a new FSTHDR segment for the chunk header of the first chunk.
718 The user needs to create a customized linker config file which adds
719 new memory areas and segments to hold the new header data for the first load
720 chunk and the header data for the second load chunk. Also an assembly source file
721 needs to be created which defines the contents of the new header data
722 for the two load chunks.
725 This is an example of a modified cc65 Atari linker configuration file
729 __STACKSIZE__: value = $800 type = weak; # 2K stack
730 __RESERVED_MEMORY__: value = $0000, type = weak;
733 STARTADDRESS: default = $2E00;
736 ZP: start = $82, size = $7E, type = rw, define = yes;
738 HEADER: start = $0000, size = $2, file = %O; # first load chunk
740 FSTHDR: start = $0000, size = $4, file = %O; # second load chunk
741 RAMLO: start = %S, size = $4000 - %S, file = %O;
743 DISCARD: start = $4000, size = $4000, file = "";
745 SECHDR: start = $0000, size = $4, file = %O; # second load chunk
746 RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
749 EXEHDR: load = HEADER, type = ro;
751 MAINHDR: load = DISCARD, type = ro;
753 NEXEHDR: load = FSTHDR, type = ro; # first load chunk
754 STARTUP: load = RAMLO, type = ro, define = yes;
755 LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes;
756 INIT: load = RAMLO, type = ro, optional = yes;
757 CODE: load = RAMLO, type = ro, define = yes;
759 CHKHDR: load = SECHDR, type = ro; # second load chunk
760 RODATA: load = RAM, type = ro, define = yes;
761 DATA: load = RAM, type = rw, define = yes;
762 BSS: load = RAM, type = bss, define = yes;
764 ZEROPAGE: load = ZP, type = zp;
765 AUTOSTRT: load = RAM, type = ro; # defines program entry point
768 CONDES: segment = RODATA,
770 label = __CONSTRUCTOR_TABLE__,
771 count = __CONSTRUCTOR_COUNT__;
772 CONDES: segment = RODATA,
774 label = __DESTRUCTOR_TABLE__,
775 count = __DESTRUCTOR_COUNT__;
780 A new memory area DISCARD was added.
781 It gets loaded with the contents of the (now unused) MAINHDR segment. But the
782 memory area isn't written to the output file. This way the contents of
783 the MAINHDR segment get discarded.
785 The newly added NEXEHDR segment defines the correct chunk header for the
786 first intended load chunk. It
787 puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the
788 segments containing only code, into load chunk #1 (RAMLO memory area).
790 The header for the second load chunk comes from the new CHKHDR
791 segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load
792 chunk #2 (RAM memory area).
795 The contents of the new NEXEHDR and CHKHDR segments come from this
798 .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
799 .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
802 .word __STARTUP_LOAD__
803 .word __CODE_LOAD__ + __CODE_SIZE__ - 1
806 .word __RODATA_LOAD__
807 .word __BSS_LOAD__ - 1
812 cl65 -t atari -C split.cfg -o prog.com prog.c split.s
815 <sect2>Low data and high code example<p>
818 Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT,
819 CODE, BSS, ZPSAVE into high memory (split2.cfg):
823 __STACKSIZE__: value = $800 type = weak; # 2K stack
824 __RESERVED_MEMORY__: value = $0000, type = weak;
827 STARTADDRESS: default = $2E00;
830 ZP: start = $82, size = $7E, type = rw, define = yes;
832 HEADER: start = $0000, size = $2, file = %O; # first load chunk
834 FSTHDR: start = $0000, size = $4, file = %O; # second load chunk
835 RAMLO: start = %S, size = $4000 - %S, file = %O;
837 DISCARD: start = $4000, size = $4000, file = "";
839 SECHDR: start = $0000, size = $4, file = %O; # second load chunk
840 RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
843 EXEHDR: load = HEADER, type = ro; # discarded old EXE header
845 MAINHDR: load = DISCARD, type = ro;
847 NEXEHDR: load = FSTHDR, type = ro; # first load chunk
848 RODATA: load = RAMLO, type = ro, define = yes;
849 DATA: load = RAMLO, type = rw, define = yes;
851 CHKHDR: load = SECHDR, type = ro; # second load chunk
852 STARTUP: load = RAM, type = ro, define = yes;
853 INIT: load = RAM, type = ro, optional = yes;
854 CODE: load = RAM, type = ro, define = yes;
855 BSS: load = RAM, type = bss, define = yes;
857 ZEROPAGE: load = ZP, type = zp;
858 AUTOSTRT: load = RAM, type = ro; # defines program entry point
861 CONDES: segment = RODATA,
863 label = __CONSTRUCTOR_TABLE__,
864 count = __CONSTRUCTOR_COUNT__;
865 CONDES: segment = RODATA,
867 label = __DESTRUCTOR_TABLE__,
868 count = __DESTRUCTOR_COUNT__;
872 New contents for NEXEHDR and CHKHDR are needed (split2.s):
874 .import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__
875 .import __DATA_LOAD__, __RODATA_LOAD__
878 .word __RODATA_LOAD__
879 .word __DATA_LOAD__ + __DATA_SIZE__ - 1
882 .word __STARTUP_LOAD__
883 .word __BSS_LOAD__ - 1
888 cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s
891 <sect2>Final note<label id="memhole_final_note"><p>
893 There are two other memory areas which don't appear directly in the
894 linker config file. They are the stack and the heap.
896 The cc65 runtime lib places the stack location at the end of available
897 memory. This is dynamically set from the MEMTOP system variable at
898 startup. The heap is located in the area between the end of the BSS
899 segment and the top of the stack as defined by __STACKSIZE__.
901 If BSS and/or the stack shouldn't stay at the end of the program,
902 some parts of the cc65 runtime lib need to be replaced/modified.
904 common/_heap.s defines the location of the heap and atari/crt0.s
905 defines the location of the stack by initializing sp.
908 <sect1>Upgrading from an older cc65 version<p>
910 If you are using a customized linker config file you might get some errors
911 regarding the MAINHDR segment. Like this:
914 ld65: Error: Missing memory area assignment for segment `MAINHDR'
917 The old "HEADER" memory description contained six bytes: $FFFF
918 and the first and last memory addess of the program. For the "system
919 check" load chunk this had to be split into two memory assigments. The
920 "HEADER" now only contains the $FFFF. The main program's first
921 and last memory address were moved to a new segment, called "MAINHDR",
922 which in the new linker config file goes into its own memory area (also
923 called "MAINHDR").&nl;&nl;
924 A simple way to adapt your old linker config file is to add the
925 following line to the "SEGMENTS" section:
928 MAINHDR: load = HEADER, type = ro;
933 <sect1>Getting rid of the "system check" load chunk<label id="nosyschk"><p>
935 If, for some reason, you don't want to include the "system check" load
936 chunk, you can do so by defining the symbol <tt/__SYSTEM_CHECK__/ when linking the
937 program. The "system check" chunk doesn't include vital parts of the
938 program. So if you don't want the system checks, it is save to leave them out.
939 This is probably mostly interesting for debugging.
941 When using cl65, you can leave it out with this command line:
944 cl65 -Wl -D__SYSTEM_CHECK__=1 <arguments>
947 The value you assign to <tt/__SYSTEM_CHECK_/ doesn't matter. If the
948 <tt/__SYSTEM_CHECK__/ symbol is defined, the load chunk won't be included.
953 This software is provided 'as-is', without any expressed or implied
954 warranty. In no event will the authors be held liable for any damages
955 arising from the use of this software.
957 Permission is granted to anyone to use this software for any purpose,
958 including commercial applications, and to alter it and redistribute it
959 freely, subject to the following restrictions:
962 <item> The origin of this software must not be misrepresented; you must not
963 claim that you wrote the original software. If you use this software
964 in a product, an acknowledgment in the product documentation would be
965 appreciated but is not required.
966 <item> Altered source versions must be plainly marked as such, and must not
967 be misrepresented as being the original software.
968 <item> This notice may not be removed or altered from any source