From 59d89796d50f2eec8148e57b0da16d406c6eed84 Mon Sep 17 00:00:00 2001 From: cuz Date: Sun, 14 Dec 2003 21:39:33 +0000 Subject: [PATCH] Added plus/4 docs git-svn-id: svn://svn.cc65.org/cc65/trunk@2759 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/Makefile | 3 +- doc/c128.sgml | 4 +- doc/c64.sgml | 2 +- doc/index.sgml | 3 + doc/plus4.sgml | 247 +++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 255 insertions(+), 4 deletions(-) create mode 100644 doc/plus4.sgml diff --git a/doc/Makefile b/doc/Makefile index 8e8275f00..8a94aca64 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -23,7 +23,8 @@ SGML = ar65.sgml \ index.sgml \ intro.sgml \ ld65.sgml \ - library.sgml + library.sgml \ + plus4.sgml TXT = $(SGML:.sgml=.txt) HTML = $(SGML:.sgml=.html) diff --git a/doc/c128.sgml b/doc/c128.sgml index 91f61f9f9..36d182f18 100644 --- a/doc/c128.sgml +++ b/doc/c128.sgml @@ -2,7 +2,7 @@
-C128 specific information for cc65 +<title>Commodore 128 specific information for cc65 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> <date>2003-12-14 @@ -301,4 +301,4 @@ freely, subject to the following restrictions: - + diff --git a/doc/c64.sgml b/doc/c64.sgml index 53ae5ba2e..3b56e2d5f 100644 --- a/doc/c64.sgml +++ b/doc/c64.sgml @@ -2,7 +2,7 @@ <article> -<title>C64 specific information for cc65 +<title>Commodore 64 specific information for cc65 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> <date>2003-09-23 diff --git a/doc/index.sgml b/doc/index.sgml index f20086195..eedac81ce 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -93,6 +93,9 @@ Main documentation page, contains links to other available stuff. <tag><htmlurl url="c64.html" name="c64.html"></tag> Topics specific to the Commodore 64. + <tag><htmlurl url="plus4.html" name="plus4.html"></tag> + Topics specific to the Commodore Plus/4. + </descrip> diff --git a/doc/plus4.sgml b/doc/plus4.sgml new file mode 100644 index 000000000..712afbabe --- /dev/null +++ b/doc/plus4.sgml @@ -0,0 +1,247 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore Plus/4 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 Plus/4 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 Plus/4 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, Plus/4 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that Plus/4 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. + +Since the Plus/4 and the Commodore 16/116 are almost identical (the latter are +missing the 6551 ACIA and do only have 16KB of memory), the <htmlurl +url="c16.html" name="C16 documentation"> is also worth a look. The difference +between both targets is that the Plus/4 runtime uses banking to support full +64K RAM, while the C16 does not use banking and supports up to 32K RAM. +Because banking is not needed, most C16 programs will be somewhat smaller than +the same program compiled for the Plus/4. However, programs compiled for the +C16 will always run on the Plus/4, while the reverse is not necessarily true. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Plus/4 +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 kernal and basic +banked out. This gives a usable memory range of $1000 - $FD00. +Having the kernal and basic ROMs banked out means, that no ROM entry points +may be called directly from user code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $C00 (as in the standard setup). + + <tag/Color RAM/ + The color RAM is located at $800 (standard location). + + <tag/Stack/ + The C runtime stack is located at $FCFF 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 Plus/4 specific code may use the <tt/plus4.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/plus4.h/ and declares several functions +common to all CBM platforms. + +Please note that most of the header file declarations from the <tt/plus4.h/ +header file are shared between the C16 and Plus/4 configurations. For this +reason, most of it is located in a common header file named <tt/cbm264.h/. + + + +<sect1>Plus/4 specific functions<p> + +There are currently no special Plus/4 functions. + + +<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/plus4.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/TED/</tag> + The <tt/TED/ structure allows access to the TED chip. See the + <tt/_ted.h/ header file located in the include directory for the + declaration of the structure. + + <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> + +No graphics drivers are currently available for the Plus/4. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Plus/4. + + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/plus4-stdjoy.joy/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the Plus/4. + +</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/plus4-stdser.ser/</tag> + Driver for the 6551 ACIA chip built into the Plus/4 Supports up to 19200 + baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note + that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts flow + control because of a full buffer. + + Note that you need an adapter to use the builtin port, since the output + levels available at the user port don't follow the RS232 standard. + +</descrip><p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line argument passing is currently not supported for the Plus/4. + + +<sect1>Interrupts<p> + +The runtime for the Plus/4 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> + + + + -- 2.39.5