Jaap's Psion II Page

Home / Psion / Assembler Interface To Comms Link

Notes on the Assembler Interface To Comms Link Driver Code


COMMS LINK driver code is now interrupt driven and handles XON/XOFF and hardware handshaking at the lowest level. It also now parity checks all incoming data if parity is enabled.

As all serial I/O is now interrupt driven, interrupts CANNOT be disabled (as with the keyboard). All calls to the operating system via the SWI instruction are intercepted by the new driver code once the port has been opened, to make data pack access transparent (and possible!) while the port is open. It also ensures that the port is active and not affected by various power saving techniques in the operating system while it is open.

The function of the following operating system services are altered when the port is opened; PK$SETP, PK$PKOF, BZ$TONE, BZ$ALRM and BZ$BELL. As all SWI's and interrupts are intercepted directly, and the old handlers are not chained to, any other application that re-vectors the same services will not function correctly while the port is open. The old handlers are saved only when the comms pack is booted during the install code but are restored every time the port is closed. Any application booted in after the comms pack, which re-vectors any service used by the comms pack, will not function correctly even when the port has been closed as the original handler will be restored.

PK$SETP - This function will first wait for the correct time to elapse from the last character being sent and then switch off the port. From this point the port will no longer be able to receive characters. The operating system function will then select the pack in the normal way, and the next call made to a COMMS LINK service will switch the port on again.

PK$PKOF - This function will do nothing while the port is open.

BZ$TONE, BZ$ALRM, BZ$BELL These three functions will all just do a beep regardless of any parameters passed while the port is open because interrupts cannot be disabled.

The interface to the COMMS LINK driver code is via a block of fixed address memory of 40 bytes long starting at dvt_spar (=$214F). This memory is divided into two areas: a table of variables which set various i/o parameters and an entry point for calls to the driver code. All these variables and a macro for calling the driver code via this entry point are defined below.

The following variables can be set to control the function of the COMMS LINK driver code. However, these variables are also set by the SETUP option in the COMMS menu and by the LSET OPL function, so generally their values must be preserved.

AddressNameSizeRange
$2150rsb_baud1 byte0-950,75,110,150,300,600,1200,2400,4800,9600
$2151rsb_parity1 byte0-4NONE,ODD,EVEN,MARK,SPACE
$2152rsb_bits1 byte0-17 BIT DATA, 8 BIT DATA
$2153rsb_stop1 byte0-11 STOP BIT, 2 STOP BITS
$2154rsb_hand1 byte0-7NONE,XON,RTS,XON+RTS,DTR,DTR+XON,DTR+RTS,ALL
$2155rsb_proto1 byte0-2NONE, XMODEM, PSION (File transfer protocol)
$2156rsb_echo1 byte0-1LOCAL, HOST (Terminal emulation only)
$2157rsb_width1 byte0-250NONE,1-250 (Forced line width)
$2158rsb_timout1 byte0-255NONE,1-255 (LPRINT timeout in seconds)
$2159rst_reol3 bytes0-2NONE,1,2 (1st byte only, other two data)
$215Crst_reof3 bytes0-2NONE,1,2 (1st byte only, other two data)
$215Frst_rtrn3 bytes0-2NONE,1,2 (1st byte only, other two data)
$2162rst_teol3 bytes0-2NONE,1,2 (1st byte only, other two data)
$2165rst_teof3 bytes0-2NONE,1,2 (1st byte only, other two data)
$2168rst_ttrn3 bytes0-2NONE,1,2 (1st byte only, other two data)
$216Brsb_off_del1 byte1-255(Time to off delay in characters default=3)
$216Crsb_xoff_del1 byte1-255(Time to off delay with XON/XOFF default=7)
$216Drsb_tcon_val1 byte0-255Time constant value for timer 2 baud rate gen
$216Ersb_off_ticks1 byte0-255No. of ticks for baud rate dependent Tx off delay
$216Frsw_off_tcon2 bytes0-65535Time constant for single tick Tx off delay
$2171rsb_sec_timer1 byte0-255General purpose decrement to zero second timer
$2172RESERVED WORD2 bytes
$2174rst_entry_point3 bytes-Entry point for assembler interface

All the 3 byte fields are of the following format:

byte 0 = Length of data, 0 for none
byte 1 = First data byte (optional)
byte 2 = Second data byte (optional)

After any of these variables have been altered a call to rs$setvars must be made to set up various derived variables. None of these variables should be altered while the port is open.

In addition a general purpose timer is available, rsb_sec_timer. This location is decremented once every second if it is non-zero. This timer is used by the higher level functions such as LPRINT to implement time outs so be warned!

All calls to the COMMS LINK driver code are made via the macro "rs" which is defined below:-

; ; RS - Macro for assembler interface to COMMS LINK drivers ; .macro rs function jsr rst_entry_point .byte function .endm

Before using this macro a check must be made that the COMMS LINK code has been booted as follows:

ldx #opl_name ; choose an OPL function unique to COMMS-LINK os dv$lkup ; ask O/S if it's booted bcs not_booted ;ok to call rs$ routines now opl_name: .ascic "XFEOF"

The following functions are available:

Function No.FunctionDescription
0rs$openOpen the COMMS LINK channel
1rs$closeClose the COMMS LINK channel
2rs$putcharPut a character to the RS232 port
3rs$getcharGet a character from the RS232 port
4rs$flushFlush the receive buffer
5rs$setvarsSet the COMMS LINK variables up after a change
6rs$lprintPrint a string
7rs$linputInput a string
8rs$liconLink layer connect call
9rs$lidisLink layer disconnect call
10rs$liputLink layer put a frame call
11rs$ligetLink layer get a frame call

Example to open the RS232 port for reading and writing

clr b ; Open for reading and writing rs rs$open bcs error ; Deal with error ... ; Rest of code

Functions:-
In general all functions indicate an error condition by returning with the carry flag set and the appropriate error code in the B register.


Function name:rs$open
Function number:0
Input parameters:B reg - Mode to open.
Output values:Carry set if error, error number in B
Description:- Opens the RS232 channel and initialises the hardware, also sets various modes of operation for the port depending on the value passed in B.
Bits in B :
Bit 0 - Set if port in Tx only mode.
Bit 1 - Set to enable break key error inhibiting.
Bit 2 - Set if th Tx paused state is to be cleared.

If a pack access is made while RS232 is open this access will be delayed until any stray characters have been dealt with. Any subsequent calls to rs_putchar or rs_getchar will switch the port on again. If a call to rs$open is made while the port is already open the call is ignored.

Registers corrupted:All
Errors:Carry set, error number in b
ER_DV_NP - Device not present
ER_GN_BL - Battery too low

Function name:rs$close
Function number:1
Input parameters:B reg mode to close see below
Output parameters:Carry set if can not close port because host is busy
Description:- Closes the RS232 port, bits in B:
Bit 0 CLEAR port closed and is turned off later by pack access or key scan
Bit 0 SET port closed and turned off
Bit 1 CLEAR host paused state is ignored
Bit 1 SET port fails to close if the host is busy (paused by an XOFF)
Registers corrupted:All
Errors:Carry set if failed to close due to host busy

Function name:rs$putchar
Function number:2
Input parameters:A register - Character to be put to buffer
Output parameters:Carry set if error or busy, B clear or error number.
Description:- Transmits the passed character. Returns with the carry set if an error or the port was busy, else the carry is clear. B is clear if no error.
Registers corrupted:B,CCR
Errors:Carry set error number in B
ER_DV_CA - Invalid device call - Port not open
ER_RT_BK - Break Key
ER_GN_BL - Battery too low

Function name:rs$getchar
Function number:3
Input parameters:None
Output parameters:A register - Next character from receive buffer
Carry set if error or busy, B clear or error number.
Description:- Gets the next character from the receive buffer. Returns with carry set if error or no characters in the buffer, else the next character from the buffer in the A register B is clear.
Registers corrupted:A,B,CCR
Errors:Carry set error number in B
ER_DV_CA - Invalid device call - Port not open
ER_GN_RF - Device read fail - Parity or overrun
ER_RT_BK - Break Key
ER_GN_BL - Battery too low

Function name:rs$flush
Function number:4
Input parameters:None
Output parameters:None
Description:- Flushes the receive buffer.
Registers corrupted:CCR
Errors:None

Function name:rs$setvars
Function number:5
Input parameters:None
Output parameters:None
Description:- Sets the derived COMMS LINK variables after a change to the setable COMMS LINK variables.
Registers corrupted:All
Errors:None

Function name:rs$lprint
Function number:6
Input parameters:X register - Pointer to text to print
B register - Length of string to print
Output parameters:B register - Error code if any
Description:- Opens the RS232 port for output only, then writes the passed string to the port applying all the translates, timeouts etc specified.
Registers corrupted:All
Errors: ER_GN_BL - Battery too low
ER_GN_WF - Device write fail (Timeout)
ER_RT_BK - Break Key
ER_DV_NP - Device not present

Function name:rs$linput
Function number:7
Input parameters:A register - Timeout in seconds (0=no timeout)
B register - Number of characters to receive
X register - Address of buffer to place characters
Output parameters:B register - Error code if any
A register - Number of characters received
Description:- Opens the RS232 port for output and input and then reads the passed number of bytes into the passed buffer applying all the translates, timeouts etc specified.
Registers corrupted:All
Errors: ER_GN_BL - Battery too low
ER_GN_RF - Device read fail (Timeout)
ER_RT_BK - Break Key
ER_DV_NP - Device not present

Function name:rs$licon
Function number:8
Input parameters:None
Output parameters:B register - Error code if any
Description:- Attempts to establish a logical link with the correspondent link entity. Wait for a suitable acknowledgment.
Registers corrupted:All
Errors: ER_RT_F0 - a link already exists (local error)
ER_GN_RF - timeout trying to get a connection
Any errors that rs$open can return

Function name:rs$lidis
Function number:9
Input parameters:None
Output parameters:B register - Error code if any
Description:- Disconnect the logical link with the correspondent link layer. Harmless if the link is already disconnected.
Registers corrupted:All
Errors: ER_RT_FC - no link in existence
ER_GN_BL - Battery too low

Function name:rs$liput
Function number:10
Input parameters:D register - Length of buffer to send
X register - Address of buffer to send
Output parameters:B register - Error code if any
Description:- Send data in buf to the correspondent. The data length must be >=0 and <=MAXILEN. Waits for a suitable acknowledgment. (MAXILEN currently 260)
Registers corrupted:All
Errors: ER_RT_FC - a link does not exist (local error)
ER_GN_RF - a re-transmission threshold expired
ER_LX_ST - len exceeds MAXILEN (no data transferred)
A server disconnection reason code. E.g. "no disk space"
ER_GN_BL - Battery too low

Function name:rs$liget
Function number:11
Input parameters:D register - Number of bytes to get
X register - Address of buffer to put bytes
Output parameters:B register - Error code if any
D register - Number of bytes placed in buffer if OK
Description:- Wait for a frame to arrive from the physical layer. Returns number of bytes placed in buf if all ok.
Registers corrupted:All
Errors:
ER_RT_FC - a link does not exist (local error)
ER_GN_RF - a timer expired
ER_LX_ST - data length exceeds len - 1st len bytes in buf
A file server disconnection reason code. E.g. drive door open
ER_GN_BL - Battery too low