From: Florent Flament Date: Wed, 11 Jan 2017 22:12:30 +0000 (+0100) Subject: Add Atari 2600 documentation X-Git-Tag: V2.16~55^2 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=refs%2Fpull%2F365%2Fhead;p=cc65 Add Atari 2600 documentation --- diff --git a/doc/atari2600.sgml b/doc/atari2600.sgml new file mode 100644 index 000000000..ae1b6cb5c --- /dev/null +++ b/doc/atari2600.sgml @@ -0,0 +1,124 @@ + + +
+ +Atari 2600 specific information for cc65 +<author> +<url url="mailto:contact@florentflament.com" name="Florent Flament"><newline> +<date>2017-01-11 + +<abstract> +An overview over the Atari 2600 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 2600 runtime system as it +comes with the cc65 C compiler. It describes the memory layout, Atari +2600 specific header files and any pitfalls specific to that platform. + +<sect>Binary format<p> + +The default binary output format generated by the linker for the Atari +2600 target is a 4K cartridge image. + +<sect>Memory layout<p> + +cc65 generated programs with the default setup can use RAM from +$0080 to $00FF - __STACKSIZE__, where __STACKSIZE__ is +the size of the system stack with a default value of 16 bytes. The +size of the system stack can be customized by defining the +__STACKSIZE__ linker variable. + +Special locations: + +<descrip> + <tag/Stack/ The C runtime stack is located at $00FF - + __STACKSIZE__ and growing downwards. + + <tag/Heap/ The C heap is located at $0080 and grows upwards. + +</descrip><p> + +<sect>Start-up condition<p> + +When powered-up, the Atari 2600 TIA registers contain random +values. During the initialization phase, the start-up code needs to +initialize the TIA registers to sound values (or else the console has +an unpredictable behavior). In this implementation, zeros are written +to all of TIA registers during the start-up phase. + +Note that RIOT registers (mostly timers) are left uninitialized, as +they don't have any consequence on the console behavior. + +<sect>Platform specific header files<p> + +Programs containing Atari 2600 specific code may use the +<tt/atari2600.h/ header file. + +The following pseudo variables declared in the <tt/atari2600.h/ header +file allow access to the Atari 2600 TIA & RIOT chips registers. + +<descrip> + + <tag><tt/TIA/</tag> The <tt/TIA/ structure allows read/write access + to the Atari 2600 TIA chip registers. See the <tt/_tia.h/ header + file located in the include directory for the declaration of the + structure. Also refer to the Stella Programmer's Guide by Steve + Wright for a detailed description of the chip and its registers. + + <tag><tt/RIOT/</tag> The <tt/RIOT/ structure allows read/write + access to the Atari 2600 RIOT chip registers. See the + <tt/_riot.h/ header file located in the include directory for the + declaration of the structure. Also refer to the Stella Programmer's + Guide by Steve Wright for a detailed description of the chip and its + registers. + +</descrip><p> + + +<sect>Loadable drivers<p> + +There are no drivers for the Atari 2600. + + +<sect>Limitations<p> + +TBD + + +<sect>Other hints<p> + +One may write a custom linker configuration file to tune the memory +layout of a program. See the <tt/atari2600.cfg/ file in the cfg +directory as a starting point. + + +<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> diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 2c43a9b50..da0233c62 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -4583,6 +4583,7 @@ compiler, depending on the target system selected: <itemize> <item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/ <item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ +<item><tt/__ATARI2600__/ - Target system is <tt/atari2600/ <item><tt/__ATARI5200__/ - Target system is <tt/atari5200/ <item><tt/__ATARI__/ - Target system is <tt/atari/ or <tt/atarixl/ <item><tt/__ATARIXL__/ - Target system is <tt/atarixl/ diff --git a/doc/cc65.sgml b/doc/cc65.sgml index 3e59d4cf0..80dba89b8 100644 --- a/doc/cc65.sgml +++ b/doc/cc65.sgml @@ -752,6 +752,10 @@ The compiler defines several macros at startup: This macro is defined if the target is the enhanced Apple //e (-t apple2enh). + <tag><tt>__ATARI2600__</tt></tag> + + This macro is defined if the target is the Atari 2600 game console. + <tag><tt>__ATARI5200__</tt></tag> This macro is defined if the target is the Atari 5200 game console. diff --git a/doc/index.sgml b/doc/index.sgml index 44b58ef5e..9b7ab794e 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -116,6 +116,9 @@ <tag><htmlurl url="atari.html" name="atari.html"></tag> Topics specific to the Atari 8-bit machines. + <tag><htmlurl url="atari2600.html" name="atari2600.html"></tag> + Topics specific to the Atari 2600 Game Console. + <tag><htmlurl url="atari5200.html" name="atari5200.html"></tag> Topics specific to the Atari 5200 Game Console. diff --git a/doc/intro.sgml b/doc/intro.sgml index d92fd1d20..bb8965c60 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -335,6 +335,35 @@ your harddrive directly. to the DOS menu. Your C program should wait for a keypress if you want to see any output. +<sect2>Stella<p> +Available at <url +url="http://stella.sourceforge.net">: + +Stella is a multi-platform Atari 2600 VCS emulator. The latest version +is available on the emulator's website. It is also available through +the package manager of most Linux distributions (Fedora, Ubuntu, ..). + +Compile the Atari 2600 sample with + +<tscreen><verb> +make SYS=atari2600 samples +</verb></tscreen> + +Then execute it with + +<tscreen><verb> +stella samples/atari2600hello +</verb></tscreen> + +<sect2>Harmony Cartridge<p> +Available at <url +url="http://harmony.atariage.com/Site/Harmony.html">: + +The Harmony Cartridge allows running any Atari 2600 binary on real +hardware. The binary must be copied on an SD card, to be inserted in +the Harmony Cartridge. It can then be inserted on an Atari 2600 +console, and run any binary on the SD card. + <sect1>Atmos diff --git a/doc/ld65.sgml b/doc/ld65.sgml index 448157ce0..5687aa8ab 100644 --- a/doc/ld65.sgml +++ b/doc/ld65.sgml @@ -156,6 +156,7 @@ Here is a description of all of the command-line options: <item>module <item>apple2 <item>apple2enh + <item>atari2600 <item>atari <item>atarixl <item>atmos