diff --git a/doc/Makefile b/doc/Makefile index fff4315d9..8e8275f00 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,6 +7,7 @@ SGML = ar65.sgml \ atari.sgml \ + c128.sgml \ c64.sgml \ ca65.sgml \ ca65html.sgml \ diff --git a/doc/c128.sgml b/doc/c128.sgml new file mode 100644 index 000000000..91f61f9f9 --- /dev/null +++ b/doc/c128.sgml @@ -0,0 +1,304 @@ + + +
+ +C128 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-14 + +<abstract> +An overview over the C128 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 C128 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C128 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that C128 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 C128 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. Note that this is a non standard memory layout, and that +there is no "memory configuration index" for this layout. This means that +special case has to be taken when changing the configuration, or calling any +code that does this. The memory configuration register at $FF00 should +be saved and restored instead of relying on the memory configuration index +stored in the zero page. + +The setup gives a usable memory range of $1C00 - $CFFF. Having +just the kernal ROM mapped in 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. + + <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 C128 specific code may use the <tt/c128.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/c128.h/ and declares several functions +common to all CBM platforms. + + +<sect1>C128 specific functions<p> + +The functions listed below are special for the C128. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>toggle_videomode +<item>c64mode +<item>fast +<item>slow +</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/c128.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/VDC/</tag> + The <tt/VDC/ structure allows access to the VDC (the video display + controller). See the <tt/_vdc.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> + +Note: The graphics drivers for the VDC are incompatible with the extended +memory drivers using the VDC memory! + +<descrip> + <tag><tt/c128-vdc.tgi/</tag> + This driver uses the 80 column display and features a resolution of 640*200 + with two colors and an adjustable palette (that means that the two colors + can be choosen out of the 16 VDC colors). + + <tag><tt/c128-vdc2.tgi/</tag> + This driver uses the 80 column display and features a resolution of 640*480 + with two colors and an adjustable palette (that means that the two colors + can be choosen out of the 16 VDC colors). +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c128-georam.emd/</tag> + A driver for the GeoRam cartridge. The driver will always assume 2048 pages + of 256 bytes each. There are no checks, so if your program knows better, + just go ahead. + + <tag><tt/c128-ram.emd/</tag> + An extended memory driver for the RAM in page 1. The common memory area is + excluded, so this driver supports 251 pages of 256 bytes each. + + <tag><tt/c128-ramcart.emd/</tag> + A driver for the RamCart 64/128. Will test the hardware for the available + RAM. + + <tag><tt/c128-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/c128-vdc.emd/</tag> + A driver for the VDC memory of the C128. Autodetects the amount of memory + available (16 or 64K) and offers 64 or 256 pages of 256 bytes each. Note: + This driver is incompatible with any of the graphics drivers using the VDC! + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c128-ptvjoy.joy/</tag> + Driver for the Protovision 4-player adapter. See + <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices + and building instructions. Up to four joysticks are supported. + + <tag><tt/c128-stdjoy.joy/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the C128. + +</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/c128-swlink.ser/</tag> + Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow + control (RTS/CTS) and interrupt driven receives. Note that because of the + peculiarities of the 6551 chip together with the use of the NMI, transmits + are not interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + + The driver uses the RS232 variables and buffers of the kernal (buffers at + $C00 and $D00). + +</descrip><p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line argument passing is currently not supported for the C128. + + +<sect1>Interrupts<p> + +The runtime for the C128 uses routines marked as <tt/.CONDES/ type 2 for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<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> + + + + diff --git a/doc/c64.sgml b/doc/c64.sgml index fc71e5cb1..53ae5ba2e 100644 --- a/doc/c64.sgml +++ b/doc/c64.sgml @@ -2,7 +2,7 @@ <article> -<title>c64 specific information for cc65 +<title>C64 specific information for cc65 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> <date>2003-09-23 @@ -166,7 +166,8 @@ setup without any memory loss or need for a changed configuration. <tag><tt/c64-georam.emd/</tag> A driver for the GeoRam cartridge. The driver will always assume 2048 pages - of 256 bytes each. + of 256 bytes each. There are no checks, so if your program knows better, + just go ahead. <tag><tt/c64-ram.emd/</tag> A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48 @@ -227,7 +228,10 @@ does not exist). <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. + control (RTS/CTS) and interrupt driven receives. Note that because of the + peculiarities of the 6551 chip together with the use of the NMI, transmits + are not interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. </descrip><p> diff --git a/doc/index.sgml b/doc/index.sgml index 9e07e18ab..f20086195 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -87,6 +87,9 @@ Main documentation page, contains links to other available stuff. <tag><htmlurl url="atari.html" name="atari.html"></tag> Topics specific to the Atari 8 bit machines. + <tag><htmlurl url="c128.html" name="c128.html"></tag> + Topics specific to the Commodore 128. + <tag><htmlurl url="c64.html" name="c64.html"></tag> Topics specific to the Commodore 64.