From: cuz Date: Tue, 23 Sep 2003 19:53:54 +0000 (+0000) Subject: First version of the c64 platform specific docs X-Git-Tag: V2.12.0~1328 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=84bbb0c27038ae4b59bdcdb38bdbcb60080766cc;p=cc65 First version of the c64 platform specific docs git-svn-id: svn://svn.cc65.org/cc65/trunk@2443 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- diff --git a/doc/c64.sgml b/doc/c64.sgml new file mode 100644 index 000000000..c89fb3c98 --- /dev/null +++ b/doc/c64.sgml @@ -0,0 +1,256 @@ + + +
+ +c64 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-09-23 + +<abstract> +An overview over the C64 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 C64 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C64 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that C64 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl 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 standard binary output format generated by the linker for the C64 target +is a machine language program with a one line BASIC stub. This means that a +program can be loaded as BASIC program and started with RUN. 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 run with the I/O area and the +kernal ROM enabled. The BASIC ROM is disabled, which gives a usable memory +range of $0800 - $CFFF. This means that kernal entry points may +be called directly, but using the BASIC ROM is not possible without additional +code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $400 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $CFFF and growing downwards. +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/c64.h/ and declares several functions +common to all CBM platforms. + + +<sect1>C64 specific functions<p> + +The functions listed below are special for the C64. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>get_ostype +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/c64.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/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC II (the graphics + controller). See the <tt/_vic2.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/SID/</tag> + The <tt/SID/ structure allows access to the SID (the sound interface + device). See the <tt/_sid.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/CIA1, CIA2/</tag> + Access to the two CIA (complex interface adapater) chips is available via + the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables + is explained in <tt/_cia.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the C64 at $D800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<sect1>Graphics drivers<p> + +All available graphics drivers for the TGI interface will use the space below +the I/O area and kernal ROM, so you can have hires graphics in the standard +setup without any memory loss or need for a changed configuration. + +<descrip> + <tag><tt/c64-hi.tgi/</tag> + This driver features a resolution of 320*200 with two colors and an + adjustable palette (that means that the two colors can be choosen out of a + palette of the 16 C64 colors). +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c64-georam.emd/</tag> + A driver for the GeoRam cartridge. The driver will always assume 2048 pages + of 256 bytes each. + + <tag><tt/c64-ram.emd/</tag> + A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48 + 256 byte pages. Please note that this driver is incompatible with any of the + graphics drivers! + + <tag><tt/c64-ramcart.emd/</tag> + A driver for the RamCart 64/128. Will test the hardware for the available + RAM. + + <tag><tt/c64-reu.emd/</tag> + A driver for the CBM REUs. The driver will determine from the connected REU + if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, + but since there are no range checks, the application can use more memory if + it has better knowledge about the hardware than the driver. + + <tag><tt/c64-vdc.emd/</tag> + A driver for the VDC memory of the C128. Can be used if the program is + running in C64 mode of the C128. Autodetects the amount of memory available + (16 or 64K) and offers 64 or 256 pages of 256 bytes each. + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c64-stdjoy.joy/</tag> + Supports up to two standard joysticks connected to the joysticks port of + the C64. + +</descrip><p> + + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/c64-swlink.ser/</tag> + Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow + control (RTS/CTS) and interrupt driven receives. + +</descrip><p> + + + +<sect>Other hints<p> + + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<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> + + +