Quick Reference Table

Background

The Serial Controller Interface is the hardware subsystem that deals with all transactions over the main serial port (UART). These functions provide a high level interface to the SCI while also facilitating easy use of all features. The functions are split up into three different groups. Listed first are a set macro functions that mimic the functionality of many de facto standard I/O calls that, while not ANSI, are commonplace in the desktop programming world. These functions are usually straight pass-throughs to the corresponding driver calls. The second group of calls described herein are the driver calls that will be used in normal use of the SCI covering many different methods of input and output, timing and control. Lastly there are a handful of low-level helper functions that modularize some of the functionality behind the main driver calls. These functions will never be called directly from your user applications but are documented with the primary intent of providing a patching mechanism. This allows a user to change the behavior of some of the driver calls in ways which may facilitate the implementation of their specific application.

STDIO Warning

The ANSI C I/O libraries provided with the CF1 are, for the most part, even higher level wrappers to these driver functions. However, in an effort of duplicate exactly the behavior of the ANSI stdio system, the stdio functions often provide software buffering and queues. While you should feel free to use and intermingle both these driver level functions and stdio functions, it should be noted that due to the software buffering used by the stdio library, the outcome of intermingling these two groups of functions can yield unexpected results. If you, as a developer, choose to use both libraries, you should be careful to flush the buffers of each subsystem (driver calls and stdio) before using the other. Not doing so will not cause any fatal problems, but can cause confusion. For instance, if you were using the stdio printf function, and then immediately followed it with a driver call that also output data to the serial port, it is likely that the data output by the driver call would appear on the serial port before the data printed with stdio printf.

Error Codes

Many of the driver calls, particularly those which deal with fetching a byte from the receive portion of the main UART, return a short integer (16 bits) instead of a char (8 bits) as you might expect. The reason for this is so that error information can be passed back with the character. The character fetched is always in the LSB(low 8 bits) of the short so that if it is automatically typecast into a char, your character will survive and only the error codes will be lost. Similarly, if a char is passed to a function that expects a short for the purpose of holding error codes in the MSB, there should not be any unexpected behavior. In the MSB (high 8 bits) are error codes that are tested using the following masks, taken from cf1bios.h, and hopefully explained here:

RxD_OR_MASK

RxD_NF_MASK

RxD_FE_MASK

RxD_PF_MASK

RxD_BOV_MASK

RxD_ERR_MASK

By AND'ing any of these masks with the short that is returned with a given function, the user's application can determine what, if any, error occurred during the operation.

SCI and EIA Introduction

The CF1 has a dual RS-232 (MAX3222) driver with one receiver and transmitter pair assigned to the SCI /RXD and /TXD signals, and the other pair assigned to digital I/O lines. Both the CMOS and EIA signals are brought on connector C so this spare pair can be used for hardware handshaking (RTS, CTS, DTR, DTS) or as primary EIA level drivers for an external UART like the Maxim MAX3100.

These connections are summarized below:

Pin:	Name:	Type:	Dir:	9.DTE.25	9.DCE.25
44	RSTXD	RS232	Out	3 TXD 2	2 RXD 3
46	/TXD	CMOS	I/O	------	------
42	RSRXD	RS232	In	2 RXD 2	3 TXD 2
45	/RXD	CMOS	In	------	------
47	RSTXX	RS232	Out	7 RTS 4	8 CTS 5
48	/TXX	CMOS	I/O	------	------
49	RSRXX	RS232	In	8 CTS 5	7 RTS 4
50	/RXX	CMOS	I/O	------	------

..TXD is transmit data

..RXD is receive data

..TXX is transimit handshake or auxiliary (also labeled as RSRTS in some CF1 docs)

..RXX is transimit handshake or auxiliary (also labeled as RSCTS in some CF1 docs)

The 9.DTE.25 shows the pin connections to a DB9 or DB25 when the CF1 is designated as the data terminal equipment (DTE) device. Computers are generally configured as DTE devices, but ...

The 9.DCE.25 shows the pin connections to a DB9 or DB25 when the CF1 is designated as the data communications equipment (DCE) device. It's generally modems that are configured as DCE devices, but ...

The CF1 complicates things a bit since its designation is context dependent and is even likely to change roles when you switch between development and deployment modes. During development, setup or data recovery, the PC that you use as a terminal is the DTE device and expects to be talking to a DCE. In your remote application however, you may be assigning the SCI to talk to a smart instrument or communications device that will likely be a DCE device and expecting to talk to a DTE.

Most CF1 RecipeCards come with cabling that ends up at a DB9F connector setup as a DCE which mates directly (or with an extension cable) to the standard COMM port connectors on your PC. Some RecipeCards will have board mounted DB9Fs and others will use an adapter cable that mates at one end to a standard 10-pin DIP header. In either case, these bring the handshake or auxiliary RS-232 signals to the RTS and CTS signals at the PC to permit hardware flow control with PC communications programs.

Using BIOS calls the MAX3222 RS-232 transmitters can be enabled and disabled independently of the receivers, which can also be turned off under software control. Disabling the transmitters can save several milliamps of current drain for times when your program does not need to be sending data, but incoming data will still be received. If you're using flow control however, turning off the transmitters will probably make the PCs CTS signal appear negated and the PC will refuse to send any data. If you disable both the transmitters and receivers, the MAX3222 becomes effectively disconnected from the CF1 circuitry and you can safely insert alternate RS-232, RS-485, RS-422, CMOS, or IRDA drivers in place of the default drivers by connecting to the CF1 connector C CMOS level signals.

Similarly, under software control, you can define any or all of the CMOS control signals going to the MAX3222 as digital inputs that will be ignored by the 68338. Doing this, while keeping the transmitters or receivers enabled, lets you use the onboard MAX3222 RS-232 driver by connecting your offboard CMOS control signals to the effectively disabled onboard CMOS control signals through connector C. Though it's unlikely you would want to do this for the main SCI RXD and TXD, this could be very handy for getting RS-232 levels to an add-on single chip UART like the MAX3100 using the TXX and RXX connections.

On power-up, the CF1 assigns all of these signals to the 68338 and asserts TXX to allow communication with devices expecting hardware flow control. If you will be assigning the auxiliary transmitter to offboard hardware, you will need to make sure that the connected signal either tri-states until the onboard signal can be turned off, or you can connect to pin 48 through a 4.7K resistor which will limit the contention current to a safe amount without degrading signal switching speed.

However, if you watch this signal with a scope, you will see it toggle between 0V when idle, and a positive voltage when echoing characters. This is because by default, PicoDOS turns off the RS-232 transmitters between commands and drops into LPSTOP to conserve power.

From within your program you can use the PIORead() function or PinRead() macro specifying 48 or "TXX" as the sole argument to revert the CTIO2 pin to an input. From the PicoDOS command line or from within a batch file, you can use the command "PR 48" to revert the pin to an input. Pin 48 has a weak (1M) pullup, so with no external signal, the RS-232 level (pin 49) will mark at a negative voltage.

Driver Functions SCIConfigure -- Set the baud rate and parity

Sets the baud rate, parity, stop bits and auto-recalculation settings for the main UART. This is the primary means by which a user's application can change the serial port settings.

Prototype:	long SCIConfigure(long baud, char parity, bool autoTiming);
Definition:	#include <cf1bios.h>
Inputs:	baud is a long integer containing the desired baud rate parity is a character containing a code to specify the parity and stop bits settings desired. The codes are listed below. autoTiming is a Boolean indicating whether or not you would like the SCI to recalculate the baud rate in the event of a clock speed change. TRUE means do recalculate.
Returns:	Returns a copy of the argument baud.
Notes:	Parity codes are as follows: 'N' = '0' = '1' = No Parity and 1 Stop Bit '2' = No Parity and 2 Stop Bits 'E' = Even Parity and 1 Stop Bit  'O' = Odd Parity and 1 Stop Bit
Timing:	approx. 85 µsecs @ 16 MHz

SCIGetConfig -- Get the baud rate and parity

SCIGetConfig is used to extract the current settings of the SCI including baud rate and parity. Parity and stop bit information is returned in the form of a character that corresponds to a code which is described below. If either of the pointers passed to SCIGetConfig are NULL, the function will not write to the base of memory, but rather ignore that parameter. It will always return the baud rate, even if baudPtr is NULL.

Prototype:	long SCIGetConfig(long *baudPtr, char *parityPtr);
Definition:	#include <cf1bios.h>
Inputs:	baudPtr is a pointer to a long where SCIGetConfig should put the returned baud rate. parityPtr is a pointer to a character where SCIGetConfig should put the code which denotes the current parity/stop bit setting.
Returns:	Returns a long equal to the baud rate (equal to *baudPtr)
Notes:	Parity is denoted by a character containing a code to specify the parity and stop bits settings. The codes are as follows: 'N' = '0' = '1' = No Parity and 1 Stop Bit '2' = No Parity and 2 Stop Bits 'E' = Even Parity and 1 Stop Bit  'O' = Odd Parity and 1 Stop Bit
Timing:	approx. 28 µsecs @ 16 MHz

SCIInit -- Initialize the SCI hardware module

This function initializes the Serial Controller Interface hardware and software subsystems of your CF1. In normal use, this function should never be called from a user application and is included here only in the interests of a complete function reference. It is normally called by the when the machine starts up.

Prototype:	void SCIInit(void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	approx. 233 µsecs @ 16 MHz

SCINotifyPostClockChange -- Finish updating after a clock change

This function allows the SCI hardware and software subsystems to finish its adjustments after clock change. This is especially relevant if, in a call to SCIConfigure, autoTiming was true. This function should never be called from a user application and is included here only in the interests of a complete function reference.

Prototype:	void SCINotifyPostClockChange(void) ;
Definition:	#include <cf1bios.h>
Notes:
Timing:	approx. 31 µsecs @ 16 MHz

SCINotifyPreClockChange -- Prepare the SCI for a pending clock change

This function prepares the SCI hardware and software subsystems for an imminent clock change. This is especially relevant if, in a call to SCIConfigure, autoTiming was true. This function should never be called from a user application and is included here only in the interests of a complete function reference.

Prototype:	void SCINotifyPreClockChange(void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	approx. 9 µsecs @ 16 MHz

SCIRxBreak -- Return true if break is seen for at least millisecs

This function can be called to determine if a long break signal is being received. This function will return true if the break signal is received for at least duration millisecs ms. If the serial line was not in a break condition when the function is called, it will return FALSE immediately.

Prototype:	bool SCITxBreak(short millisecs)
Definition:	#include <cf1bios.h>
Inputs:	millisecs is the length of the break for which you wish to test.
Returns:	Returns a Boolean that is TRUE if a break of the specified length was received.
Notes:
Timing:	From 11 µsecs if no break condition exists up to within 1 on the order of magnitude of millisecs.

SCIRxFlush -- Delete any data in the receive queue

SCIRxFlush simply purges the receive queue and throws away any data contained therein.

Prototype:	void SCIRxFlush(void)
Definition:	#include <cf1bios.h>
Notes:	See STDIO Warning.
Timing:	11 µsecs

SCIRxGetByte -- Return the next word, wait if block is true

SCIRxGetByte retrieves one byte from the main UART. If block is TRUE and no characters are available, the function will wait until a character is available before returning. If block is false, and there are no characters are available it will return -1. If a byte was received, the function will return that byte in the LSB of the short returned. The MSB will contain error codes if applicable.

Prototype:	ushort SCIRxGetByte(bool block);
Definition:	#include <cf1bios.h>
Inputs:	block - a Boolean, TRUE if the call should wait until a byte has been received to return
Returns:	Returns a short, the LSB of which contains the byte gotten or -1 if block was false and there was not a byte available in the receive queue.
Notes:	See STDIO Warning. See Error Codes.
Timing:	Depends on argument, buffering mode, buffer condition, and serial line condition.

SCIRxGetChar -- Wait for, and return the next word

This command waits for and returns the next byte from the UART. In the high byte of the short returned are error codes, if applicable.

Prototype:	short SCIRxGetChar(void);
Definition:	#include <cf1bios.h>
Returns:	The character gotten from the UART is returned in the LSB of the short and the MSB contains error codes.
Notes:	See STDIO Warning. See Error Codes.
Timing:	Depends upon buffering mode, buffer condition, serial line condition and baud rate.

SCIRxGetCharWaitIdle -- Wait for incoming serial to idle with ms delay

This function waits for the receive line to be idle for millisecs ms and then returns the last character that came in before the idle was completed. An example of usage would be to handle long streams of garbage data coming in on the UART. You want to ignore all of the garbage and wait for the other end to stop sending.

Prototype:	short SCIRxGetCharWaitIdle(short millisecs)
Definition:	#include <cf1bios.h>
Inputs:	millisecs - number of milliseconds you wish the incoming serial line to be idle before returning from the function.
Returns:	The last character received before the serial port went idle.
Notes:	See STDIO Warning.
Timing:	Depends on argument, buffer condition, and serial line conditions.

SCIRxGetCharWithTimeout -- Return next byte from receive queue with timeout

This command waits up to millisecs ms for the next character to arrive on the main UART. In the high byte of the short returned are error codes, if applicable. If the function times out, it will return -1.

Prototype:	short SCIRxGetCharWithTimeout(short millisecs);
Definition:	#include <cf1bios.h>
Inputs:	millisecs - the number of milliseconds to wait for a character before returning an error.
Returns:	A short, the LSB of which contains the character gotten, or which equals -1 if the function times out.
Notes:	See STDIO Warning. See Error Codes.
Timing:	Within 1 on the milliseconds order of magnitude.

SCIRxGetFinalChar -- Empty receive queue and return last word

This will discard the entire contents of the receive queue excepting the last byte, which gets returned in the LSB of the returned short. In the high byte of the short returned are error codes, if applicable.

Prototype:	short SCIRxGetFinalChar(void);
Definition:	#include <cf1bios.h>
Returns:	The last character in the receive buffer at the time the function was called is returned in the low byte of the short and the high byte contains error codes, if applicable.
Notes:	See STDIO Warning. See Error Codes.
Timing:	approx. 11 µsecs @ 16MHz

SCIRxGetLine -- input line with minimal editing features

SCIRxGetLine() receives characters from the main UART until a newline is found or until len characters have been buffered in. It also sets up the UART in a way to allow the use of the backspace key for interactive sessions. The short returned is the actual number of characters received. In an interactive session, input may be aborted if the user presses <Control C>. In this event the value returned by the function will be 0 regardless of how many characters were entered before <Control C> was pressed.

Prototype:	short SCIRxGetLine(char *buf, short len);
Definition:	#include <cf1bios.h>
Inputs:	buf is a pointer to a buffer of chars of at least length len. len is the maximum number of characters to return.
Returns:	Returns the number of characters actually received.
Notes:	See STDIO Warning.
Timing:	Dependent on many factors not the least of which are buffering mode, buffer condition, serial line condition, and baud rate.

SCIRxHandshake -- Set receive flow control

The BIOS SCI functions provide both hardware and software flow control options for both input and output operations with the setup functions SCIRxHandshake() and SCITxHandshake() and three enumerated setup constants.

Input flow control, when enabled, tells the connected serial transmitting device to stop sending data when the CF1's 2048 word input buffer gets to within 256 words of overflowing. This gives the sender a minimum of 10ms at 230,400 BAUD to recognize the request and stop transmitting. For hardware flow control, the stop mechanism is the negation of the RSTXX signal (EIA negative). For software flow control, the stop mechanism is the transmission by the CF1 of an XOFF character, which can be user defined, but is typically a control-S (0x13) character.

When the buffer empties to within 512 words of overflowing, the CF1 tells the transmitting device that it's ok to resume sending data. This 256 words of hysteresis keeps from tying up both the receiver and transmitter with flow control signals possibly accompanying each character. For hardware flow control, the resume mechanism is the assertion of the RSTXX signal (EIA positive). For software flow control, the stop mechanism is the transmission by the CF1 of an XON character, which can be user defined, but is typically a control-Q (0x11) character.

Prototype:	void SCIRxHandshake(short hshk, char xon, char xoff)
Definition:	#include <cf1bios.h> defines: enum { hshkOff, hshkXonXoff, hshkCtsRts };
Inputs:	hshk is the enumerated handshake selector (hshkOff by default) xon is the character sent from the CF1 to resume transmission (CTRL-Q by default). xoff is the character sent from the CF1 to pause transmission (CTRL-S by default)
Notes:	Flow control can be OFF (hshkOff), ON using the auxiliary RS-232 control signals (hshkCtsRts), or ON using definable XON/XOFF characters. Flow control is only supported when the input or output drivers are working in buffered (interrupt driven) modes.
Timing:	N/A

SCIRxQueuedCount -- Return the number of characters in the receive queue

This function allows you to find out how many characters are waiting in the receive queue to be received. In polled buffering mode this function will always return either 1 or 0 depending on the existence of a character waiting in the UART receive register. In interrupt-driven buffering mode, this function returns the number of characters waiting in the receive queue, up to the maximum, 2048.

Prototype:	short SCIRxQueuedCount(void);
Definition:	#include <cf1bios.h>
Returns:	Returns the number of characters currently in the receive queue.
Notes:
Timing:	5.9 µsecs

SCIRxSetBuffered -- Select buffered (true) or non-buffered receive

This function allows you to change the buffering scheme for the receive line of the main UART. By specifying interrupt driven buffering mode, the CF1's internal BIOS buffering scheme is activated providing an transparent receive buffer of 2048 characters. In polled buffering mode the receive queue still "exists" but have a size of one character reflecting the fact that only the internal UART registers are being used for buffering.

Prototype:	void SCIRxSetBuffered(bool buffered);
Definition:	#include <cf1bios.h>
Inputs:	buffered - a Boolean used to specify the buffering mode desired. TRUE selects interrupt-driven buffering mode and FALSE selects polled mode or non-buffered mode.
Notes:
Timing:	29 µsecs

SCIRxTxIdle -- Return true if all Rx and Tx flags indicate idle

Returns a boolean that is TRUE if both the transmit and receive sections of the UART are idle and both queues are empty.

Prototype:	bool SCIRxTxIdle(void);
Definition:	#include <cf1bios.h>
Returns:
Notes:	This could be used to determine if the UART is ready to be shut down.
Timing:	4.9 µsecs

SCITxBreak -- Start (-1) , stop (0) , or send timed break (+ val)

SCITxBreak sets the UART to transmit a break condition for the specified duration or to start or stop an indefinite break.

Prototype:	void SCITxBreak(short millisecs)
Definition:	#include <cf1bios.h>
Inputs:	millisecs is the duration of the desired break in milliseconds. If it is -1 it will start an indefinite break and return, if it is 0 it will stop an indefinite break and return.
Notes:
Timing:	8 µsecs to stop and start. Specified duration breaks will be within 1 on the order of magnitude of millisecs.

SCITxFlush -- Delete any data in the transmit queue

SCITxFlush empties the transmit buffer and throws away any data not yet transmitted out the UART.

Prototype:	void SCITxFlush(void);
Definition:	#include <cf1bios.h>
Notes:	See STDIO Warning.
Timing:	7.5 µsecs

SCITxHandshake -- Set transmit flow control

The BIOS SCI functions provide both hardware and software flow control options for both input and output operations with the setup functions SCIRxHandshake() and SCITxHandshake() and three enumerated setup constants.

Output flow control, when enabled, lets the connected serial receiving device tell the CF1 to stop sending data when the receiver's senses it is near overflow. For hardware flow control, the stop mechanism is the detection of a negated RSRXX signal (EIA negative). For software flow control, the stop mechanism is the receipt of an an XOFF character, which can be user defined, but is typically a control-S (0x13) character.

The CF1 resumes transmitting when the receiving device tells the CF1 it's ok to resume sending data. For hardware flow control, the resume mechanism is the detection by the CF1 of an asserted RSRXX signal (EIA positive). For software flow control, the resume mechanism is the receipt by the CF1 of an XON character, which can be user defined, but is typically a control-Q (0x11) character.

Prototype:	void SCITxHandshake(short hshk, char xon, char xoff)
Definition:	#include <cf1bios.h> defines: enum { hshkOff, hshkXonXoff, hshkCtsRts };
Inputs:	hshk is the enumerated handshake selector (hshkOff by default) xon is the character sent to the CF1 to resume transmission (CTRL-Q by default). xoff is the character sent to the CF1 to pause transmission (CTRL-S by default)
Notes:	Flow control can be OFF (hshkOff), ON using the auxiliary RS-232 control signals (hshkCtsRts), or ON using definable XON/XOFF characters. Flow control is only supported when the input or output drivers are working in buffered (interrupt driven) modes.
Timing:	N/A

SCITxPrintf -- Simple printf to SCI with no floating point

Provides the same functionality as the ANSI C library function printf() with respect to the main UART, excepting floating point number display support. The types float, double and long long, cannot be output by SCITxPrintf(). Full documentation of the printf() function and its many format specifiers and conventions is beyond the scope of this BIOS manual, please see an ANSI function reference for a more detailed description of printf() usage.

Prototype:	void SCITxPrintf(const char * format, ...);
Definition:	#include <cf1bios.h>
Inputs:	See ANSI C documentation of printf function arguments and behavior.
Notes:	See STDIO Warning.
Timing:	Depends upon arguments, baud rate and buffer mode and conditions.

SCITxPutByte -- Transmit byte, wait if block is true

SCITxPutByte transmits one byte out the main UART. If block is TRUE and the transmit buffer is full, the function will wait until it is able to enqueue the byte before returning. If block is false, and the function cannot enqueue the byte it will return FALSE without enqueuing. If the byte was enqueued or transmitted, the function will return TRUE.

Prototype:	bool SCITxPutByte(ushort data, bool block)
Definition:	#include <cf1bios.h>
Inputs:	data - a short, the LSB of which should contain the byte you wish to send. block - a Boolean, true if the call should wait until byte has been sent to return
Returns:	Returns true if byte was transmitted, or false if block was set to false and the byte could not be transmitted or enqueued (depending on buffering mode) immediately.
Notes:	See STDIO Warning.
Timing:	Depends on argument, buffering mode, buffer condition, and serial line condition.

SCITxPutChar -- Transmit byte

This function takes the LSB of data and puts it in the transmit queue of the main UART. If the SCI is in polled mode, SCITxPutChar() will wait for the transmit queue to be empty and then write the LSB of data to the main UART. The MSB of data is always ignored.

Prototype:	void SCITxPutChar(ushort data);
Definition:	#include <cf1bios.h>
Inputs:	data is a ushort, the LSB of which is the character you wish to transmit.
Notes:	See STDIO Warning.
Timing:	Depends on buffering mode, buffer conditions, line condition and baud rate.

SCITxPutStr -- Transmit zero terminated string with C '\n' to '\r'-'\n' translation

Writes the NULL terminated string pointed to by str to the transmit queue of the main UART. SCITxPutStr() will not append any characters to the end of any string passed to it, however it will replace any "newline" characters (/n) already in the string with CRLF sequences before inserting it into the buffer.

Prototype:	void SCITxPutStr(const char *str);
Definition:	#include <cf1bios.h>
Inputs:	str is a pointer to a NULL terminated string.
Notes:	See STDIO Warning.
Timing:	Depends on baud rate and buffering mode.

SCITxQueuedCount -- Return the number of words in the transmit queue

This function allows you to find out how many characters are waiting in the transmit queue. In polled buffering mode this function will always return either 1 or 0 depending on the existence of a character waiting in the UART transmit register. In interrupt-driven buffering mode, this function returns the number of characters waiting in the transmit queue, up to the maximum, 512.

Prototype:	short SCITxQueuedCount(void);
Definition:	#include <cf1bios.h>
Returns:	Returns the number of characters currently in the receive queue.
Notes:
Timing:	4.9 µsecs

SCITxSetBuffered -- Select buffered (true) or non-buffered transmit

This function allows you to change the buffering scheme for the transmit line of the main UART. By specifying interrupt driven buffering mode, the CF1's internal BIOS buffering scheme is activated providing an transparent transmit buffer of 512 characters. In polled buffering mode the transmit queue still "exists" but have a size of one character reflecting the fact that only the internal UART registers are being used for buffering.

Prototype:	void SCITxSetBuffered(bool buffered);
Definition:	#include <cf1bios.h>
Inputs:	buffered - a Boolean used to specify the buffering mode desired. TRUE selects interrupt-driven buffering mode and FALSE selects polled mode or non-buffered mode.
Notes:
Timing:	29 µsecs

SCITxWaitCompletion -- Wait for all transmission to complete

SCITxWaitCompletion waits for the transmit buffer to finish sending all characters in the buffer and then returns.

Prototype:	void SCITxWaitCompletion(void);
Definition:	#include <cf1bios.h>
Notes:	See STDIO Warning.
Timing:	Depends on buffering mode, baud rate and number of characters in the transmit buffer.

Low Level Functions for System Use and Specialty Patches

SCIEnableErrTrap -- Enable/Disable SCI error trapping

This function is used to turn on and off the trapping of errors in the SCI subsystem. If this function is called with TRUE for dotrap, then if there are any error, the machine will cease execution and print a debugging message. Otherwise, errors will be passed back through the return mechanism to be dealt with at the application level.

Prototype:	void SCIEnableErrTrap(bool dotrap);
Definition:	#include <cf1bios.h>
Inputs:	dotrap is a Boolean that indicates which of two actions should be taken in the event of a receive error. TRUE tells the Persistor to throw an exception and crash if there is a receive error, and FALSE implies that the error and the garbage character should be passed back into the program for a user-level handler to deal with.
Notes:	See also SCIRxErrorSignal.
Timing:	4.4 µsecs

SCIRxBlocked -- Called when receive routine is waiting for data

This function is not one that would be called from a user's application. It exists as a helper function to SCIRxGetByte, called by SCIRxGetByte in a tight loop, to "kill time" during a blocking receive operation. If you have code that you would like to have executed during a blocking receive operation you could patch this function.

Prototype:	void SCIRxBlocked(void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	N/A

SCIRxErrorSignal -- Return error or take SCIErrorTrap

This function will be called each time there is a receive error, such as a framing error or a parity error. The action it takes is determined by the SCIEnableErrTrap function. It will either return the garbage character in the LSB of a ushort, the MSB of which contains error codes describing the error, or it will throw an exception and the Persistor will crash. For a more detailed description of the error codes returned when not rapping errors see the Error Codes section.

Prototype:	ushort SCIRxErrorSignal(ushort data:__d0):__d0;
Definition:	#include <cf1bios.h>
Inputs:	data is a ushort the MSB of which will contain error codes, and the LSB of which will most likely contain garbage.
Returns:	Returns data.
Notes:	See Error Codes.
Timing:	N/A

SCIRxFilter -- Filter incoming serial data

This function is not one that would be called from a user's application. It is made available for the express purpose of being patched. It is called by SCIRxRingBuffer() once for each character coming into the UART. There are two flags relevant to this function that assist in filtering. They are RxD_TOSS_MASK and RxD_RPTF_MASK. These should be OR'ed with the MSB of the ushort that is to be returned to set them. RxD_TOSS_MASK should be set if you wish to throw away the character, in other words to replace one character with zero characters. In this case the LSB of the return value is ignored. If RxD_RPTF_MASK is set in the ushort that is returned, the filter will be called again with the same character until the flag is no longer set. This would allow you to replace one character with more than one character. This can be done by setting up a counter in global space that allows you to keep track of where you are in the sequence you wish to return.

Prototype:	ushort SCIRxFilter(ushort data:__d0):__d0;
Definition:	#include <cf1bios.h>
Inputs:	data is the character to be examined/filtered.
Returns:	By default returns the same character passed to it, however the character that is returned is the character that will be put into the ring buffer, so if any filtering is to occur, you would pass out the replacement character by returning it.
Notes:	A good rule of thumb is to keep any chores running at interrupt time under 100 µsecs. See example code coming soon.
Timing:	N/A

SCIRxGetByteBuffed -- return the next word in buffered mode

This function is not one that would be called from a user's application. It exists as a helper function to SCIRxGetByte, called by SCIRxGetByte, taking the same arguments and returning the same type, but is only called when the SCI is in interrupt driven buffering mode.

Prototype:	ushort SCIRxGetByteBuffed(bool block);
Definition:	#include <cf1bios.h>
Inputs:	block is a Boolean that determines whether the operation should return right away or wait for a byte to be received on the serial port to return.
Returns:	Returns a short, the LSB of which contains the byte gotten or -1 if block was false and there was not a byte available in the receive queue.
Notes:
Timing:	Depends on arguments, baud rate and buffer condition.

SCIRxGetBytePolled -- return the next word in polled mode

This function is not one that would be called from a user's application. It exists as a helper function to SCIRxGetByte, called by SCIRxGetByte, taking the same arguments and returning the same type, but is only called when the SCI is in polled mode.

Prototype:	ushort SCIRxGetBytePolled(bool block);
Definition:	#include <cf1bios.h>
Inputs:	block is a Boolean that determines whether the operation should return right away or wait for a byte to be received on the serial port to return.
Returns:	Returns a short, the LSB of which contains the byte gotten or -1 if block was false and there was not a byte available in the receive queue.
Notes:
Timing:	Depends on arguments, baud rate and buffer condition.

SCIRxRingBuffer -- Insert data in receive buffer

This function is not one that would be called from a user's application. It is made available for the express purpose of being patched. This function is a helper function for the default interrupt service routine for receiving characters from the main UART. The interrupt service routine calls this function when after it has gotten the data from the UART but before the data goes into the buffer. This function will never be called from an application but can be replaced or patched to allow for filtering. Because this function is called at interrupt time, it is advisable to keep any patches to a minimal length. For filtering received characters it is advisable to use the patchable function SCIRxFilter which is called on behalf of each incoming character by SCIRxRingBuffer.

Prototype:	void SCIRxRingBuffer(ushort data:__d0);
Definition:	#include <cf1bios.h>
Inputs:	data is the character to place into the receive buffer.
Notes:	A good rule of thumb is to keep any chores running at interrupt time under 100 µsecs.
Timing:	N/A

SCITxBlocked -- Called when transmit routine is waiting to send

This function is not one that would be called from a user's application. It exists as a helper function to SCITxPutByte, called by SCITxPutByte in a tight loop, to "kill time" during a blocking transmit operation. If you have code that you would like to have executed during a blocking transmit operation you could patch this function.

Prototype:	void SCITxBlocked(void);
Definition:	#include <cf1bios.h>
Notes:
Timing:	N/A

SCITxPutByteBuffed -- Transmit word in buffered mode

This function is not one that would be called from a user's application. It exists as a helper function to SCITxPutByte, taking the same arguments and returning the same type, but is only called when the SCI is in interrupt-driven buffering mode.

Prototype:	bool SCITxPutByteBuffed(ushort data, bool block);
Definition:	#include <cf1bios.h>
Inputs:	data is a ushort, the LSB of which contains the byte to be transmitted. block is a Boolean that determines whether the operation should return right away or wait for the byte to be put out the serial port to return.
Returns:	Returns true if byte was transmitted, or false if block was set to false and the byte could not be enqueued immediately (i.e. buffer is full).
Notes:
Timing:	Depends on arguments, baud rate and buffer condition.

SCITxPutBytePolled -- Transmit word in polled mode

This function is not one that would be called from a user's application. It exists as a helper function to SCITxPutByte, taking the same arguments and returning the same type, but is only called when the SCI is in polled mode.

Prototype:	bool SCITxPutBytePolled(ushort data, bool block);
Definition:	#include <cf1bios.h>
Inputs:	data is a ushort, the LSB of which contains the byte to be transmitted. block is a Boolean that determines whether the operation should return right away or wait for the byte to be put out the serial port to return.
Returns:	Returns true if byte was transmitted, or false if block was set to false and the byte could not be transmitted or enqueued (depending on buffering mode) immediately.
Notes:
Timing:	Depends on arguments, baud rate and buffer condition.

SCITxRingBuffer -- Fetch data from transmit buffer

This function is not one that would be called from a user's application. It is made available for the express purpose of being patched. It is called by the interrupt service routine for moving data from the transmit queue to the UART register. It also manages the head/tail adjustments on the transmit queue.

Prototype:	short SCITxRingBuffer(void):__d0;
Definition:	#include <cf1bios.h>
Returns:	Returns a short integer the LSB of which contains the character to be moved from the head of the transmit queue to the UART register.
Notes:
Timing:	N/A

 

Previous

Next

Top

Contents

Glossary

Index

Tel: 508-759-6434		Fax: 508-759-6436
Copyright (C) 1998 Persistor Instruments Inc. - All Rights Reserved