diff --git a/doc/Makefile b/doc/Makefile index 9c4afc029..effbf0d96 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -27,7 +27,8 @@ SGML = apple2.sgml \ intro.sgml \ ld65.sgml \ library.sgml \ - plus4.sgml + plus4.sgml \ + vic20.sgml TXT = $(SGML:.sgml=.txt) HTML = $(SGML:.sgml=.html) diff --git a/doc/vic20.sgml b/doc/vic20.sgml new file mode 100644 index 000000000..b3af79c6d --- /dev/null +++ b/doc/vic20.sgml @@ -0,0 +1,242 @@ + + +
+ +Commodore VIC20 (aka VC20) 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>2004-09-13 + +<abstract> +An overview over the VIC20 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 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. + +Please note that VIC20 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 VIC20 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 (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. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $1E00 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $1DFF 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 VIC20 specific code may use the <tt/vic20.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/vic20.h/ and declares several functions +common to all CBM platforms. + + +<sect1>VIC20 specific functions<p> + +The functions listed below are special for the VIC20. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>get_ostype +</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/vic20.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 (the graphics + controller). See the <tt/_vic.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/VIA1, VIA2/</tag> + Access to the two VIA (versatile interface adapter) chips is available via + the <tt/VIA1/ and <tt/VIA2/ variables. The structure behind these variables + is explained in <tt/_6522.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the VIC20 at $9600. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the VIC20. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the VIC20. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/vic20-stdjoy.joy/</tag> + Supports one standard joystick connected to the joysticks port of the VIC20. + +</descrip><p> + + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the VIC20. + + +<sect1>RS232 device drivers<p> + +No VIC1011 drivers are currently available for the VIC20. + + + +<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. + + + + +<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> + + +