/usr/share/doc/cc65-doc/html/vic20.html

<!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.72">
 <TITLE>Commodore VIC20 (aka VC20) specific information for cc65</TITLE>
</HEAD>
<BODY>
<H1>Commodore VIC20 (aka VC20) 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>2014-04-12
<HR>
<EM>An overview over the VIC20 runtime system as it is implemented for the cc65 C
compiler.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="vic20.html#s1">Overview</A></H2>

<P>
<H2><A NAME="toc2">2.</A> <A HREF="vic20.html#s2">Binary format</A></H2>

<P>
<H2><A NAME="toc3">3.</A> <A HREF="vic20.html#s3">Memory layout</A></H2>

<P>
<H2><A NAME="toc4">4.</A> <A HREF="vic20.html#s4">Platform-specific header files</A></H2>

<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="vic20.html#ss4.1">VIC20-specific functions</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="vic20.html#ss4.2">CBM-specific functions</A>
<LI><A NAME="toc4.3">4.3</A> <A HREF="vic20.html#ss4.3">Hardware access</A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="vic20.html#s5">Loadable drivers</A></H2>

<UL>
<LI><A NAME="toc5.1">5.1</A> <A HREF="vic20.html#ss5.1">Graphics drivers</A>
<LI><A NAME="toc5.2">5.2</A> <A HREF="vic20.html#ss5.2">Extended memory drivers</A>
<LI><A NAME="toc5.3">5.3</A> <A HREF="vic20.html#ss5.3">Joystick drivers</A>
<LI><A NAME="toc5.4">5.4</A> <A HREF="vic20.html#ss5.4">Mouse drivers</A>
<LI><A NAME="toc5.5">5.5</A> <A HREF="vic20.html#ss5.5">RS232 device drivers</A>
</UL>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="vic20.html#s6">Limitations</A></H2>

<P>
<H2><A NAME="toc7">7.</A> <A HREF="vic20.html#s7">Other hints</A></H2>

<UL>
<LI><A NAME="toc7.1">7.1</A> <A HREF="vic20.html#ss7.1">Escape code</A>
<LI><A NAME="toc7.2">7.2</A> <A HREF="vic20.html#ss7.2">Passing arguments to the program</A>
<LI><A NAME="toc7.3">7.3</A> <A HREF="vic20.html#ss7.3">Program return code</A>
<LI><A NAME="toc7.4">7.4</A> <A HREF="vic20.html#ss7.4">Using extended memory</A>
<LI><A NAME="toc7.5">7.5</A> <A HREF="vic20.html#ss7.5">Interrupts</A>
</UL>
<P>
<H2><A NAME="toc8">8.</A> <A HREF="vic20.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 VIC20 runtime system as it comes with the
cc65 C compiler. It describes the memory layout, VIC20-specific header files,
available drivers, and any pitfalls specific to that platform.</P>
<P>Please note that VIC20-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 VIC20 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 unexpanded memory
(RAM at $A000 - $BFFF may be used for the heap),
which gives a usable memory range of $1000 - $1DFF.
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 $1E00 (as in the standard setup).</P>

<DT><B>Stack</B><DD>
<P>The C runtime stack is located at $1DFF 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 VIC20-specific code may use the <CODE>vic20.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>vic20.h</CODE> and declares several functions
common to all CBM platforms.</P>


<H2><A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">VIC20-specific functions</A>
</H2>


<P>There are currently no special VIC20 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>vic20.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>VIC</CODE></B><DD>
<P>The <CODE>VIC</CODE> structure allows access to the VIC (the graphics
controller). See the <CODE>_vic.h</CODE> header file located in the include
directory for the declaration of the structure.</P>

<DT><B><CODE>VIA1, VIA2</CODE></B><DD>
<P>Access to the two VIA (versatile interface adapter) chips is available via
the <CODE>VIA1</CODE> and <CODE>VIA2</CODE> variables. The structure behind these variables
is explained in <CODE>_6522.h</CODE>.</P>

<DT><B><CODE>COLOR_RAM</CODE></B><DD>
<P>A character array that mirrors the color RAM of the VIC20 at $9600.</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 VIC20.</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 VIC20.</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>vic20-stdjoy.joy (vic20_stdjoy_joy)</CODE>.</P>
<P>
<DL>

<DT><B><CODE>vic20-stdjoy.joy (vic20_stdjoy_joy)</CODE></B><DD>
<P>Supports one standard joystick connected to the joysticks port of the VIC20.</P>

<DT><B><CODE>vic20-ptvjoy.joy (vic20_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 three
joysticks are supported.</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 VIC20.</P>


<H2><A NAME="ss5.5">5.5</A> <A HREF="#toc5.5">RS232 device drivers</A>
</H2>


<P>No VIC1011 drivers are currently available for the VIC20.</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">Escape code</A>
</H2>


<P>For an Esc, press CTRL and the <CODE>[</CODE> key.</P>


<H2><A NAME="ss7.2">7.2</A> <A HREF="#toc7.2">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.3">7.3</A> <A HREF="#toc7.3">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.4">7.4</A> <A HREF="#toc7.4">Using extended memory</A>
</H2>


<P>The extended memory at $A000 may be added to the heap by using the following
code:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
    /* Check for the existence of RAM */
    if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) {
        /* Add it to the heap */
        _heapadd ((void *) 0xA000, 0x2000);
    }
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME="ss7.5">7.5</A> <A HREF="#toc7.5">Interrupts</A>
</H2>


<P>The runtime for the VIC20 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="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>
cc65-doc 2.16-2 / usr / share / doc / cc65-doc / html / vic20.html
