Using Streams: 2.1 Using the Serial Ports: Initializing a Serial Port

GEOS SDK TechDocs

2 Using the Serial Ports

2.2 Communicating

Like the stream driver, the serial driver is not accessed directly from Goc code. Instead, a Goc application makes calls to the Stream Library, which passes the requests through to the Serial Driver's strategy routine. Each serial-port command must be passed the GeodeHandle of the Serial Library; again, you can find this handle by calling GeodeGetInfo() .

The serial driver uses two streams, one for data going out to the serial port (outgoing) and one for data coming in from the serial port (incoming). Your program is the writer of the outgoing and the reader of the incoming. (In both cases, the port acts as the opposite user.)

Opening a Serial Port

SerialOpen()

To open a serial port, call the routine SerialOpen() . This routine is passed the following arguments:

• The GeodeHandle of the serial-port driver.
• A member of the SerialUnit enumerated type; this specifies which serial port is being opened. The type's members are SERIAL_COM1, SERIAL_COM2, and so on up to SERIAL_COM8.
• A member of the StreamOpenFlags enumerated type, indicating what to do if the requested serial port is busy (either STREAM_OPEN_NO_BLOCK, indicating that the routine should return an error immediately; or STREAM_OPEN_TIMEOUT, indicating that the routine should wait a specified number of clock ticks to see if the port will free up).
• The total size of the stream to be used as an input buffer, in bytes.
• The total size of the stream to be used as an output buffer, in bytes.
• The maximum number of ticks to wait for the serial port to become available (if STREAM_OPEN_TIMEOUT was passed).

A flag is returned to indicate whether the serial port could be opened; if not, a value of type StreamError will be returned to indicate the reason. Possible stream error values are STREAM_BUFFER_TOO_LARGE and STREAM_CANNOT_CREATE, and the additional values STREAM_NO_DEVICE (if the serial port does not exist) or STREAM_DEVICE_IN_USE (if the device is busy and the StreamOpenFlags passed indicate not to wait).

Note that when using the serial driver, you do not identify the stream by a stream token but rather by the serial port number, known as a unit number . When accessing a serial port, you simply pass the port's unit number along with either STREAM_READ (if reading from the stream) or STREAM_WRITE (if writing to the stream); because each port has two streams associated with it, you must specify both parameters. The serial driver will understand which stream you are accessing.

Configuring a Serial Port

SerialSetFormat(), SerialGetFormat(),SerialSetModem(), SerialGetModem(), SerialSetFlowControl()

Communication using a serial port requires that parity, speed, and flow control be properly set. To control these settings, call SerialSetFormat() , passing the following arguments:

• The GeodeHandle of the serial-port driver.
• The member of the SerialUnit enumerated type.
• A one-byte record of type SerialFormat , specifying the parity, word length, and number of stop bits to be used on the serial line; this record is described below.
• A member of the SerialMode enumerated type, set to indicate the level of flow control: SM_COOKED to indicate XON/XOFF flow control with characters stripped to seven bits, SM_RARE to indicate XON/XOFF flow control but incoming characters left alone, or SM_RAW to indicate no flow control.
• The baud rate to use, a member of the enumerated type SerialBauds , which has the following members:

typedef	enum
{
	SERIAL_BAUD_115200				= 1,
	SERIAL_BAUD_57600				= 2,
	SERIAL_BAUD_38400				= 3,
	SERIAL_BAUD_19200				= 6,
	SERIAL_BAUD_14400				= 8,
	SERIAL_BAUD_9600				= 12,
	SERIAL_BAUD_7200				= 16,
	SERIAL_BAUD_4800				= 24,
	SERIAL_BAUD_3600				= 32,
	SERIAL_BAUD_2400				= 48,
	SERIAL_BAUD_2000				= 58,
	SERIAL_BAUD_1800				= 64,
	SERIAL_BAUD_1200				= 96,
	SERIAL_BAUD_600				= 192,
	SERIAL_BAUD_300				= 384
} SerialBaud;

SerialFormat is a byte-sized record that specifies the parity, word-length, and number of stop bits for the serial line. The record has the following fields:

SERIAL_FORMAT_DLAB

This is for internal use only; it must be set to zero.

SERIAL_FORMAT_BREAK

If set, this causes a BREAK condition to be asserted on the line. You must explicitly clear this bit again to resume normal operation.

SERIAL_FORMAT_PARITY

This three-bit field holds the parity to expect on receive and use on transmit. It uses the SerialParity enumerated type, which has the following members:

typedef		enum {
	SERIAL_PARITY_NONE				= 0,
	SERIAL_PARITY_ODD				= 1,
	SERIAL_PARITY_EVEN				= 3,
	SERIAL_PARITY_ONE				= 5,
	SERIAL_PARITY_MARK				= 5,
	SERIAL_PARITY_ZERO				= 7,
	SERIAL_PARITY_SPACE				= 7
} SerialParity;

SERIAL_FORMAT_EXTRA_STOP

If this is set, extra stop-bits will be sent. One stop bit is always sent. However, if you set this flag, an extra 1/2 stop bit will be sent if the word-length is 5 bits long; an extra 1 stop bit will be sent if the frame is 6, 7, or 8 bits long.

SERIAL_FORMAT_LENGTH

This two-bit field holds the length of each data word, minus five (i.e. a five-bit word is represented with a zero, a six-bit word with a one).

To find out the current settings of a serial port, call SerialGetFormat() . This routine is passed five arguments:

• The GeodeHandle of the serial-port driver.
• The member of the SerialUnit enumerated type.
• A pointer to a SerialFormat variable. SerialGetFormat() will write the format data to this variable.
• A pointer to a SerialMode variable. SerialGetFormat() will write the appropriate mode constant (SM_COOKED, XON/XOFF, or SM_RARE) to this variable.
• A pointer to a SerialBaud variable. SerialFormat() will write the appropriate constant to this variable.

As with other serial port routines, if the routine is successful, it will return zero; if it is unsuccessful, it will return an error code.

If you are using a modem's hardware flow control, you will have to configure the modem appropriately. You can do this by calling SerialSetModem() . This routine is passed three arguments:

• The GeodeHandle of the serial-port driver.
• The member of the SerialUnit enumerated type.
• A record of type SerialModem . This record has four fields: SERIAL_MODEM_OUT2, SERIAL_MODEM_OUT1, SERIAL_MODEM_RTS, and SERIAL_MODEM_DTR. Set these fields to indicate how the control-bits should be set.

To find out what flow control is being used, call SerialGetModem() . This routine is passed three arguments:

• The GeodeHandle of the serial-port driver.
• The member of the SerialUnit enumerated type.
• A pointer to a record of type SerialModem . SerialGetModem() will set this record's SERIAL_MODEM_OUT2, SERIAL_MODEM_OUT1, SERIAL_MODEM_RTS, and SERIAL_MODEM_DTR bits appropriately.

You can also set the flow control without setting the other format options. Do this by calling SerialSetFlowControl() . This routine is passed the following arguments:

• The GeodeHandle of the serial-port driver.
• The member of the SerialUnit enumerated type.
• A record of type SerialModem . This record has four fields: SERIAL_MODEM_OUT2, SERIAL_MODEM_OUT1, SERIAL_MODEM_RTS, and SERIAL_MODEM_DTR. Set these fields to indicate how the control-bits should be set.
• A member of the SerialMode enumerated type, set to indicate the level of flow control: SM_COOKED to indicate XON/XOFF flow control with characters stripped to seven bits, SM_RARE to indicate XON/XOFF flow control but incoming characters left alone, or SM_RAW to indicate no flow control.
• A record of type SerialModemStatus to indicate which lines (chosen from DCD, DSR, and CTS) should be used to control outgoing data (if hardware flow control is selected). When one of the selected lines is de-asserted by the remote system, the serial driver will not transmit any more data until the state changes.

GEOS SDK TechDocs

2 Using the Serial Ports

2.2 Communicating