<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.71">
<TITLE>Commodore PET-specific information for cc65</TITLE>
</HEAD>
<BODY>
<H1>Commodore PET-specific information for cc65</H1>
<H2>
<A HREF="mailto:uz@cc65.org">Ullrich von Bassewitz</A>,<BR>
<A HREF="mailto:polluks@sdf.lonestar.org">Stefan A. Haubenthal</A></H2>
<HR>
<EM>An overview over the PET runtime system as it is implemented for the cc65 C
compiler.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="pet.html#s1">Overview</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="pet.html#s2">Binary format</A></H2>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="pet.html#s3">Memory layout</A></H2>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="pet.html#s4">Platform-specific header files</A></H2>
<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="pet.html#ss4.1">PET-specific functions</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="pet.html#ss4.2">CBM-specific functions</A>
<LI><A NAME="toc4.3">4.3</A> <A HREF="pet.html#ss4.3">Hardware access</A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="pet.html#s5">Loadable drivers</A></H2>
<UL>
<LI><A NAME="toc5.1">5.1</A> <A HREF="pet.html#ss5.1">Graphics drivers</A>
<LI><A NAME="toc5.2">5.2</A> <A HREF="pet.html#ss5.2">Extended memory drivers</A>
<LI><A NAME="toc5.3">5.3</A> <A HREF="pet.html#ss5.3">Joystick drivers</A>
<LI><A NAME="toc5.4">5.4</A> <A HREF="pet.html#ss5.4">Mouse drivers</A>
<LI><A NAME="toc5.5">5.5</A> <A HREF="pet.html#ss5.5">RS232 device drivers</A>
</UL>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="pet.html#s6">Limitations</A></H2>
<P>
<H2><A NAME="toc7">7.</A> <A HREF="pet.html#s7">Other hints</A></H2>
<UL>
<LI><A NAME="toc7.1">7.1</A> <A HREF="pet.html#ss7.1">Passing arguments to the program</A>
<LI><A NAME="toc7.2">7.2</A> <A HREF="pet.html#ss7.2">Program return code</A>
<LI><A NAME="toc7.3">7.3</A> <A HREF="pet.html#ss7.3">Interrupts</A>
<LI><A NAME="toc7.4">7.4</A> <A HREF="pet.html#ss7.4">Using extended memory</A>
</UL>
<P>
<H2><A NAME="toc8">8.</A> <A HREF="pet.html#s8">License</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<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.</P>
<P>Please note that PET-specific functions are just mentioned here, they are
described in detail in the separate
<A HREF="funcref.html">function reference</A>. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Binary format</A></H2>
<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, which calls the
machine language part via SYS. 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.</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Memory layout</A></H2>
<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.</P>
<P>Special locations:</P>
<P>
<DL>
<DT><B>Text screen</B><DD>
<P>The text screen is located at $8000.</P>
<DT><B>Stack</B><DD>
<P>The C runtime stack is located at $7FFF and growing downwards.</P>
<DT><B>Heap</B><DD>
<P>The C heap is located at the end of the program and grows towards the C
runtime stack.</P>
</DL>
</P>
<H2><A NAME="s4">4.</A> <A HREF="#toc4">Platform-specific header files</A></H2>
<P>Programs containing PET-specific code may use the <CODE>pet.h</CODE> or <CODE>cbm.h</CODE>
header files. Using the later may be an option when writing code for more than
one CBM platform, since it includes <CODE>pet.h</CODE> and declares several functions
common to all CBM platforms.</P>
<H2><A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">PET-specific functions</A>
</H2>
<P>There are currently no special PET functions.</P>
<H2><A NAME="ss4.2">4.2</A> <A HREF="#toc4.2">CBM-specific functions</A>
</H2>
<P>Some functions are available for all (or at least most) of the Commodore
machines. See the
<A HREF="funcref.html">function reference</A> for
declaration and usage.</P>
<P>
<UL>
<LI>cbm_close</LI>
<LI>cbm_closedir</LI>
<LI>cbm_k_setlfs</LI>
<LI>cbm_k_setnam</LI>
<LI>cbm_k_load</LI>
<LI>cbm_k_save</LI>
<LI>cbm_k_open</LI>
<LI>cbm_k_close</LI>
<LI>cbm_k_readst</LI>
<LI>cbm_k_chkin</LI>
<LI>cbm_k_ckout</LI>
<LI>cbm_k_basin</LI>
<LI>cbm_k_bsout</LI>
<LI>cbm_k_clrch</LI>
<LI>cbm_load</LI>
<LI>cbm_open</LI>
<LI>cbm_opendir</LI>
<LI>cbm_read</LI>
<LI>cbm_readdir</LI>
<LI>cbm_save</LI>
<LI>cbm_write</LI>
<LI>get_tv</LI>
</UL>
</P>
<H2><A NAME="ss4.3">4.3</A> <A HREF="#toc4.3">Hardware access</A>
</H2>
<P>The following pseudo variables declared in the <CODE>pet.h</CODE> 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.</P>
<P>
<DL>
<DT><B><CODE>PIA1, PIA2</CODE></B><DD>
<P>Access to the two PIA (peripheral interface adapter) chips is available via
the <CODE>PIA1</CODE> and <CODE>PIA2</CODE> variables. The structure behind these variables
is explained in <CODE>_pia.h</CODE>.</P>
<DT><B><CODE>VIA</CODE></B><DD>
<P>The <CODE>VIA</CODE> structure allows access to the VIA (versatile interface
adapter). See the <CODE>_6522.h</CODE> header file located in the include
directory for the declaration of the structure.</P>
</DL>
</P>
<H2><A NAME="s5">5.</A> <A HREF="#toc5">Loadable drivers</A></H2>
<P>The names in the parentheses denote the symbols to be used for static linking of the drivers.</P>
<H2><A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">Graphics drivers</A>
</H2>
<P>No graphics drivers are currently available for the PET.</P>
<H2><A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Extended memory drivers</A>
</H2>
<P>No extended memory drivers are currently available for the PET.</P>
<H2><A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">Joystick drivers</A>
</H2>
<P>The default drivers, <CODE>joy_stddrv (joy_static_stddrv)</CODE>, point to <CODE>pet-stdjoy.joy (pet_stdjoy_joy)</CODE>.</P>
<P>
<DL>
<DT><B><CODE>pet-ptvjoy.joy (pet_ptvjoy_joy)</CODE></B><DD>
<P>Driver for the Protovision 4-player adapter contributed by Groepaz. See
<A HREF="http://www.protovision-online.de/hardw/4_player.php?language=en">Protovision shop</A> for prices and building instructions. Up to two
joysticks are supported.</P>
<DT><B><CODE>pet-stdjoy.joy (pet_stdjoy_joy)</CODE></B><DD>
<P>Driver for the standard PET userport joystick.</P>
</DL>
</P>
<H2><A NAME="ss5.4">5.4</A> <A HREF="#toc5.4">Mouse drivers</A>
</H2>
<P>No mouse drivers are currently available for the PET.</P>
<H2><A NAME="ss5.5">5.5</A> <A HREF="#toc5.5">RS232 device drivers</A>
</H2>
<P>No serial drivers are currently available for the PET.</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Limitations</A></H2>
<H2><A NAME="s7">7.</A> <A HREF="#toc7">Other hints</A></H2>
<H2><A NAME="ss7.1">7.1</A> <A HREF="#toc7.1">Passing arguments to the program</A>
</H2>
<P>Command-line arguments can be passed to <CODE>main()</CODE>. Since that is not
supported directly by BASIC, the following syntax was chosen:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>
<OL>
<LI>Arguments are separated by spaces.</LI>
<LI>Arguments may be quoted.</LI>
<LI>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.</LI>
<LI>The first argument passed to <CODE>main()</CODE> is the program name.</LI>
<LI>A maximum number of 10 arguments (including the program name) are
supported.</LI>
</OL>
</P>
<H2><A NAME="ss7.2">7.2</A> <A HREF="#toc7.2">Program return code</A>
</H2>
<P>The program return code (low byte) is passed back to BASIC by use of the
<CODE>ST</CODE> variable.</P>
<H2><A NAME="ss7.3">7.3</A> <A HREF="#toc7.3">Interrupts</A>
</H2>
<P>The runtime for the PET uses routines marked as <CODE>.INTERRUPTOR</CODE> 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 <CODE>.CONDES</CODE>
feature in the
<A HREF="ca65.html">assembler manual</A>.</P>
<H2><A NAME="ss7.4">7.4</A> <A HREF="#toc7.4">Using extended memory</A>
</H2>
<P>The extended memory at $9000 of the CBM 8x96 may be added to the heap by using
the following code:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* Check for the existence of RAM */
if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) {
/* Add it to the heap */
_heapadd ((void *) 0x9000, 0x2000);
}
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="s8">8.</A> <A HREF="#toc8">License</A></H2>
<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.</P>
<P>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:</P>
<P>
<OL>
<LI> 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.</LI>
<LI> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.</LI>
<LI> This notice may not be removed or altered from any source
distribution.</LI>
</OL>
</P>
</BODY>
</HTML>