Merge pull request #662 from Compyx/master

[cc65] / doc / funcref.sgml

diff --git a/doc/funcref.sgml b/doc/funcref.sgml
index 946b881595d210fb10efda6594519bf3d1e33e6e..4e35ebb7ef95d4cf7790850d32b16abd571a3918 100644 (file)
--- a/doc/funcref.sgml
+++ b/doc/funcref.sgml
@@ -4,7 +4,7 @@
 <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-07
+<date>2018-05-23
 
 <abstract>
 cc65 is a C compiler for 6502 based systems. This function reference describes
@@ -200,11 +200,14 @@ function.
 <item><ref id="cbm_k_readst" name="cbm_k_readst">
 <item><ref id="cbm_k_save" name="cbm_k_save">
 <item><ref id="cbm_k_scnkey" name="cbm_k_scnkey">
+<item><ref id="cbm_k_second" name="cbm_k_second">
 <item><ref id="cbm_k_setlfs" name="cbm_k_setlfs">
 <item><ref id="cbm_k_setnam" name="cbm_k_setnam">
 <item><ref id="cbm_k_talk" name="cbm_k_talk">
+<item><ref id="cbm_k_tksa" name="cbm_k_tksa">
 <item><ref id="cbm_k_udtim" name="cbm_k_udtim">
 <item><ref id="cbm_k_unlsn" name="cbm_k_unlsn">
+<item><ref id="cbm_k_untlk" name="cbm_k_untlk">
 <!-- <item><ref id="cbm_load" name="cbm_load"> -->
 <!-- <item><ref id="cbm_open" name="cbm_open"> -->
 <!-- <item><ref id="cbm_opendir" name="cbm_opendir"> -->
@@ -357,6 +360,9 @@ function.
 
 <sect1><tt/em.h/<label id="em.h"><p>
 
+This header file contains definitions for extended memory access,
+see also <tt>testcode/lib/em-test.c</tt> and <tt>samples/multidemo.c</tt>.
+
 <itemize>
 <item><ref id="em_commit" name="em_commit">
 <item><ref id="em_copyfrom" name="em_copyfrom">
@@ -543,8 +549,8 @@ It does not declare any functions.
 
 <sect1><tt/serial.h/<label id="serial.h"><p>
 
-The <tt/serial.h/ header file contains definitions for initializing serial
-communication.
+This header file contains definitions for initializing serial
+communication, see also <tt>testcode/lib/ser-test.c</tt>.
 
 <itemize>
 <item><ref id="ser_close" name="ser_close">
@@ -2087,7 +2093,7 @@ only be used in presence of a prototype.
 </itemize>
 <tag/Availability/cc65
 <tag/See also/
-<ref id="cbm_k_unlsn" name="cbm_k_unlsn">,
+<ref id="cbm_k_unlsn" name="cbm_k_unlsn">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -2219,6 +2225,31 @@ function, in order to provide input from the keyboard.
 </quote>
 
 
+<sect1>cmb_k_second<label id="cbm_k_second"><p>
+
+<quote>
+<descrip>
+<tag/Function/Send secondary address for LISTEN.
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/void __fastcall__ cbm_k_second (unsigned char addr);/
+<tag/Description/This function is used to send a secondary address to an I/O
+device after a call to LISTEN is made, and the device is commanded to LISTEN.
+<tag/Notes/<itemize>
+<item>The function is only available as fastcall function, so it may
+only be used in presence of a prototype.
+<item>The function can only be called after a call to LISTEN.
+<item>The function will not work after a TALK.
+<item>When a secondary address is to be sent to a device on the serial bus,
+the address must first be ORed with $60.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cbm_k_listen" name="cbm_k_listen">
+<tag/Exampe/None.
+</descrip>
+</quote>
+
+
 <sect1>cbm_k_setlfs<label id="cbm_k_setlfs"><p>
 
 <quote>
@@ -2284,6 +2315,28 @@ only be used in presence of a prototype.
 </quote>
 
 
+<sect1>cbm_k_tksa<label id="cbm_k_tksa"><p>
+
+<quote>
+<descrip>
+<tag/Function/Send TALK secondary address to serial bus
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/void __fastcall__ cbm_k_tksa (unsigned char addr);/
+<tag/Description/This function transmits a secondary address on the serial bus for a TALK device.
+<tag/Notes/<itemize>
+<item>The function is only available as fastcall function, so it may
+only be used in presence of a prototype.
+<item>The function can only be called after a call to TALK.
+<item>The function will not work after a LISTEN.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cbm_k_talk" name="cbm_k_talk">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>cbm_k_udtim<label id="cbm_k_udtim"><p>
 
 <quote>
@@ -2319,9 +2372,6 @@ bus. Only devices previously commanded to LISTEN are affected. This
 function is normally used after the host computer is finished sending data
 to external devices. Sending the UNLISTEN commands the listening devices
 to get off the serial bus so it can be used for other purposes.
-<tag/Notes/<itemize>
-<item>
-</itemize>
 <tag/Availability/cc65
 <tag/See also/
 <ref id="cbm_k_listen" name="cbm_k_listen">
@@ -2330,6 +2380,28 @@ to get off the serial bus so it can be used for other purposes.
 </quote>
 
 
+<sect1>cbm_k_untlk<label id="cbm_k_untlk"><p>
+
+<quote>
+<descrip>
+<tag/Function/Send an UNTALK command
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/void cbm_k_untlk (void);/
+<tag/Description/This function commands all devices on the serial bus to
+stop sending data to the host computer (i.e., UNTALK). Calling this
+function results in an UNTALK command being transmitted on the serial
+bus. Only devices previously commanded to TALK are affected. This
+function is normally used after the host computer is finished listening to data
+from an external device. Sending the UNTALK commands the sending devices
+to get off the serial bus so it can be used for other purposes.
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cbm_k_talk" name="cbm_k_talk">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>cclear<label id="cclear"><p>
 
 <quote>
@@ -3682,50 +3754,49 @@ header files define constants that can be used to check the return code.
 </quote>
 
 
-<sect1>get_turbomaster_speed<label id="get_turbomaster_speed"><p>
+<sect1>get_scpu_speed<label id="get_scpu_speed"><p>
 
 <quote>
 <descrip>
-<tag/Function/Get the current speed of the C64 Turbo Master cartridge.
+<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_turbomaster_speed (void);/
-<tag/Description/The function returns the current speed of the C64 Turbo Master cartridge.
+<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 C64.
-<item>The function does not check for the presence of the C64 Turbo master cartridge.
+<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_turbomaster" name="detect_turbomaster">,
-<ref id="set_turbomaster_speed" name="set_turbomaster_speed">,
+<ref id="detect_scpu" name="detect_scpu">,
+<ref id="set_scpu_speed" name="set_scpu_speed">,
 <tag/Example/None.
 </descrip>
 </quote>
 
 
-<sect1>get_scpu_speed<label id="get_scpu_speed"><p>
+<sect1>get_turbomaster_speed<label id="get_turbomaster_speed"><p>
 
 <quote>
 <descrip>
-<tag/Function/Get the current speed of the C64/C128 SuperCPU cartridge.
+<tag/Function/Get the current speed of the C64 Turbo Master 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/Declaration/<tt/unsigned char get_turbomaster_speed (void);/
+<tag/Description/The function returns the current speed of the C64 Turbo Master 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>The function is specific to the C64.
+<item>The function does not check for the presence of the C64 Turbo Master 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">,
+<ref id="detect_turbomaster" name="detect_turbomaster">,
+<ref id="set_turbomaster_speed" name="set_turbomaster_speed">,
 <tag/Example/None.
 </descrip>
 </quote>
 
-
 <sect1>getcpu<label id="getcpu"><p>
 
 <quote>
@@ -5844,7 +5915,7 @@ if (rename (OLDNAME, NEWNAME) == 0) {
 before a call to <tt/set_brk/.
 <tag/Notes/<itemize>
 <item>The break vector is reset on program termination, so it's not strictly
-necessary to call this function as a part of your clean-up when exitting the program.
+necessary to call this function as a part of your clean-up when exiting the program.
 </itemize>
 <tag/Availability/cc65
 <tag/See also/
@@ -5866,7 +5937,7 @@ necessary to call this function as a part of your clean-up when exitting the pro
 <tag/Description/<tt/reset_irq/ resets the C level interrupt request vector.
 <tag/Notes/<itemize>
 <item>The interrupt vector is reset on program termination, so it's not strictly
-necessary to call this function as a part of your clean-up when exitting the program.
+necessary to call this function as a part of your clean-up when exiting the program.
 </itemize>
 <tag/Availability/cc65
 <tag/See also/
@@ -6227,7 +6298,7 @@ the continue with the interrupted code, you have to adjust <tt/brk_pc/,
 otherwise the <tt/BRK/ instruction will get executed over and over again.
 <item>The break vector is reset on program termination, so it's not strictly
 necessary to call <tt/<ref id="reset_brk" name="reset_brk">/ as a part of your
-clean-up when exitting the program.
+clean-up when exiting the program.
 </itemize>
 <tag/Availability/cc65
 <tag/See also/
@@ -6265,7 +6336,7 @@ enable stack checks for the handler function or any other function called from
 it.
 <item>The interrupt vector is reset on program termination, so it's not strictly
 necessary to call <tt/<ref id="reset_irq" name="reset_irq">/ as a part of your
-clean-up when exitting the program.
+clean-up when exiting the program.
 </itemize>
 <tag/Availability/cc65
 <tag/See also/
@@ -6365,45 +6436,45 @@ clean-up when exitting the program.
 </quote>
 
 
-<sect1>set_turbomaster_speed<label id="set_turbomaster_speed"><p>
+<sect1>set_scpu_speed<label id="set_scpu_speed"><p>
 
 <quote>
 <descrip>
-<tag/Function/Set the current speed of the C64 Turbo Master cartridge.
+<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_turbomaster_speed (unsigned char speed);/
-<tag/Description/The function returns the speed after trying to set the speed of the C64 Turbo Master cartridge.
+<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 C64.
-<item>The function does not check for the presence of the C64 Turbo Master cartridge.
+<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_turbomaster" name="detect_turbomaster">,
-<ref id="get_turbomaster_speed" name="get_turbomaster_speed">,
+<ref id="detect_scpu" name="detect_scpu">,
+<ref id="get_scpu_speed" name="get_scpu_speed">,
 <tag/Example/None.
 </descrip>
 </quote>
 
 
-<sect1>set_scpu_speed<label id="set_scpu_speed"><p>
+<sect1>set_turbomaster_speed<label id="set_turbomaster_speed"><p>
 
 <quote>
 <descrip>
-<tag/Function/Set the current speed of the C64/C128 SuperCPU cartridge.
+<tag/Function/Set the current speed of the C64 Turbo Master 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/Declaration/<tt/unsigned char __fastcall__ set_turbomaster_speed (unsigned char speed);/
+<tag/Description/The function returns the speed after trying to set the speed of the C64 Turbo Master 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>The function is specific to the C64.
+<item>The function does not check for the presence of the C64 Turbo Master 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">,
+<ref id="detect_turbomaster" name="detect_turbomaster">,
+<ref id="get_turbomaster_speed" name="get_turbomaster_speed">,
 <tag/Example/None.
 </descrip>
 </quote>