Serial driver details

To Contents

To previous page

To next page

 




Serial driver details

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

"simple serial" driver

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

The simple 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

 
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
	

NOTE

On most hardware, a selection of 1.5 stop bits is only valid if the word (character) length is 5.

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.

API details

 
 cyg_io_write
(handle, buf, len)
	

Send the data from 'buf' to the device. The driver maintains a buffer to hold the data and will return as soon as there is space in the buffer and the entire contents of 'buf' have been consumed. The data is not modified at all while it is being buffered. The size of the intermediate buffer is configurable within the interface module.

 
 cyg_io_read
(handle, buf, len)
	

Receive data into the specified buffer from the device. The total 'len' number of characters will be received before this call completes. No manipulation of the data is performed before being transferred. An interrupt driven interface module will support data arriving when no read is pending by buffering the data in the serial channel. Again, this buffering is completely configurable.

 
 cyg_io_get_config
(handle, key, buf, len)
	

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

Key:

CYG_IO_GET_CONFIG_SERIAL_INFO

Buf type:

cyg_serial_info_t

Function:

This function retrieves the current state of the driver and hardware. This information contains fields for hardware baud rate, number of stop bits, and parity mode. It also includes a set of flags that control the port, such as hardware flow control.

Key:

CYG_IO_GET_CONFIG_SERIAL_OUTPUT_DRAIN

Buf type:

void *

Function:

This function waits for any buffered output to complete. This function only completes when there is no more data remaining to be sent to the device.

Key:

CYG_IO_GET_CONFIG_SERIAL_OUTPUT_FLUSH

Buf type:

void *

Function:

This function discards any buffered output for the device.

Key:

CYG_IO_GET_CONFIG_SERIAL_INPUT_DRAIN

Buf type:

void *

Function:

This function discards any buffered input for the device.

 
 cyg_io_set_config
(handle, key, buf, len)
	

This function is used to update or change runtime configuration of a port.

The only key currently defined is CYG_IO_SET_CONFIG_SERIAL_INFO which is used to access the hardware configuration. The buffer must be of type cyg_serial_info_t and all fields must contain valid information.

"tty" driver

Use the include file cyg/io/ttyio.h for this driver.

This driver is built on top of the simple serial driver and is typically used for a device that interfaces with humans such as a terminal. It provides some minimal formatting of data on output and allows for line-oriented editing on input.

Runtime configuration

 
typedef struct {
 cyg_uint32 tty_out_flags;
 cyg_uint32 tty_in_flags;
} cyg_tty_info_t;
	

The field ' tty_out_flags' is used to control what happens to data as it is send to the serial port. It contains a bitmap comprised of the bits as defined by the CYG_TTY_OUT_FLAGS_xxx values below.

 
#define CYG_TTY_OUT_FLAGS_CRLF 0x0001 // Map '\n' => '\n\r' on output
 	

If this bit is set in 'tty_out_flags', any occurrence of the character '\n' will be replaced by the sequence '\n\r' before sending to the device.

The field ' tty_in_flags' is used to control how data is handles as it comes from the serial port. It contains a bitmap comprised of the bits as defined by the CYG_TTY_IN_FLAGS_xxx values below.

 
#define CYG_TTY_IN_FLAGS_CR 0x0001 // Map '\r' => '\n' on input
	

If this bit is set in 'tty_in_flags', the character '\r' ("return" or "enter" on most keyboards) will be mapped to '\n'.

 
#define CYG_TTY_IN_FLAGS_CRLF 0x0002 // Map '\n\r' => '\n' on input
	

If this bit is set in 'tty_in_flags', the character sequence '\n\r' (often sent by DOS/Windows based terminals) will be mapped to '\n'.

 
#define CYG_TTY_IN_FLAGS_BINARY 0x0004 // No input processing
	

If this bit is set in 'tty_in_flags', the input will not be manipulated in any way before being placed in the user's buffer.

 
#define CYG_TTY_IN_FLAGS_ECHO 0x0008 // Echo characters as processed
	

If this bit is set in 'tty_in_flags', characters will be echoed back to the serial port as they are processed.

API details

 
 cyg_io_read
(handle, buf, len)
	

This function is used to read data from the device. In the default case, data is read until an end-of-line character ('\n' or '\r') is read. Additionally, the characters are echoed back to the [terminal] device. Minimal editing of the input is also supported.

NOTE

When connecting to a remote target via GDB it is not possible to provide console input while GDB is connected. The GDB remote protocol does not support input. Users must disconnect from GDB if this functionality is required.

 
	
 cyg_io_write
(handle, buf, len)
	

This function is used to send data to the device. In the default case, the end-of-line character '\n' is replaced by the sequence '\n\r'.

 
 cyg_io_get_config
(handle, key, buf, len)
	

This function is used to get information about the channel's configuration at runtime.

Key:

CYG_IO_GET_CONFIG_TTY_INFO

Buf type:

cyg_tty_info_t

Function:

This function retrieves the current state of the driver.

The key must be "CYG_IO_GET_CONFIG_TTY_INFO" which returns the control flags for the channel. The buffer 'buf' must be of type 'cyg_tty_info_t' and the length should match.

Serial driver keys (see above) may also be specified in which case the call is passed directly to the serial driver.

 
 cyg_io_set_config
(handle, key, buf, len)
	

This function is used to modify the channel's configuration at runtime.

Key:

CYG_IO_SET_CONFIG_TTY_INFO

Buf type:

cyg_tty_info_t

Function:

This function changes the current state of the driver.

The key must be CYG_IO_SET_CONFIG_TTY_INFO which returns the control flags for the channel. The buffer 'buf' must be of type cyg_tty_info_t and the length should match.

Serial driver keys (see above) may also be specified in which case the call is passed directly to the serial driver.


Serial driver details

To Contents

To previous page

To next page