Added commented placeholder for future Mitsubishi 740 CPU in "cpu.mac".

[cc65] / doc / funcref.sgml

diff --git a/doc/funcref.sgml b/doc/funcref.sgml
index 64e5192389485a6971412ae82d6880569b167336..d4c2f3fe1ba11fc3ee650879f2e8f393d0f5fd95 100644 (file)
--- a/doc/funcref.sgml
+++ b/doc/funcref.sgml
@@ -3,7 +3,7 @@
 <article>
 <title>cc65 function reference
 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
-<date>2016-06-08
+<date>2016-08-07
 
 <abstract>
 cc65 is a C compiler for 6502 based systems. This function reference describes
@@ -169,8 +169,11 @@ function.
 <item><ref id="cbm_k_open" name="cbm_k_open">
 <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_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_udtim" name="cbm_k_udtim">
 <item><ref id="cbm_k_unlsn" name="cbm_k_unlsn">
 <!-- <item><ref id="cbm_load" name="cbm_load"> -->
 <!-- <item><ref id="cbm_open" name="cbm_open"> -->
@@ -2020,6 +2023,31 @@ only be used in presence of a prototype.
 </quote>
 
 
+<sect1>cbm_k_scnkey<label id="cbm_k_scnkey"><p>
+
+<quote>
+<descrip>
+<tag/Function/Scan the keyboard matrix.
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/void cbm_k_scnkey (void);/
+<tag/Description/This function looks at the switches in the keyboard, to see
+if any of them are being pressed.  If they are, then code numbers for them are
+stored in RAM.  Other functions use those numbers to input text.  Normally,
+the keyboard is scanned by the Kernal's Interrupt Service Routine.  But, if
+you divert the "Jiffy interrupt" to a C-code ISR, then that ISR must call this
+function, in order to provide input from the keyboard.
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cbm_k_getin" name="cbm_k_getin">,
+<ref id="cbm_k_udtim" name="cbm_k_udtim">,
+<ref id="cgetc" name="cgetc">,
+<!-- <ref id="getc" name="getc"> -->
+<!-- <ref id="getchar" name="getchar"> -->
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>cbm_k_setlfs<label id="cbm_k_setlfs"><p>
 
 <quote>
@@ -2085,6 +2113,27 @@ only be used in presence of a prototype.
 </quote>
 
 
+<sect1>cbm_k_udtim<label id="cbm_k_udtim"><p>
+
+<quote>
+<descrip>
+<tag/Function/Update the Jiffy clock.
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/void cbm_k_udtim (void);/
+<tag/Description/This function adds one count to the Jiffy clock.  That clock
+counts sixtieths of a second.  It is used by the library's <tt/clock()/
+function.  Normally, the Jiffy clock is updated by the Kernal's Interrupt
+Service Routine.  But, if you divert the "Jiffy interrupt" to a C-code ISR,
+then that ISR must call this function, in order to keep the clock valid.
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cbm_k_scnkey" name="cbm_k_scnkey">,
+<ref id="clock" name="clock">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>cbm_k_unlsn<label id="cbm_k_unlsn"><p>
 
 <quote>
@@ -2164,15 +2213,18 @@ only be used in presence of a prototype.
 <tag/Header/<tt/<ref id="conio.h" name="conio.h">/
 <tag/Declaration/<tt/char cgetc (void);/
 <tag/Description/The function reads a character from the keyboard. If there is
-no character available, <tt/cgetc/ waits until the user presses a key. If the
+no character available, <tt/cgetc()/ waits until the user presses a key. If the
 cursor is enabled by use of the <tt/cursor/ function, a blinking cursor is
 displayed while waiting.
 <tag/Notes/<itemize>
-<item>If the system supports a keyboard buffer, <tt/cgetc/ will fetch a key
-from this buffer and wait only if the buffer is empty.
+<item>If the system supports a keyboard buffer, <tt/cgetc()/ will fetch a key
+from that buffer; and, wait only if the buffer is empty.
+<item>The keyboard must be scanned periodically, in order for this function to
+see anything that you type.  (See the description of <tt/cbm_k_scnkey()/.)
 </itemize>
 <tag/Availability/cc65
 <tag/See also/
+<ref id="cbm_k_scnkey" name="cbm_k_scnkey">,
 <ref id="cursor" name="cursor">,
 <ref id="kbhit" name="kbhit">
 <tag/Example/None.
@@ -2262,16 +2314,19 @@ used in presence of a prototype.
 <tag/Header/<tt/<ref id="time.h" name="time.h">/
 <tag/Declaration/<tt/clock_t clock (void);/
 <tag/Description/The <tt/clock/ function returns an approximaton of processor
-time used by the program. The time is returned in implementation defined
+time used by the program. The time is returned in implementation-defined
 units. It can be converted to seconds by dividing by the value of the macro
 <tt/CLOCKS_PER_SEC/.
 <tag/Notes/<itemize>
-<item>Since the machines, cc65 generated programs run on, cannot run multiple
-processes, the function will actually return the time since some
-implementation defined point in the past.
+<item>Since the machines that cc65-generated programs run on cannot run multiple
+processes, the function actually will return the time since some
+implementation-defined point in the past.
+<item>The Jiffy clock must be "running", in order for this function to return
+changing values.  (See the description of <tt/cbm_k_udtim()/.)
 </itemize>
 <tag/Availability/ISO 9899
 <tag/See also/
+<ref id="cbm_k_udtim" name="cbm_k_udtim">,
 <ref id="time" name="time">
 <tag/Example/None.
 </descrip>