Chapter 16. Serial driver details

Table of Contents
Raw Serial Driver
TTY driver

Two different classes of serial drivers are provided as a standard part of the eCos system. These are described as “raw serial” (serial) and “tty-like” (tty).

Raw Serial Driver

Use the include file <cyg/io/serialio.h> for this driver.

The raw serial driver is capable of sending and receiving blocks of raw data to a serial device. Controls are provided to configure the actual hardware, but there is no manipulation of the data by this driver.

There may be many instances of this driver in a given system, one for each serial channel. Each channel corresponds to a physical device and there will typically be a device module created for this purpose. The device modules themselves are configurable, allowing specification of the actual hardware details, as well as such details as whether the channel should be buffered by the serial driver, etc.

Runtime Configuration

Runtime configuration is achieved by exchanging data structures with the driver via the cyg_io_set_config() and cyg_io_get_config() functions.

typedef struct {
 cyg_serial_baud_rate_t baud;
 cyg_serial_stop_bits_t stop;
 cyg_serial_parity_t parity;
 cyg_serial_word_length_t word_length;
 cyg_uint32 flags;
} cyg_serial_info_t;

The field word_length contains the number of data bits per word (character). This must be one of the values:

 CYGNUM_SERIAL_WORD_LENGTH_5
 CYGNUM_SERIAL_WORD_LENGTH_6
 CYGNUM_SERIAL_WORD_LENGTH_7
 CYGNUM_SERIAL_WORD_LENGTH_8

The field baud contains a baud rate selection. This must be one of the values:

 CYGNUM_SERIAL_BAUD_50
 CYGNUM_SERIAL_BAUD_75
 CYGNUM_SERIAL_BAUD_110
 CYGNUM_SERIAL_BAUD_134_5
 CYGNUM_SERIAL_BAUD_150
 CYGNUM_SERIAL_BAUD_200
 CYGNUM_SERIAL_BAUD_300
 CYGNUM_SERIAL_BAUD_600
 CYGNUM_SERIAL_BAUD_1200
 CYGNUM_SERIAL_BAUD_1800
 CYGNUM_SERIAL_BAUD_2400
 CYGNUM_SERIAL_BAUD_3600
 CYGNUM_SERIAL_BAUD_4800
 CYGNUM_SERIAL_BAUD_7200
 CYGNUM_SERIAL_BAUD_9600
 CYGNUM_SERIAL_BAUD_14400
 CYGNUM_SERIAL_BAUD_19200
 CYGNUM_SERIAL_BAUD_38400
 CYGNUM_SERIAL_BAUD_57600
 CYGNUM_SERIAL_BAUD_115200
 CYGNUM_SERIAL_BAUD_234000

The field stop contains the number of stop bits. This must be one of the values:

 CYGNUM_SERIAL_STOP_1
 CYGNUM_SERIAL_STOP_1_5
 CYGNUM_SERIAL_STOP_2

The field parity contains the parity mode. This must be one of the values:

 CYGNUM_SERIAL_PARITY_NONE
 CYGNUM_SERIAL_PARITY_EVEN
 CYGNUM_SERIAL_PARITY_ODD
 CYGNUM_SERIAL_PARITY_MARK
 CYGNUM_SERIAL_PARITY_SPACE

The field flags is a bitmask which controls the behavior of the serial device driver. It should be built from the values CYG_SERIAL_FLAGS_xxx defined below:

#define CYG_SERIAL_FLAGS_RTSCTS 0x0001

If this bit is set then the port is placed in “hardware handshake” mode. In this mode, the CTS and RTS pins control when data is allowed to be sent/received at the port. This bit is ignored if the hardware does not support this level of handshake.

typedef struct {
  cyg_int32 rx_bufsize;
  cyg_int32 rx_count;
  cyg_int32 tx_bufsize;
  cyg_int32 tx_count;
} cyg_serial_buf_info_t;     

The field rx_bufsize contains the total size of the incoming data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).

The field rx_count contains the number of bytes currently occupied in the incoming data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).

The field tx_bufsize contains the total size of the transmit data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).

The field tx_count contains the number of bytes currently occupied in the transmit data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices).

API Details

cyg_io_get_config

cyg_io_get_config(handle, key, buf, len)

This function returns current [runtime] information about the device and/or driver.

CYG_IO_GET_CONFIG_SERIAL_INFO

CYG_IO_GET_CONFIG_SERIAL_BUFFER_INFO

CYG_IO_GET_CONFIG_SERIAL_OUTPUT_DRAIN

CYG_IO_GET_CONFIG_SERIAL_OUTPUT_FLUSH

CYG_IO_GET_CONFIG_SERIAL_INPUT_DRAIN

CYG_IO_GET_CONFIG_SERIAL_ABORT

CYG_IO_GET_CONFIG_SERIAL_READ_BLOCKING

CYG_IO_GET_CONFIG_SERIAL_WRITE_BLOCKING