mirror of
https://github.com/cc65/cc65.git
synced 2024-08-16 12:29:03 +00:00
297 lines
9.1 KiB
Plaintext
297 lines
9.1 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
<title>Atari 5200 specific information for cc65
|
|
<author>
|
|
<url url="mailto:chris@groessler.org" name="Christian Groessler"><newline>
|
|
|
|
<abstract>
|
|
An overview over the Atari 5200 runtime system as it is implemented for the
|
|
cc65 C compiler.
|
|
</abstract>
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
<sect>Overview<p>
|
|
|
|
This file contains an overview of the Atari 5200 runtime system as it comes
|
|
with the cc65 C compiler. It describes the memory layout, Atari 5200 specific header
|
|
files, available drivers, and any pitfalls specific to that platform.
|
|
|
|
Please note that Atari 5200 specific functions are just mentioned here, they are
|
|
described in detail in the separate <url url="funcref.html" name="function
|
|
reference">. Even functions marked as "platform dependent" may be available on
|
|
more than one platform. Please see the function reference for more
|
|
information.
|
|
|
|
|
|
<sect>Binary format<p>
|
|
|
|
The binary output format generated by the linker for the Atari 5200 target
|
|
is a cartridge image. It is of course
|
|
possible to change this behaviour by using a modified startup file and linker
|
|
config.
|
|
|
|
<sect>Memory layout<p>
|
|
|
|
cc65 generated programs with the default setup use the RAM space from $021C to
|
|
$3FFF. If you want to reserve memory for the display list and screen buffer
|
|
you should define the __RESERVED_MEMORY__ linker variable. The number
|
|
of bytes specified by __RESERVED_MEMORY__ are lowering the top of
|
|
memory, therefore the available
|
|
RAM memory for the program is $021C to $3FFF-__RESERVED_MEMORY__.
|
|
The default linker config file sets __RESERVED_MEMORY__ to $1E0
|
|
to reserve space for an optional CONIO text screen.
|
|
|
|
Special locations:
|
|
|
|
<descrip>
|
|
<tag/Text screen/
|
|
The text screen is only enabled if any of the CONIO output functions
|
|
is used in the program. Its size is 20x24 characters (Antic mode 6,
|
|
BASIC mode 1) by default. The text screen is located at $3E00. The
|
|
address of the screen memory is available at runtime in the variable
|
|
SAVMSC ($001B).<p>
|
|
If the program doesn't use any CONIO output functions it needs to setup its own
|
|
display list.
|
|
|
|
<tag/Stack/
|
|
The C runtime stack is located at $3FFF-__RESERVED_MEMORY__ and growing downwards.
|
|
|
|
<tag/Heap/
|
|
The C heap is located at the end of the program and grows towards the C
|
|
runtime stack.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
|
|
<sect>Platform specific header files<p>
|
|
|
|
Programs containing Atari 5200 specific code may use the <tt/atari5200.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:
|
|
|
|
<tscreen><verb>
|
|
...
|
|
OS.sdmctl = 0x00; // screen off
|
|
OS.color4 = 14; // white frame
|
|
tics = OS.rtclok[1] // get ticks
|
|
...
|
|
</verb></tscreen>
|
|
|
|
<sect1>Atari 5200 specific functions<p>
|
|
|
|
<itemize>
|
|
<item>waitvsync
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect1>Hardware access<p>
|
|
|
|
The following pseudo variables declared in the <tt/atari5200.h/ header
|
|
file do allow access to hardware located in the address space. Some
|
|
variables are structures, accessing the struct fields will access the
|
|
chip registers.
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
|
|
The <tt/GTIA_READ/ structure allows read access to the GTIA. The
|
|
<tt/GTIA_WRITE/ structure allows write access to the GTIA.
|
|
See the <tt/_gtia.h/ header file located in the include directory
|
|
for the declaration of the structure.
|
|
|
|
<tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
|
|
The <tt/POKEY_READ/ structure allows read access to the POKEY. The
|
|
<tt/POKEY_WRITE/ structure allows write access to the POKEY.
|
|
See the <tt/_pokey.h/ header file located in the include directory
|
|
for the declaration of the structure.
|
|
|
|
<tag><tt/ANTIC/</tag>
|
|
The <tt/ANTIC/ structure allows read access to the ANTIC.
|
|
See the <tt/_antic.h/ header file located in the include directory
|
|
for the declaration of the structure.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
<sect>Loadable drivers<p>
|
|
|
|
All drivers must be statically linked because no disk I/O is available.
|
|
The names in the parentheses denote the symbols to be used for static linking of the drivers.
|
|
|
|
|
|
<sect1>Graphics drivers<p>
|
|
|
|
No graphics drivers are currently available for the Atari 5200.
|
|
|
|
|
|
<sect1>Extended memory drivers<p>
|
|
|
|
No extended memory drivers are available for the Atari 5200.
|
|
|
|
|
|
<sect1>Joystick drivers<p>
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/atr5200std.joy (atr5200std_joy)/</tag>
|
|
A joystick driver for the standard Atari 5200 joystick is
|
|
available. Depending on the version of the 5200 console, two or four joysticks can be attached.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
<sect1>Mouse drivers<p>
|
|
|
|
No mouse drivers are available for the Atari 5200.
|
|
|
|
|
|
<sect1>RS232 device drivers<p>
|
|
|
|
No serial drivers are available for the Atari 5200.
|
|
|
|
|
|
|
|
<sect>Limitations<p>
|
|
|
|
|
|
<sect1>Direct console I/O<p>
|
|
|
|
The <tt/atari5200/ target uses Antic mode 6 (BASIC mode 1) for the console
|
|
screen by default. There are four colors available:
|
|
|
|
<itemize>
|
|
<item><tt/COLOR_WHITE/
|
|
<item><tt/COLOR_RED/
|
|
<item><tt/COLOR_GREEN/
|
|
<item><tt/COLOR_BLACK/
|
|
</itemize>
|
|
|
|
Note that the <tt/COLOR_GREEN/ and <tt/COLOR_RED/ colors aren't
|
|
exactly the same colors as the ones with the same name on the
|
|
<tt/atari/ target.
|
|
They are the colors which are available as <tt/COLOR_LIGHTGREEN/
|
|
and <tt/COLOR_LIGHTRED/ there.
|
|
|
|
One can set the color shadow registers directly with other colors.
|
|
Then the color defines from above will just become placeholders. In
|
|
this scenario it might be more convenient to use index values (0..3)
|
|
instead of the color defines. The index values specify which of the
|
|
system shadow color registers (<tt/COLOR0/ .. <tt/COLOR3/) to use.
|
|
|
|
The default console screen has a layout of 20x24 characters. An
|
|
alternative layout, 20x12, Antic mode 7, BASIC mode 2, is provided in
|
|
the file <tt/atari5200-conioscreen-20x12.o/.
|
|
|
|
Using <tt/atari5200-conioscreen-20x12.o/ is as simple as placing it on
|
|
the linker command line like this:
|
|
|
|
<tscreen><verb>
|
|
cl65 -t atari5200 myprog.c atari5200-conioscreen-20x12.o
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1>Disk I/O<p>
|
|
|
|
Disk I/O is not supported by the <tt/atari5200/ target. This means that
|
|
you cannot use any of the following functions (and a few others):
|
|
|
|
<itemize>
|
|
<item>fclose
|
|
<item>fopen
|
|
<item>fread
|
|
<item>fprintf
|
|
<item>fputc
|
|
<item>fscanf
|
|
<item>fwrite
|
|
<item>...
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect>Other hints<p>
|
|
|
|
<sect1>CAR format<p>
|
|
|
|
AtariROMMaker (<url url="https://www.wudsn.com/index.php/productions-atari800/tools/atarirommaker"> )
|
|
can be used to create a <tt/.CAR/ file from the binary ROM image cc65 generates.
|
|
This might be more convenient when working with emulators.
|
|
|
|
<sect1>Changing the splash screen<p>
|
|
|
|
The 5200 ROM displays a splash screen at startup with the name of the
|
|
game and the copyright year. The year information has a 'Year-2000'
|
|
problem, the first two digits are fixed in the ROM and are always "19".
|
|
|
|
<sect2>Changing the game name<p>
|
|
|
|
The runtime library provides a default game name which is "cc65
|
|
compiled". To change that, one has to link a file which puts data into
|
|
the "<tt/CARTNAME/" segment.
|
|
|
|
For reference, here's the default version used by the cc65 library:
|
|
<tscreen><verb>
|
|
.export __CART_NAME__: absolute = 1
|
|
.macpack atari
|
|
.segment "CARTNAME"
|
|
scrcode " cc"
|
|
.byte '6' + 32, '5' + 32 ; use playfield 1
|
|
scrcode " compiled"
|
|
</verb></tscreen>
|
|
|
|
'<tt/__CART_NAME__/' needs to be defined in order that the linker is
|
|
satisfied and doesn't try to include the version of the runtime library.
|
|
|
|
20 bytes are available in the <tt/CARTNAME/ segment (one line) for the
|
|
game/program name.
|
|
|
|
<sect2>Changing the copyright year / changing the cartridge type<p>
|
|
|
|
The century is hard-coded to 1900 by the ROM.
|
|
|
|
There are two digits which can be changed. For example "92" will give
|
|
"1992" on the screen.
|
|
|
|
The default used by the runtime library is
|
|
|
|
<tscreen><verb>
|
|
.export __CART_YEAR__: absolute = 1
|
|
.segment "CARTYEAR"
|
|
.byte '9' + 32,'8' + 32 ; "98", using playfield 1
|
|
</verb></tscreen>
|
|
|
|
If the second byte of the year in the <tt/CARTYEAR/ segment is 255,
|
|
the cartridge is seen as a 'diagnostic' cartridge, and the splash
|
|
screen and most of the other startup initializations are bypassed.
|
|
|
|
<sect>License<p>
|
|
|
|
This software is provided 'as-is', without any expressed or implied
|
|
warranty. In no event will the authors be held liable for any damages
|
|
arising from the use of this software.
|
|
|
|
Permission is granted to anyone to use this software for any purpose,
|
|
including commercial applications, and to alter it and redistribute it
|
|
freely, subject to the following restrictions:
|
|
|
|
<enum>
|
|
<item> The origin of this software must not be misrepresented; you must not
|
|
claim that you wrote the original software. If you use this software
|
|
in a product, an acknowledgment in the product documentation would be
|
|
appreciated but is not required.
|
|
<item> Altered source versions must be plainly marked as such, and must not
|
|
be misrepresented as being the original software.
|
|
<item> This notice may not be removed or altered from any source
|
|
distribution.
|
|
</enum>
|
|
|
|
</article>
|