<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">
+<date>2014-04-12
<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.
<sect>Binary format<p>
The standard binary output format generated by the linker for the C128 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.
+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.
<sect>Memory layout<p>
The text screen is located at $400 (as in the standard setup).
<tag/Stack/
- The C runtime stack is located at $CFFF 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_scpu
+<item>scpu_get_speed
+<item>scpu_set_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>
</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
is explained in <tt/_6526.h/.
<tag><tt/COLOR_RAM/</tag>
- A character array that mirrors the color RAM of the C64 at $D800.
+ A character array that mirrors the color RAM of the C128 at $D800.
</descrip><p>
<sect>Loadable drivers<p>
+The names in the parentheses denote the symbols to be used for static linking of the drivers.
+
+
<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/</tag>
- This driver was written by Maciej Witkowiak. It uses the 80 column display
+ <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/</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 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 the VIC palette.
<sect1>Extended memory drivers<p>
<descrip>
- <tag><tt/c128-georam.emd/</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/</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-ramcart.emd/</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
+ in pages 2+3 is autodetected, but it's larger and there are not many
+ 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_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/</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/</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/</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/</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/</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/</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/</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/</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>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>
<sect1>Interrupts<p>
-The runtime for the C128 uses routines marked as <tt/.CONDES/ type 2 for
+The runtime for the C128 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">.
-
-
-
-<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">.
</enum>
</article>
-
-
-
-