Merge pull request #332 from greg-king5/interrupt-functions

Add C-code interfaces for the CBM Kernal functions SCNKEY and UDTIM.

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
+<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.
+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
+<item>Since the machines that cc65-generated programs run on cannot run multiple
-processes, the function will actually return the time since some
+processes, the function actually will return the time since some
-implementation defined point in the past.
+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>

include/cbm.h

@@ -187,10 +187,12 @@ unsigned int __fastcall__ cbm_k_load(unsigned char flag, unsigned addr);
 unsigned char cbm_k_open (void);
 unsigned char cbm_k_readst (void);
 unsigned char __fastcall__ cbm_k_save(unsigned int start, unsigned int end);
+void cbm_k_scnkey (void);
 void __fastcall__ cbm_k_setlfs (unsigned char LFN, unsigned char DEV,
                                 unsigned char SA);
 void __fastcall__ cbm_k_setnam (const char* Name);
 void __fastcall__ cbm_k_talk (unsigned char dev);
+void cbm_k_udtim (void);
 void cbm_k_unlsn (void);
 
 

libsrc/cbm/c_scnkey.s

@@ -0,0 +1,8 @@
+;
+; 2016-08-07, Greg King
+;
+; void cbm_k_scnkey (void);
+;
+
+        .import         SCNKEY
+        .export         _cbm_k_scnkey := SCNKEY

libsrc/cbm/c_udtim.s

@@ -0,0 +1,8 @@
+;
+; 2016-08-07, Greg King
+;
+; void cbm_k_udtim (void);
+;
+
+        .import         UDTIM
+        .export         _cbm_k_udtim := UDTIM

libsrc/plus4/kscnkey.s

@@ -0,0 +1,19 @@
+;
+; 2002-11-22, Ullrich von Bassewitz
+; 2016-08-07, Greg King
+;
+; SCNKEY replacement function
+;
+
+        .export         SCNKEY
+
+        .include        "plus4.inc"
+
+.segment        "LOWCODE"               ; Must go into low memory
+
+.proc   SCNKEY
+        sta     ENABLE_ROM              ; Enable the ROM
+        jsr     $FF9F                   ; Call the ROM routine
+        sta     ENABLE_RAM              ; Switch back to RAM
+        rts                             ; Return to caller
+.endproc

libsrc/plus4/kudtim.s

@@ -0,0 +1,19 @@
+;
+; 2002-11-22, Ullrich von Bassewitz
+; 2016-08-07, Greg King
+;
+; UDTIM replacement function
+;
+
+        .export         UDTIM
+
+        .include        "plus4.inc"
+
+.segment        "LOWCODE"               ; Must go into low memory
+
+.proc   UDTIM
+        sta     ENABLE_ROM              ; Enable the ROM
+        jsr     $FFEA                   ; Call the ROM routine
+        sta     ENABLE_RAM              ; Switch back to RAM
+        rts                             ; Return to caller
+.endproc