<title>cc65 function reference
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
-<date>2018-02-06
+<date>2018-02-07
<abstract>
cc65 is a C compiler for 6502 based systems. This function reference describes
</itemize>
+<sect1><tt/accelerator.h/<label id="accelerator.h"><p>
+
+<itemize>
+<item><ref id="detect_c128" name="detect_c128">
+<item><ref id="detect_c64dtv" name="detect_c64dtv">
+<item><ref id="detect_scpu" name="detect_scpu">
+<item><ref id="get_c128_speed" name="get_c128_speed">
+<item><ref id="get_c64dtv_speed" name="get_c64dtv_speed">
+<item><ref id="get_scpu_speed" name="get_scpu_speed">
+<item><ref id="set_c128_speed" name="set_c128_speed">
+<item><ref id="set_c64dtv_speed" name="set_c64dtv_speed">
+<item><ref id="set_scpu_speed" name="set_scpu_speed">
+</itemize>
+
+
<sect1><tt/apple2.h/<label id="apple2.h"><p>
<itemize>
<itemize>
<item><ref id="c64mode" name="c64mode">
<item><ref id="fast" name="fast">
+<item><ref id="isfast" name="isfast">
<item><ref id="slow" name="slow">
<item><ref id="toggle_videomode" name="toggle_videomode">
<item><ref id="videomode" name="videomode">
<sect1><tt/c16.h/<label id="c16.h"><p>
+<itemize>
+<item><ref id="fast" name="fast">
+<item><ref id="isfast" name="isfast">
+<item><ref id="slow" name="slow">
+</itemize>
+
(incomplete)
<sect1><tt/plus4.h/<label id="plus4.h"><p>
+<itemize>
+<item><ref id="fast" name="fast">
+<item><ref id="isfast" name="isfast">
+<item><ref id="slow" name="slow">
+</itemize>
+
(incomplete)
<itemize>
<!-- <item><ref id="chdir" name="chdir"> -->
<item><ref id="exec" name="exec">
-<!-- <item><ref id="getcwd" name="getcwd"> -->
+<item><ref id="getcwd" name="getcwd">
<item><ref id="getopt" name="getopt">
<!-- <item><ref id="lseek" name="lseek"> -->
<!-- <item><ref id="mkdir" name="mkdir"> -->
</quote>
+<sect1>detect_c128<label id="detect_c128"><p>
+
+<quote>
+<descrip>
+<tag/Function/Check for the presence of a C128 in C64 mode.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char detect_c128 (void);/
+<tag/Description/The function returns a 1 if a C128 in C64 mode has been detected.
+<tag/Notes/<itemize>
+<item>The function is specific to the C64.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="get_c128_speed" name="get_c128_speed">,
+<ref id="set_c128_speed" name="set_c128_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>detect_c64dtv<label id="detect_c64dtv"><p>
+
+<quote>
+<descrip>
+<tag/Function/Check for the presence of the C64DTV.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char detect_c64dtv (void);/
+<tag/Description/The function returns a 1 if a C64DTV has been detected.
+<tag/Notes/<itemize>
+<item>The function is specific to the C64.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="get_c64dtv_speed" name="get_c64dtv_speed">,
+<ref id="set_c64dtv_speed" name="set_c64dtv_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>detect_scpu<label id="detect_scpu"><p>
+
+<quote>
+<descrip>
+<tag/Function/Check for the presence of the C64/C128 SuperCPU cartridge.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char detect_scpu (void);/
+<tag/Description/The function returns a 1 if a SuperCPU cartridge has been detected.
+<tag/Notes/<itemize>
+<item>The function is specific to the C128 and C64.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="get_scpu_speed" name="get_scpu_speed">,
+<ref id="set_scpu_speed" name="set_scpu_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>div<label id="div"><p>
<quote>
<quote>
<descrip>
-<tag/Function/Switch the C128 into 2MHz mode.
-<tag/Header/<tt/<ref id="c128.h" name="c128.h">/
+<tag/Function/Switch the CPU into fast mode (C128: 2MHz mode, C16/Plus4: double clock mode).
+<tag/Header/<tt/<ref id="c128.h" name="c128.h">,
+<ref id="c16.h" name="c16.h">, <ref id="plus4.h" name="plus4.h">/
<tag/Declaration/<tt/void fast (void);/
-<tag/Description/The function will switch the clock of the C128 to 2MHz. This
-will nearly double the speed compared to slow mode.
+<tag/Description/The function will switch the clock of the CPU to fast mode. For the C128
+target it means switching the CPU into 2MHz mode. For the C16/Plus4 target it means
+switching the CPU into double clock mode.
<tag/Notes/<itemize>
-<item>The function is specific to the C128.
-<item>2MHz clock will not work in 40 column mode.
+<item>The function is specific to the C128, C16 and Plus4.
+<item>On the C128 the 2MHz clock will not work in 40 column mode.
</itemize>
-<tag/Availability/C128
+<tag/Availability/cc65 (not all platforms)
<tag/See also/
+<ref id="isfast" name="isfast">,
<ref id="slow" name="slow">,
-<ref id="toggle_videomode" name="toggle_videomode">,
-<ref id="videomode" name="videomode">
<tag/Example/None.
</descrip>
</quote>
</quote>
+<sect1>get_c128_speed<label id="get_c128_speed"><p>
+
+<quote>
+<descrip>
+<tag/Function/Get the current speed of the C128 in C64 mode.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char get_c128_speed (void);/
+<tag/Description/The function returns the current speed of the C128 in C64 mode.
+<tag/Notes/<itemize>
+<item>The function is specific to the C64.
+<item>The function does not check for the presence of a C128 in C64 mode.
+<item>See the accelerator.h header for the speed definitions.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="detect_c128" name="detect_c128">,
+<ref id="set_c128_speed" name="set_c128_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>get_c64dtv_speed<label id="get_c64dtv_speed"><p>
+
+<quote>
+<descrip>
+<tag/Function/Get the current speed of the C64DTV.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char get_c64dtv_speed (void);/
+<tag/Description/The function returns the current speed of the C64DTV.
+<tag/Notes/<itemize>
+<item>The function is specific to the C64.
+<item>The function does not check for the presence of the C64DTV.
+<item>See the accelerator.h header for the speed definitions.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="detect_c64dtv" name="detect_c64dtv">,
+<ref id="set_c64dtv_speed" name="set_c64dtv_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>get_scpu_speed<label id="get_scpu_speed"><p>
+
+<quote>
+<descrip>
+<tag/Function/Get the current speed of the C64/C128 SuperCPU cartridge.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char get_scpu_speed (void);/
+<tag/Description/The function returns the current speed of the SuperCPU cartridge.
+<tag/Notes/<itemize>
+<item>The function is specific to the C128 and C64.
+<item>The function does not check for the presence of the cartridge.
+<item>See the accelerator.h header for the speed definitions.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="detect_scpu" name="detect_scpu">,
+<ref id="set_scpu_speed" name="set_scpu_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>getcpu<label id="getcpu"><p>
<quote>
<item><tt/CPU_6502/
<item><tt/CPU_65C02/
<item><tt/CPU_65816/
+<item><tt/CPU_4510/
+<item><tt/CPU_65SC02/
+<item><tt/CPU_65CE02/
+<item><tt/CPU_HUC6280/
+<item><tt/CPU_2A0x/
</itemize>
<tag/Notes/<itemize>
<item>Other, more exotic CPU types are not disinguished.
<tag/Header/<tt/<ref id="device.h" name="device.h">/
<tag/Declaration/<tt/unsigned char getcurrentdevice (void);/
<tag/Description/The function returns the current device.
-<tag/Notes/<itemize>
-<item>
-</itemize>
+It allows to access the current device with the <ref id="dio.h"
+name="Low-level disk I/O API"> or <ref id="cbm.h" name="cbm_* I/O
+functions"> requiring a 'device' parameter.
<tag/Availability/cc65
<tag/See also/
<ref id="getdevicedir" name="getdevicedir">,
<ref id="getfirstdevice" name="getfirstdevice">,
<ref id="getnextdevice" name="getnextdevice">
<tag/Example/<verb>
-puts (getdevicedir (getcurrentdevice (), buf, sizeof buf));
+dio_open (getcurrentdevice ());
</verb>
</descrip>
</quote>
+<sect1>getcwd<label id="getcwd"><p>
+
+<quote>
+<descrip>
+<tag/Function/Get current working directory.
+<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/
+<tag/Declaration/<tt/char* __fastcall__ getcwd (char* buf, size_t size);/
+<tag/Description/The function will return the current working directory.
+<tag/Notes/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/POSIX 1003.1
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>getdevicedir<label id="getdevicedir"><p>
<quote>
<tag/Function/Get device directory.
<tag/Header/<tt/<ref id="device.h" name="device.h">/
<tag/Declaration/<tt/char* __fastcall__ getdevicedir (unsigned char device, char* buf, size_t size);/
-<tag/Description/The function returns the current directory of <tt/device/.
+<tag/Description/The function returns the directory representing <tt/device/.
+It allows to access the device on filesystem level by calling chdir() with
+the directory returned.
<tag/Notes/<itemize>
+<item>Calling getdevicedir() <em/does/ check for a (formatted) disk in a
+floppy-disk-type device and returns NULL if that check fails.
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
</itemize>
<ref id="getfirstdevice" name="getfirstdevice">,
<ref id="getnextdevice" name="getnextdevice">
<tag/Example/<verb>
-puts (getdevicedir (getcurrentdevice (), buf, sizeof buf));
+chdir (getdevicedir (device, buf, sizeof buf));
</verb>
+cf. <tt/samples/enumdevdir.c/
+</descrip>
+</quote>
+
+
+<sect1>getenv<label id="getenv"><p>
+
+<quote>
+<descrip>
+<tag/Function/Return a value from the environment.
+<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/
+<tag/Declaration/<tt/char* __fastcall__ getenv (const char* name);/
+<tag/Description/The function searches the environment for an entry that
+matches <tt/name/ and returns its value. The environment consists of a list
+of strings in the form <tt/name=value/. If there is no match, <tt/getenv/
+returns <tt/NULL/.
+<tag/Notes/<itemize>
+<item>What exactly is stored in the environment depends on the machine the
+program is running on.
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/ISO 9899
+<tag/Example/None.
</descrip>
</quote>
<tag/Header/<tt/<ref id="device.h" name="device.h">/
<tag/Declaration/<tt/unsigned char getfirstdevice (void);/
<tag/Description/The function returns the first device.
-The value 255 indicates no device.
+The constant <tt/INVALID_DEVICE/ indicates no device.
<tag/Notes/<itemize>
-<item>
+<item>Calling getfirstdevice() does <em/not/ turn on the motor of a
+drive-type device and does <em/not/ check for a disk in the drive.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="getnextdevice" name="getnextdevice">
<tag/Example/<verb>
unsigned char dev = getfirstdevice ();
-while (dev != 255) {
+while (dev != INVALID_DEVICE) {
printf ("%d\n", dev);
dev = getnextdevice (dev);
}
<tag/Header/<tt/<ref id="device.h" name="device.h">/
<tag/Declaration/<tt/unsigned char __fastcall__ getnextdevice (unsigned char device);/
<tag/Description/The function returns the next device after <tt/device/.
-The value 255 indicates no further device.
+The constant <tt/INVALID_DEVICE/ indicates no further device.
<tag/Notes/<itemize>
+<item>Calling getnextdevice() does <em/not/ turn on the motor of a
+drive-type device and does <em/not/ check for a disk in the drive.
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
</itemize>
<ref id="getfirstdevice" name="getfirstdevice">
<tag/Example/<verb>
unsigned char dev = getfirstdevice ();
-while (dev != 255) {
+while (dev != INVALID_DEVICE) {
printf ("%d\n", dev);
dev = getnextdevice (dev);
}
</quote>
-<sect1>getenv<label id="getenv"><p>
-
-<quote>
-<descrip>
-<tag/Function/Return a value from the environment.
-<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/
-<tag/Declaration/<tt/char* __fastcall__ getenv (const char* name);/
-<tag/Description/The function searches the environment for an entry that
-matches <tt/name/ and returns its value. The environment consists of a list
-of strings in the form <tt/name=value/. If there is no match, <tt/getenv/
-returns <tt/NULL/.
-<tag/Notes/<itemize>
-<item>What exactly is stored in the environment depends on the machine the
-program is running on.
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
-<tag/Availability/ISO 9899
-<tag/Example/None.
-</descrip>
-</quote>
-
-
<sect1>getopt<label id="getopt"><p>
<quote>
</quote>
+<sect1>isfast<label id="isfast"><p>
+
+<quote>
+<descrip>
+<tag/Function/Check if the CPU is in fast mode (C128: 2MHz mode, C16/Plus4: double clock mode).
+<tag/Header/<tt/<ref id="c128.h" name="c128.h">,
+<ref id="c16.h" name="c16.h">, <ref id="plus4.h" name="plus4.h">/
+<tag/Declaration/<tt/unsigned char isfast (void);/
+<tag/Description/The function returns a 1 if the CPU is in fast mode (C128: 2MHz mode, C16/Plus4: double clock mode).
+<tag/Notes/<itemize>
+<item>The function is specific to the C128, C16 and Plus4.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="fast" name="fast">,
+<ref id="slow" name="slow">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>isgraph<label id="isgraph"><p>
<quote>
</quote>
+<sect1>set_c128_speed<label id="set_c128_speed"><p>
+
+<quote>
+<descrip>
+<tag/Function/Set the current speed of a C128 in C64 mode.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ set_c128_speed (unsigned char speed);/
+<tag/Description/The function returns the speed after trying to set the speed of the C128 in C64 mode.
+<tag/Notes/<itemize>
+<item>The function is specific to the C64.
+<item>The function does not check for the presence of a C128 in C64 mode.
+<item>See the accelerator.h header for the speed definitions.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="detect_c128" name="detect_c128">,
+<ref id="get_c128_speed" name="get_c128_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>set_c64dtv_speed<label id="set_c64dtv_speed"><p>
+
+<quote>
+<descrip>
+<tag/Function/Set the current speed of the C64DTV.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ set_c64dtv_speed (unsigned char speed);/
+<tag/Description/The function returns the speed after trying to set the speed of the C64DTV.
+<tag/Notes/<itemize>
+<item>The function is specific to the C64.
+<item>The function does not check for the presence of the C64DTV.
+<item>See the accelerator.h header for the speed definitions.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="detect_c64dtv" name="detect_c64dtv">,
+<ref id="get_c64dtv_speed" name="get_c64dtv_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>set_scpu_speed<label id="set_scpu_speed"><p>
+
+<quote>
+<descrip>
+<tag/Function/Set the current speed of the C64/C128 SuperCPU cartridge.
+<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ set_scpu_speed (unsigned char speed);/
+<tag/Description/The function returns the speed after trying to set the speed of the SuperCPU cartridge.
+<tag/Notes/<itemize>
+<item>The function is specific to the C128 and C64.
+<item>The function does not check for the presence of the cartridge.
+<item>See the accelerator.h header for the speed definitions.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/See also/
+<ref id="detect_scpu" name="detect_scpu">,
+<ref id="get_scpu_speed" name="get_scpu_speed">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>setjmp<label id="setjmp"><p>
<quote>
<quote>
<descrip>
-<tag/Function/Switch the C128 into 1MHz mode.
-<tag/Header/<tt/<ref id="c128.h" name="c128.h">/
+<tag/Function/Switch the CPU into slow mode (C128: 1MHz mode, C16/Plus4: single clock mode).
+<tag/Header/<tt/<ref id="c128.h" name="c128.h">,
+<ref id="c16.h" name="c16.h">, <ref id="plus4.h" name="plus4.h">/
<tag/Declaration/<tt/void slow (void);/
-<tag/Description/The function will switch the clock of the C128 to 1MHz. This
-will halve the speed compared to fast mode.
+<tag/Description/The function will switch the clock of the CPU to slow mode. for the C128
+target it means switching the CPU into 1MHz mode. for the C16/Plus4 target it means
+switching the CPU into single clock mode.
<tag/Notes/<itemize>
-<item>The function is specific to the C128.
+<item>The function is specific to the C128, C16 and Plus4.
</itemize>
-<tag/Availability/C128
+<tag/Availability/cc65 (not all platforms)
<tag/See also/
<ref id="fast" name="fast">,
-<ref id="toggle_videomode" name="toggle_videomode">,
-<ref id="videomode" name="videomode">
+<ref id="isfast" name="isfast">,
<tag/Example/None.
</descrip>
</quote>
<tag/Availability/C128
<tag/See also/
<ref id="fast" name="fast">,
+<ref id="isfast" name="isfast">,
<ref id="slow" name="slow">,
<ref id="videomode" name="videomode">
<tag/Example/None.
<tag/Availability/C128 and enhanced Apple //e
<tag/See also/
<ref id="fast" name="fast">,
+<ref id="isfast" name="isfast">,
<ref id="slow" name="slow">,
<ref id="toggle_videomode" name="toggle_videomode">
<tag/Example/None.
projects / cc65 / blobdiff