<!doctype linuxdoc system>
<article>
-
-<title>Commodore 128 specific information for cc65
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2003-12-14
+<title>Commodore 128-specific information for cc65
+<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
+<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">
<abstract>
An overview over the C128 runtime system as it is implemented for the cc65 C
<sect>Overview<p>
This file contains an overview of the C128 runtime system as it comes with the
-cc65 C compiler. It describes the memory layout, C128 specific header files,
+cc65 C compiler. It describes the memory layout, C128-specific header files,
available drivers, and any pitfalls specific to that platform.
-Please note that C128 specific functions are just mentioned here, they are
-described in detail in the separate <htmlurl url="funcref.html" name="function
+Please note that C128-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.
The text screen is located at $400 (as in the standard setup).
<tag/Stack/
- The C runtime stack is located at $BFFF and growing downwards.
+ The C runtime stack is located at $BFFF, and growing downwards.
<tag/Heap/
- The C heap is located at the end of the program and grows towards the C
+ 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>
+<sect>Platform
-specific header files<p>
-Programs containing C128 specific code may use the <tt/c128.h/ or <tt/cbm.h/
+Programs containing C128-specific code may use the <tt/c128.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/c128.h/ and declares several functions
common to all CBM platforms.
-<sect1>C128
specific functions<p>
+<sect1>C128
-specific functions<p>
-The functions listed below are special for the C128. See the <htmlurl
+The functions listed below are special for the C128. See the <url
url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>videomode
<item>c64mode
-<item>fast
-<item>slow
</itemize>
-<sect1>CBM specific functions<p>
+<sect1>C128-specific accelerator functions<p>
+
+The functions listed below are accelerator functions for the C128. See the <url
+url="funcref.html" name="function reference"> for declaration and usage.
+
+<itemize>
+<item>detect_c128
+<item>detect_scpu
+<item>get_c128_speed
+<item>get_scpu_speed
+<item>set_c128_speed
+<item>set_scpu_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>
<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
</itemize>
+<sect1>CBM specific CPU functions<p>
+
+Some CPU related functions are available for some of the Commodore
+machines. See the <url url="funcref.html" name="function reference"> for
+declaration and usage.
+
+<itemize>
+<item>fast
+<item>slow
+<item>isfast
+</itemize>
+
+
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/c128.h/ header file do
<sect1>Graphics drivers<p>
+The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/, point to <tt/c128-vdc.tgi (c128_vdc_tgi)/.
+
Note: The graphics drivers for the VDC are incompatible with the extended
memory drivers using the VDC memory!
<descrip>
- <tag><tt/c128-vdc.tgi (c128_640_200_2)/</tag>
- This driver was written by Maciej Witkowiak. It uses the 80 column display
- and features a resolution of 640*200 with two colors and an adjustable
+
+ <tag><tt/c128-hi.tgi (c128_hi_tgi)/</tag>
+ This driver features a resolution of 320×200 with two colors and an
+ adjustable palette (that means that the two colors can be chosen out of a
+ palette of the 16 VIC colors). Unlike BASIC 7.0, this driver puts its
+ graphics data into the RAM behind the ROMs.
+
+ <tag><tt/c128-vdc.tgi (c128_vdc_tgi)/</tag>
+ This driver was written by Maciej Witkowiak. It uses the 80-column display,
+ and features a resolution of 640×200 with two colors and an adjustable
palette (that means that the two colors can be chosen out of the 16 VDC
colors).
- <tag><tt/c128-vdc2.tgi (c128_640_480_2)/</tag>
- This driver was written by Maciej Witkowiak. This driver uses the 80 column
- display and features a resolution of 640*480 with two colors and an
+ <tag><tt/c128-vdc2.tgi (c128_vdc2_tgi)/</tag>
+ This driver was written by Maciej Witkowiak. This driver uses the 80-column
+ display, and features a resolution of 640×480 with two colors and an
adjustable palette (that means that the two colors can be chosen out of the
16 VDC colors). The driver requires 64KB VDC RAM.
+
</descrip><p>
-Note: The colors are translated from definitions in headers to correct VDC values
-so please use definitions or VIC color numbers only. Colors <tt/GRAY3/ and <tt/BROWN/ are
-missing on VDC and are translated to the two colors missing from VIC palette.
+Note: The colors are translated from the definitions in the headers to correct
+VDC values; so, please use definitions or VIC color numbers only. Colors
+<tt/GRAY3/ and <tt/BROWN/ are missing on the VDC; and, are translated to the
+two colors missing from the VIC palette.
+
<sect1>Extended memory drivers<p>
<descrip>
- <tag><tt/c128-georam.emd (c128_georam)/</tag>
+ <tag><tt/c128-efnram.emd (c128_efnram_emd)/</tag>
+ Extended memory driver for the C128 External Function RAM.
+ Written and contributed by Marco van den Heuvel.
+
+ <tag><tt/c128-georam.emd (c128_georam_emd)/</tag>
A driver for the GeoRam cartridge. The driver will always assume 2048 pages
of 256 bytes each. There are no checks, so if your program knows better,
just go ahead.
- <tag><tt/c128-ram.emd (c128_ram)/</tag>
+ <tag><tt/c128-ifnram.emd (c128_ifnram_emd)/</tag>
+ Extended memory driver for the C128 Internal Function RAM.
+ Written and contributed by Marco van den Heuvel.
+
+ <tag><tt/c128-ram.emd (c128_ram_emd)/</tag>
An extended memory driver for the RAM in page 1. The common memory area is
excluded, so this driver supports 251 pages of 256 bytes each.
- <tag><tt/c128-ram2.emd (c128_ram2)/</tag>
-
+ <tag><tt/c128-ram2.emd (c128_ram2_emd)/</tag>
An extended memory driver for the RAM in pages 1-3. The common memory area
is excluded, so this driver supports up to 731 pages of 256 bytes each. The
driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM
machines with RAM in banks 2+3, so it has been made a separate driver. The
additional code was contributed by Marco van den Heuvel.
- <tag><tt/c128-ramcart.emd (c128_ramcart)/</tag>
+ <tag><tt/c128-ramcart.emd (c128_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/c128-reu.emd (c128_reu)/</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.
+ <tag><tt/c128-reu.emd (c128_reu_emd)/</tag>
+ A driver for the CBM REUs. The driver will test the connected REU to find
+ out how much RAM is present.
- <tag><tt/c128-vdc.emd (c128_vdc)/</tag>
- A driver for the VDC memory of the C128 written and contributed by Maciej
- Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers
+ <tag><tt/c128-vdc.emd (c128_vdc_emd)/</tag>
+ A driver for the VDC memory of the C128, written and contributed by Maciej
+ Witkowiak. Autodetects the amount of memory available (16 or 64K), and offers
64 or 256 pages of 256 bytes each. Note: This driver is incompatible with
any of the graphics drivers using the VDC!
<sect1>Joystick drivers<p>
+The default drivers, <tt/joy_stddrv (joy_static_stddrv)/, point to <tt/c128-stdjoy.joy (c128_stdjoy_joy)/.
+
<descrip>
- <tag><tt/c128-ptvjoy.joy (c128_ptvjoy)/</tag>
+ <tag><tt/c128-ptvjoy.joy (c128_ptvjoy_joy)/</tag>
Driver for the Protovision 4-player adapter originally written by Groepaz
- for the C64 and converted for the C128 by me. 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.
+ for the C64, and converted for the C128 by Uz. See <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/c128-stdjoy.joy (c128_stdjoy)/</tag>
- Supports up to two joysticks connected to the standard joysticks port of
+ <tag><tt/c128-stdjoy.joy (c128_stdjoy_joy)/</tag>
+ Supports up to two joysticks connected to the standard joysticks ports of
the C128.
</descrip><p>
<sect1>Mouse drivers<p>
+The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c128-1351.mou (c128_1351_mou)/.
+
<descrip>
- <tag><tt/c128-1351.mou (c128_1351)/</tag>
+ <tag><tt/c128-1351.mou (c128_1351_mou)/</tag>
Supports a standard mouse connected to port #0 of the C128.
- <tag><tt/c128-joy.mou (c128_joymouse)/</tag>
- Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
+ <tag><tt/c128-inkwell.mou (c128_inkwell_mou)/</tag>
+ Supports the Inkwell Systems lightpens, connected to port #0 of the
+ C128. It can read both the one-button 170-C and the two-button 184-C pens.
+ (It can read other lightpens and light-guns that send their button signal to
+ the joystick left-button pin or the paddle Y [up/down] pin.) It works on
+ only the 40-column screen.
+
+ <tag><tt/c128-joy.mou (c128_joy_mou)/</tag>
+ Supports a mouse emulated by a standard joystick, e.g. 1350 mouse, in port
#1 of the C128.
- <tag><tt/c128-pot.mou (c128_potmouse)/</tag>
- Supports a potentiometer device e.g. Koala Pad connected to port #1 of
+ <tag><tt/c128-pot.mou (c128_pot_mou)/</tag>
+ Supports a potentiometer device, e.g. Koala Pad, connected to port #1 of
the C128.
</descrip><p>
<descrip>
- <tag><tt/c128-swlink.ser (c128_swlink)/</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
+ <tag><tt/c128-swlink.ser (c128_swlink_ser)/</tag>
+ 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.
The driver uses the RS232 variables and buffers of the kernal (buffers at
<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>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
<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>
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">.
-
-
-
-<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">).
+feature in the <url url="ca65.html" name="assembler manual">.
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.
+<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>
projects / cc65 / blobdiff