X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fc64.sgml;h=37ac0c1466b39ac4257177b00dad38ead19f3211;hb=cd72f816d34efbb415bdb9e97435994e4e57b443;hp=a5014414ccb3ef202f7a5676a523b117be442e29;hpb=290da8d5ae8939c6d68b798eafe3257f1b485b4f;p=cc65 diff --git a/doc/c64.sgml b/doc/c64.sgml index a5014414c..37ac0c146 100644 --- a/doc/c64.sgml +++ b/doc/c64.sgml @@ -1,10 +1,9 @@
- -Commodore 64 specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-09-23 +<title>Commodore 64-specific information for cc65 +<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz"><newline> +<url url="mailto:greg.king5@verizon.net" name="Greg King"> <abstract> An overview over the C64 runtime system as it is implemented for the cc65 C @@ -19,11 +18,11 @@ compiler. <sect>Overview<p> This file contains an overview of the C64 runtime system as it comes with the -cc65 C compiler. It describes the memory layout, C64 specific header files, +cc65 C compiler. It describes the memory layout, C64-specific header files, available drivers, and any pitfalls specific to that platform. -Please note that C64 specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function +Please note that C64-specific functions are just mentioned here, they are +described in detail in the separate <url 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. @@ -116,18 +115,51 @@ cl65 -o file.prg -u __EXEHDR__ -t c64 -C c64-asm.cfg source.s Please note that in this case a changed start address doesn't make sense, since the program must be loaded to the BASIC start address. +<sect>Extras<p> + +<sect1>80 Columns conio driver<p> + +The C64 package comes with an alternative software driven 80 columns +module <tt/c64-soft80.o/ which uses the memory under I/O between $D000 +and $FF3F. + +In memory constrained situations the memory from $400 to $7FF +can be made available to a program by calling <tt/_heapadd ((void *) 0x0400, 0x0400);/ +at the beginning of <tt/main()/. Doing so is beneficial even if the program +doesn't use the the heap explicitly because loading a driver uses the heap implicitly. + +Using <tt/c64-soft80.o/ is as simple as placing it on the linker command +line like this: + +<tscreen><verb> +cl65 -t c64 myprog.c c64-soft80.o +</verb></tscreen> + +Note that the soft80 conio driver is incompatible with the +<tt/c64-ram.emd (c64_ram_emd)/ extended memory driver and the + <tt/c64-hi.tgi (c64_hi_tgi)/ graphics driver. -<sect>Platform specific header files<p> +<sect2>80 Columns conio driver (monochrome)<p> -Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/ +In an (even more) memory constrained situation, a size optimized version of the +software driven 80 columns module may be used, which only supports one common +text color for the whole screen. + +<tscreen><verb> +cl65 -t c64 myprog.c c64-soft80mono.o +</verb></tscreen> + +<sect>Platform-specific header files<p> + +Programs containing C64-specific code may use the <tt/c64.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/c64.h/ and declares several functions common to all CBM platforms. -<sect1>C64 specific functions<p> +<sect1>C64-specific functions<p> -The functions listed below are special for the C64. See the <htmlurl +The functions listed below are special for the C64. See the <url url="funcref.html" name="function reference"> for declaration and usage. <itemize> @@ -135,10 +167,37 @@ url="funcref.html" name="function reference"> for declaration and usage. </itemize> -<sect1>CBM specific functions<p> +<sect1>C64-specific accelerator functions<p> + +The functions listed below are accelerator functions for the C64. See the <url +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>detect_c128 +<item>detect_c64dtv +<item>detect_c65 +<item>detect_chameleon +<item>detect_scpu +<item>detect_turbomaster +<item>get_c128_speed +<item>get_c64dtv_speed +<item>get_c65_speed +<item>get_chameleon_speed +<item>get_scpu_speed +<item>get_turbomaster_speed +<item>set_c128_speed +<item>set_c64dtv_speed +<item>set_c65_speed +<item>set_chameleon_speed +<item>set_scpu_speed +<item>set_turbomaster_speed +</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 +machines. See the <url url="funcref.html" name="function reference"> for declaration and usage. <itemize> @@ -156,6 +215,8 @@ declaration and usage. <item>cbm_k_basin <item>cbm_k_bsout <item>cbm_k_clrch +<item>cbm_k_tksa +<item>cbm_k_second <item>cbm_load <item>cbm_open <item>cbm_opendir @@ -202,12 +263,22 @@ structures, accessing the struct fields will access the chip registers. The names in the parentheses denote the symbols to be used for static linking of the drivers. +<label id="graphics-drivers"> <sect1>Graphics drivers<p> <em>Note:</em> All available graphics drivers for the TGI interface will use -the space below the I/O area and kernal ROM, so you can have hires graphics in -the standard setup without any memory loss or need for a changed -configuration. +the space below the I/O area and Kernal ROM; so, you can have hires graphics in +the standard setup without any memory loss or need for a changed configuration. + +You can use a mouse driver at the same time that you use a TGI driver. But, if +you want to see the default mouse pointer on the graphics screen, then you +explicitly must link a special object file into your program. It will put the +arrow into the "high RAM" area where the bitmaps are put. Its name is +"<tt/c64-tgimousedata.o/". Example: + +<tscreen><verb> +cl65 -t c64 -o program-file main-code.c subroutines.s c64-tgimousedata.o +</verb></tscreen> <descrip> <tag><tt/c64-hi.tgi (c64_hi_tgi)/</tag> @@ -216,11 +287,19 @@ configuration. palette of the 16 C64 colors). </descrip><p> +Note that the graphics drivers are incompatible with the +<tt/c64-ram.emd (c64_ram_emd)/ extended memory driver and the + <tt/c64-soft80.o/ software 80-columns conio driver. + <sect1>Extended memory drivers<p> <descrip> + <tag><tt/c64-65816.emd (c64_65816_emd)/</tag> + Extended memory driver for 65816 (eg SCPU) based extra RAM. + Written and contributed by Marco van den Heuvel. + <tag><tt/c64-c256k.emd (c64_c256k_emd)/</tag> A driver for the C64 256K memory expansion. This driver offers 768 pages of 256 bytes each. Written and contributed by Marco van den Heuvel. @@ -239,19 +318,17 @@ configuration. bytes each. Written and contributed by Marco van den Heuvel. <tag><tt/c64-ram.emd (c64_ram_emd)/</tag> - A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48 + A driver for the hidden RAM below the I/O area and kernal ROM. Supports 47 256 byte pages. Please note that this driver is incompatible with any of the - graphics drivers! + graphics drivers, or the soft80 conio driver! <tag><tt/c64-ramcart.emd (c64_ramcart_emd)/</tag> A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. Will test the hardware for the available RAM. <tag><tt/c64-reu.emd (c64_reu_emd)/</tag> - A driver for the CBM REUs. The driver will determine from the connected REU - if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, - but since there are no range checks, the application can use more memory if - it has better knowledge about the hardware than the driver. + A driver for the CBM REUs. The driver will test the connected REU to find + out how much RAM is present. <tag><tt/c64-vdc.emd (c64_vdc_emd)/</tag> A driver for the VDC memory of the C128. Written and contributed by Maciej @@ -268,19 +345,20 @@ configuration. <sect1>Joystick drivers<p> +The default drivers, <tt/joy_stddrv (joy_static_stddrv)/, point to <tt/c64-stdjoy.joy (c64_stdjoy_joy)/. + <descrip> <tag><tt/c64-hitjoy.joy (c64_hitjoy_joy)/</tag> - Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See - <htmlurl url="http://www.digitalexcess.de/downloads/productions.php" - name="http://www.digitalexcess.de/downloads/productions.php"> on + Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. + See <url url="http://www.digitalexcess.de/downloads/productions.php"> on instructions how to build one. Up to four joysticks are supported. <tag><tt/c64-ptvjoy.joy (c64_ptvjoy_joy)/</tag> Driver for the Protovision 4-player adapter contributed by Groepaz. See - <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" - name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and - building instructions. Up to four joysticks are supported. + <url url="http://www.protovision-online.de/hardw/4_player.php?language=en" + name="Protovision shop"> for prices and building instructions. Up to four + joysticks are supported. <tag><tt/c64-stdjoy.joy (c64_stdjoy_joy)/</tag> Supports up to two standard joysticks connected to the joysticks port of @@ -295,6 +373,11 @@ configuration. <sect1>Mouse drivers<p> +You can use these drivers in text-mode or graphics-mode (TGI) programs. See +the description of <ref id="graphics-drivers" name="the graphics drivers">. + +The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c64-1351.mou (c64_1351_mou)/. + <descrip> <tag><tt/c64-1351.mou (c64_1351_mou)/</tag> @@ -307,11 +390,11 @@ configuration. joystick left-button pin or the paddle Y [up/down] pin.) <tag><tt/c64-joy.mou (c64_joy_mou)/</tag> - Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port + Supports a mouse emulated by a standard joystick, e.g. 1350 mouse, in port #1 of the C64. <tag><tt/c64-pot.mou (c64_pot_mou)/</tag> - Supports a potentiometer device e.g. Koala Pad connected to port #1 of + Supports a potentiometer device, e.g. Koala Pad, connected to port #1 of the C64. </descrip><p> @@ -322,10 +405,10 @@ configuration. <descrip> <tag><tt/c64-swlink.ser (c64_swlink_ser)/</tag> - Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow - control (RTS/CTS) and interrupt driven receives. Note that because of the - peculiarities of the 6551 chip together with the use of the NMI, transmits - are not interrupt driven, and the transceiver blocks if the receiver asserts + Driver for the SwiftLink cartridge. Supports up to 38400 BPS, hardware flow + control (RTS/CTS), and interrupt-driven receives. Note that, because of the + peculiarities of the 6551 chip, together with the use of the NMI, transmits + are not interrupt driven; and, the transceiver blocks if the receiver asserts flow control because of a full buffer. </descrip><p> @@ -335,17 +418,26 @@ configuration. <sect>Limitations<p> +<sect1>Realtime clock<p> + +The realtime clock functions use the CIA1 TOD clock. As that clock only stores +the time but not the date, the date set by <tt/clock_settime()/ is simply stored +inside the C library for retrieval in the same program via <tt/clock_gettime()/. + + <sect>Other hints<p> + <sect1>Escape code<p> -For an Esc press CTRL and [ key. +For an Esc, press CTRL and the <tt/[/ key. + <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: +Command-line arguments can be passed to <tt/main()/. Since this is not +supported directly by BASIC, the following syntax was chosen: <tscreen><verb> RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 @@ -356,7 +448,7 @@ supported by BASIC, the following syntax was chosen: <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>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> @@ -374,7 +466,7 @@ The runtime for the C64 uses routines marked as <tt/.INTERRUPTOR/ 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">. +feature in the <url url="ca65.html" name="assembler manual">.