Added _rxpoll() function

Author: totalspectrum

Changelog.txt

@@ -1,4 +1,5 @@
 Version 7.1.0
+- Added _rxpoll() to check for character without a timeout
 - Updated -gbrk debug code (thanks Ada)
 
 Version 7.0.5

doc/c.md

@@ -1066,7 +1066,11 @@ These ioctls get and set flags controlling the operation of terminals (e.g. the
 
 ### _rxraw
 
-Reads a single character from the default serial port, with no processing (no echoing and no CR/LF conversion). Takes a single parameter giving a timeout in milliseconds (with 0 meaning "no timeout, wait forever"). If a timeout occurs before the character is read, returns -1, otherwise returns the ASCII character read.
+Reads a single character from the default serial port, with no processing (no echoing and no CR/LF conversion). Takes a single parameter giving a timeout in milliseconds (with 0 meaning "no timeout, wait forever"). If a timeout occurs before the character is read, returns -1, otherwise returns the ASCII character read. See also `_rxpoll()`.
+
+### _rxpoll
+
+Attempts to read a single character from the default serial port. If no character is available, returns -1 immediately, otherwise returns the character. If you would prefer to wait for a character, use `_rxraw` instead.
 
 ### _txraw
 

doc/general.md

@@ -561,7 +561,7 @@ All languages have a `_setbaud(N)` function to set the baud rate to `N`.
 ### Sending and receiving characters
 
 All languages support some functions for doing basic serial I/O.
-`_tx(ch)` sends a character to the serial port, with appropriate carriage return mapping (see below for how this is changed). `_txraw(ch)` sends the character with no interpretation. `_rx()` reads a character from the serial port, waiting until one is available. `_rxraw(tim)` attempts to read a character, waiting for up to `tim` milliseconds (actually 1/1024ths of a second) for one to be available; if no character is received before the timeout, returns -1.
+`_tx(ch)` sends a character to the serial port, with appropriate carriage return mapping (see below for how this is changed). `_txraw(ch)` sends the character with no interpretation. `_rx()` reads a character from the serial port, waiting until one is available. `_rxraw(tim)` attempts to read a character, waiting for up to `tim` milliseconds (actually 1/1024ths of a second) for one to be available; if no character is received before the timeout, returns -1. `_rxpoll()` is like `_rxraw()` but returns -1 immediately if no character is available.
 
 ### Changing echo and CR/LF interpretation
 
@@ -925,7 +925,14 @@ sends character `c` out the default serial port. Always returns 1.
 ```
 int _rxraw(int n=0)
 ```
-Receives a character on the default serial port. `n` is a timeout in milliseconds. If the timeout elapses with no character received, `_rxraw` returns -1, otherwise it returns the received character. The default timeout (0) signifies "forever"; that is, if `n` is 0 the `_rxraw` function will wait as long as necessary until a character is received.
+Receives a character on the default serial port. `n` is a timeout in milliseconds. If the timeout elapses with no character received, `_rxraw` returns -1, otherwise it returns the received character. The default timeout (0) signifies "forever"; that is, if `n` is 0 the `_rxraw` function will wait as long as necessary until a character is received. If you would rather check for a character and have the function return immediately if none is available, use `_rxpoll()` instead of `_rxraw()`.
+
+#### _rxpoll
+
+```
+int _rxpoll()
+```
+Checks for a character on the default serial port. If no character is available, returns -1 immediately. Otherwise it returns the next character.
 
 #### _setbaud
 

sys/bytecode_rom.spin

@@ -308,6 +308,11 @@ pri _rxraw(timeout = 0)
   _remotecall(3, timeout)
   return __helper_arg[0]
 
+pri _rxpoll() | timeout
+  timeout := 1  ' wait minimal number of cycles
+  _remotecall(3, timeout)
+  return __helper_arg[0]
+
 ''
 '' divide (n, nlo) by d, producing qlo and rlo (used in FRAC operation)
 ''

sys/bytecode_rom.spin.h

@@ -150,6 +150,14 @@ pri _rxraw(timeout = 0) : rxbyte = long | z, endtime, temp2, rxpin
       if endtime - _getcnt() < 0
         quit
 
+' returns -1 immediately if no pending character
+pri _rxpoll() : rxbyte = long | z, rxpin
+  rxbyte := -1
+  rxpin := _rxpin
+  z := _pinr(rxpin)
+  if z
+    rxbyte := _rdpin(rxpin)>>24
+
 ''
 '' memset/memmove are here (in processor specific code)
 '' because on P2 we can optimize them (long operations do

sys/nucode_util.spin

@@ -175,6 +175,25 @@ pri _rxraw(timeout = 0) | val, waitcycles, i, bitcycles
   _waitcnt(waitcycles + bitcycles)
   return val
 
+' like _rxraw, but no timeout and returns -1 immediately if no data
+pri _rxpoll() | val, i, bitcycles, pin
+  bitcycles := _bitcycles
+  if (bitcycles == 0)
+    bitcycles := _setbaud(__default_baud__)
+  pin := _rxpin
+  dira[pin] := 0
+
+  if ina[pin] <> 0
+     return -1
+    
+  waitcycles := cnt + (bitcycles>>1)
+  val := 0
+  repeat 8
+    _waitcnt(waitcycles += bitcycles)
+    val := (ina[pin] << 7) | (val>>1)
+  _waitcnt(waitcycles + bitcycles)
+  return val
+
 pri _setbaud(rate) : r
   _bitcycles := r := __clkfreq_var / rate
 

sys/nucode_util.spin.h

@@ -217,6 +217,34 @@ pri _rxraw(timeout = 0) : rxbyte = long | z, endtime, temp2, rxpin
     rxbyte := temp2 & $ff
   _rx_temp := temp2
 
+' like _rxraw, but no timeout and returns -1 at once if no pending
+' character
+pri _rxpoll() : rxbyte = long | z, temp2, rxpin
+  if _bitcycles == 0
+    _setbaud(__default_baud__)
+  rxbyte := -1
+  rxpin := _rxpin
+  z := 0
+  temp2 := _rx_temp
+  '' slightly tricky code for pulling out the bytes from the 28 bits
+  '' of data presented by the smartpin
+  '' Courtesy of evanh
+  asm
+          testb  temp2, #8 wc     ' check framing of prior character for valid character   
+          testbn temp2, #9 andc   ' more framing check (1 then 0)
+          shr    temp2, #10       ' shift down next character, if any
+  if_c    mov    z, #1
+  if_c    jmp    #.breakone
+          testp  rxpin wz
+  if_z    mov    z, #1
+  if_z    rdpin  temp2, rxpin
+  if_z    shr    temp2, #32 - 28
+.breakone
+  endasm
+  if z
+    rxbyte := temp2 & $ff
+  _rx_temp := temp2
+  
 pri _dirl(pin = long)
   asm
     dirl pin