From 95c7d550e5795b431c64b6db1e66028f2b16b7c2 Mon Sep 17 00:00:00 2001 From: cuz Date: Tue, 24 May 2005 20:51:56 +0000 Subject: [PATCH] Added PET docs by Stefan Haubenthal git-svn-id: svn://svn.cc65.org/cc65/trunk@3516 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/index.sgml | 3 + doc/pet.sgml | 241 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 244 insertions(+) create mode 100644 doc/pet.sgml diff --git a/doc/index.sgml b/doc/index.sgml index 8b8e0ed1d..18d006f57 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -109,6 +109,9 @@ Main documentation page, contains links to other available stuff. Topics specific to the Atari Lynx Game Console. + + Topics specific to the Commodore PET machines. + Topics specific to the Commodore Plus/4. diff --git a/doc/pet.sgml b/doc/pet.sgml new file mode 100644 index 000000000..53fc67f98 --- /dev/null +++ b/doc/pet.sgml @@ -0,0 +1,241 @@ + + +
+ +Commodore PET specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2005-05-24 + +<abstract> +An overview over the PET 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 PET runtime system as it comes with the +cc65 C compiler. It describes the memory layout, PET specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that PET 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 PET 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 and BASIC ROM enabled, which gives a usable memory range of +$0400 - $7FFF (32KB machine). +All ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $8000. + + <tag/Stack/ + The C runtime stack is located at $7FFF 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 PET specific code may use the <tt/pet.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/pet.h/ and declares several functions +common to all CBM platforms. + + +<sect1>PET specific functions<p> + +There are currently no special PET 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/pet.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/PIA1, PIA2/</tag> + Access to the two PIA (peripheral interface adapter) chips is available via + the <tt/PIA1/ and <tt/PIA2/ variables. The structure behind these variables + is explained in <tt/_pia.h/. + + <tag><tt/VIA/</tag> + The <tt/VIA/ structure allows access to the VIA (versatile interface + adapter). See the <tt/_6522.h/ header file located in the include + directory for the declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the PET. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the PET. + + +<sect1>Joystick drivers<p> + +No joystick drivers are currently available for the PET. + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the PET. + + +<sect1>RS232 device drivers<p> + +No serial drivers are currently available for the PET. + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Using extended memory<p> + +The extended memory at $9000 of the CBM 8x96 may be added to the heap by using +the following code: + +<tscreen><verb> + /* Check for the existence of RAM */ + if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) { + /* Add it to the heap */ + _heapadd ((void *) 0x9000, 0x2000); + } +</verb></tscreen> + + +<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