eCos Reference Manual
Prev |  | Next

# Chapter 16. Serial driver details

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

> 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.

    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_write

    cyg_io_write(handle, buf, len)

Send the data from `buf` to the device. The driver maintains a buffer to hold the data. The size of the intermediate buffer is configurable within the interface module. The data is not modified at all while it is being buffered. On return, `*len` contains the amount of characters actually consumed .

It is possible to configure the write call to be blocking (default) or non-blocking. Non-blocking mode requires both the configuration option `CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING` to be enabled, and the specific device to be set to non-blocking mode for writes (see `cyg_io_set_config()`).

In blocking mode, the call will not return until there is space in the buffer and the entire contents of `buf` have been consumed.

In non-blocking mode, as much as possible gets consumed from `buf`. If everything was consumed, the call returns `ENOERR`. If only part of the `buf` contents was consumed, `-EAGAIN` is returned and the caller must try again. On return, `*len` contains the number of characters actually consumed .

The call can also return `-EINTR` if interrupted via the `cyg_io_get_config()`/`ABORT` key.

### cyg_io_read

    cyg_io_read(handle, buf, len)

Receive data into the buffer, `buf`, from the device. 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 driver. Again, this buffering is completely configurable. On return, `*len` contains the number of characters actually received.

It is possible to configure the read call to be blocking (default) or non-blocking. Non-blocking mode requires both the configuration option `CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING` to be enabled, and the specific device to be set to non-blocking mode for reads (see `cyg_io_set_config()`).

In blocking mode, the call will not return until the requested amount of data has been read.

In non-blocking mode, data waiting in the device buffer is copied to `buf`, and the call returns immediately. If there was enough data in the buffer to fulfill the request, `ENOERR` is returned. If only part of the request could be fulfilled, `-EAGAIN` is returned and the caller must try again. On return, `*len` contains the number of characters actually received.

The call can also return `-EINTR` if interrupted via the `cyg_io_get_config()`/`ABORT` key.

### 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`

  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.

`CYG_IO_GET_CONFIG_SERIAL_BUFFER_INFO`

  Buf type:

    cyg_serial_buf_info_t

  Function:

    This function retrieves the current state of the software buffers in the serial drivers. For both receive and transmit buffers it returns the total buffer size and the current number of bytes occupied in the buffer. It does not take into account any buffering such as FIFOs or holding registers that the serial device itself may have.

`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.

`CYG_IO_GET_CONFIG_SERIAL_OUTPUT_FLUSH`

  Buf type:

    void *

  Function:

    This function discards any buffered output for the device.

`CYG_IO_GET_CONFIG_SERIAL_INPUT_DRAIN`

  Buf type:

    void *

  Function:

    This function discards any buffered input for the device.

`CYG_IO_GET_CONFIG_SERIAL_ABORT`

  Buf type:

    void*

  Function:

    This function will cause any pending read or write calls on this device to return with `-EABORT`.

`CYG_IO_GET_CONFIG_SERIAL_READ_BLOCKING`

  Buf type:

    cyg_uint32 (values 0 or 1)

  Function:

    This function will read back the blocking-mode setting for read calls on this device. This call is only available if the configuration option `CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING` is enabled.

`CYG_IO_GET_CONFIG_SERIAL_WRITE_BLOCKING`

  Buf type:

    cyg_uint32 (values 0 or 1)

  Function:

    This function will read back the blocking-mode setting for write calls on this device. This call is only available if the configuration option `CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING` is enabled.

### cyg_io_set_config

    cyg_io_set_config(handle, key, buf,len)

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

`CYG_IO_SET_CONFIG_SERIAL_INFO`

  Buf type:

    cyg_serial_info_t

  Function:

    This function updates the information for the driver and hardware. The 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.

`CYG_IO_SET_CONFIG_SERIAL_READ_BLOCKING`

  Buf type:

    cyg_uint32 (values 0 or 1)

  Function:

    This function will set the blocking-mode for read calls on this device. This call is only available if the configuration option `CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING` is enabled.

`CYG_IO_SET_CONFIG_SERIAL_WRITE_BLOCKING`

  Buf type:

    cyg_uint32 (values 0 or 1)

  Function:

    This function will set the blocking-mode for write calls on this device. This call is only available if the configuration option `CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING` is enabled.

Prev | Home | Next
User API | Up | TTY driver