Xenomai API  2.6.5
Serial Devices

Files

file  rtserial.h
 Real-Time Driver Model for Xenomai, serial device profile header.
 

Data Structures

struct  rtser_config
 Serial device configuration. More...
 
struct  rtser_status
 Serial device status. More...
 
struct  rtser_event
 Additional information about serial device events. More...
 

Macros

#define RTSER_RTIOC_BREAK_CTL   _IOR(RTIOC_TYPE_SERIAL, 0x06, int)
 Set or clear break on UART output line. More...
 

RTSER_DEF_BAUD

Default baud rate

#define RTSER_DEF_BAUD   9600
 

RTSER_xxx_PARITY

Number of parity bits

#define RTSER_NO_PARITY   0x00
 
#define RTSER_ODD_PARITY   0x01
 
#define RTSER_EVEN_PARITY   0x03
 
#define RTSER_DEF_PARITY   RTSER_NO_PARITY
 

RTSER_xxx_BITS

Number of data bits

#define RTSER_5_BITS   0x00
 
#define RTSER_6_BITS   0x01
 
#define RTSER_7_BITS   0x02
 
#define RTSER_8_BITS   0x03
 
#define RTSER_DEF_BITS   RTSER_8_BITS
 

RTSER_xxx_STOPB

Number of stop bits

#define RTSER_1_STOPB   0x00
 valid only in combination with 5 data bits
 
#define RTSER_1_5_STOPB   0x01
 valid only in combination with 5 data bits
 
#define RTSER_2_STOPB   0x01
 valid only in combination with 5 data bits
 
#define RTSER_DEF_STOPB   RTSER_1_STOPB
 valid only in combination with 5 data bits
 

RTSER_xxx_HAND

Handshake mechanisms

#define RTSER_NO_HAND   0x00
 
#define RTSER_RTSCTS_HAND   0x01
 
#define RTSER_DEF_HAND   RTSER_NO_HAND
 

RTSER_RS485_xxx

RS485 mode with automatic RTS handling

#define RTSER_RS485_DISABLE   0x00
 
#define RTSER_RS485_ENABLE   0x01
 
#define RTSER_DEF_RS485   RTSER_RS485_DISABLE
 

RTSER_FIFO_xxx

Reception FIFO interrupt threshold

#define RTSER_FIFO_DEPTH_1   0x00
 
#define RTSER_FIFO_DEPTH_4   0x40
 
#define RTSER_FIFO_DEPTH_8   0x80
 
#define RTSER_FIFO_DEPTH_14   0xC0
 
#define RTSER_DEF_FIFO_DEPTH   RTSER_FIFO_DEPTH_1
 

RTSER_TIMEOUT_xxx

Special timeout values, see also RTDM_TIMEOUT_xxx

#define RTSER_TIMEOUT_INFINITE   RTDM_TIMEOUT_INFINITE
 
#define RTSER_TIMEOUT_NONE   RTDM_TIMEOUT_NONE
 
#define RTSER_DEF_TIMEOUT   RTDM_TIMEOUT_INFINITE
 

RTSER_xxx_TIMESTAMP_HISTORY

Timestamp history control

#define RTSER_RX_TIMESTAMP_HISTORY   0x01
 
#define RTSER_DEF_TIMESTAMP_HISTORY   0x00
 

RTSER_EVENT_xxx

Events bits

#define RTSER_EVENT_RXPEND   0x01
 
#define RTSER_EVENT_ERRPEND   0x02
 
#define RTSER_EVENT_MODEMHI   0x04
 
#define RTSER_EVENT_MODEMLO   0x08
 
#define RTSER_EVENT_TXEMPTY   0x10
 
#define RTSER_DEF_EVENT_MASK   0x00
 

RTSER_SET_xxx

Configuration mask bits

#define RTSER_SET_BAUD   0x0001
 
#define RTSER_SET_PARITY   0x0002
 
#define RTSER_SET_DATA_BITS   0x0004
 
#define RTSER_SET_STOP_BITS   0x0008
 
#define RTSER_SET_HANDSHAKE   0x0010
 
#define RTSER_SET_FIFO_DEPTH   0x0020
 
#define RTSER_SET_TIMEOUT_RX   0x0100
 
#define RTSER_SET_TIMEOUT_TX   0x0200
 
#define RTSER_SET_TIMEOUT_EVENT   0x0400
 
#define RTSER_SET_TIMESTAMP_HISTORY   0x0800
 
#define RTSER_SET_EVENT_MASK   0x1000
 
#define RTSER_SET_RS485   0x2000
 

RTSER_LSR_xxx

Line status bits

#define RTSER_LSR_DATA   0x01
 
#define RTSER_LSR_OVERRUN_ERR   0x02
 
#define RTSER_LSR_PARITY_ERR   0x04
 
#define RTSER_LSR_FRAMING_ERR   0x08
 
#define RTSER_LSR_BREAK_IND   0x10
 
#define RTSER_LSR_THR_EMTPY   0x20
 
#define RTSER_LSR_TRANSM_EMPTY   0x40
 
#define RTSER_LSR_FIFO_ERR   0x80
 
#define RTSER_SOFT_OVERRUN_ERR   0x0100
 

RTSER_MSR_xxx

Modem status bits

#define RTSER_MSR_DCTS   0x01
 
#define RTSER_MSR_DDSR   0x02
 
#define RTSER_MSR_TERI   0x04
 
#define RTSER_MSR_DDCD   0x08
 
#define RTSER_MSR_CTS   0x10
 
#define RTSER_MSR_DSR   0x20
 
#define RTSER_MSR_RI   0x40
 
#define RTSER_MSR_DCD   0x80
 

RTSER_MCR_xxx

Modem control bits

#define RTSER_MCR_DTR   0x01
 
#define RTSER_MCR_RTS   0x02
 
#define RTSER_MCR_OUT1   0x04
 
#define RTSER_MCR_OUT2   0x08
 
#define RTSER_MCR_LOOP   0x10
 

RTSER_BREAK_xxx

Break control

typedef struct rtser_config rtser_config_t
 Serial device configuration.
 
typedef struct rtser_status rtser_status_t
 Serial device status.
 
typedef struct rtser_event rtser_event_t
 Additional information about serial device events.
 
#define RTSER_BREAK_CLR   0x00
 Serial device configuration.
 
#define RTSER_BREAK_SET   0x01
 Serial device configuration.
 
#define RTIOC_TYPE_SERIAL   RTDM_CLASS_SERIAL
 Serial device configuration.
 

Sub-Classes of RTDM_CLASS_SERIAL

#define RTDM_SUBCLASS_16550A   0
 

IOCTLs

Serial device IOCTLs

#define RTSER_RTIOC_GET_CONFIG   _IOR(RTIOC_TYPE_SERIAL, 0x00, struct rtser_config)
 Get serial device configuration. More...
 
#define RTSER_RTIOC_SET_CONFIG   _IOW(RTIOC_TYPE_SERIAL, 0x01, struct rtser_config)
 Set serial device configuration. More...
 
#define RTSER_RTIOC_GET_STATUS   _IOR(RTIOC_TYPE_SERIAL, 0x02, struct rtser_status)
 Get serial device status. More...
 
#define RTSER_RTIOC_GET_CONTROL   _IOR(RTIOC_TYPE_SERIAL, 0x03, int)
 Get serial device's modem contol register. More...
 
#define RTSER_RTIOC_SET_CONTROL   _IOW(RTIOC_TYPE_SERIAL, 0x04, int)
 Set serial device's modem contol register. More...
 
#define RTSER_RTIOC_WAIT_EVENT   _IOR(RTIOC_TYPE_SERIAL, 0x05, struct rtser_event)
 Wait on serial device events according to previously set mask. More...
 

Detailed Description

This is the common interface a RTDM-compliant serial device has to provide. Feel free to comment on this profile via the Xenomai mailing list (Xenom.nosp@m.ai@x.nosp@m.enoma.nosp@m.i.or.nosp@m.g) or directly to the author (jan.k.nosp@m.iszk.nosp@m.a@web.nosp@m..de).

Profile Revision: 3

Device Characteristics
Device Flags: RTDM_NAMED_DEVICE, RTDM_EXCLUSIVE

Device Name: "rtser<N>", N >= 0

Device Class: RTDM_CLASS_SERIAL

Supported Operations
Open
Environments: non-RT (RT optional, deprecated)
Specific return values: none

Close
Environments: non-RT (RT optional, deprecated)
Specific return values: none

IOCTL
Mandatory Environments: see below
Specific return values: see below

Read
Environments: RT (non-RT optional)
Specific return values:
  • -ETIMEDOUT
  • -EINTR (interrupted explicitly or by signal)
  • -EAGAIN (no data available in non-blocking mode)
  • -EBADF (device has been closed while reading)
  • -EIO (hardware error or broken bit stream)

Write
Environments: RT (non-RT optional)
Specific return values:
  • -ETIMEDOUT
  • -EINTR (interrupted explicitly or by signal)
  • -EAGAIN (no data written in non-blocking mode)
  • -EBADF (device has been closed while writing)

Macro Definition Documentation

#define RTSER_RTIOC_BREAK_CTL   _IOR(RTIOC_TYPE_SERIAL, 0x06, int)

Set or clear break on UART output line.

Parameters
[in]argRTSER_BREAK_SET or RTSER_BREAK_CLR (int)
Returns
0 on success, otherwise negative error code

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
A set break condition may also be cleared on UART line reconfiguration.

Rescheduling: never.

#define RTSER_RTIOC_GET_CONFIG   _IOR(RTIOC_TYPE_SERIAL, 0x00, struct rtser_config)

Get serial device configuration.

Parameters
[out]argPointer to configuration buffer (struct rtser_config)
Returns
0 on success, otherwise negative error code

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

#define RTSER_RTIOC_GET_CONTROL   _IOR(RTIOC_TYPE_SERIAL, 0x03, int)

Get serial device's modem contol register.

Parameters
[out]argPointer to variable receiving the content (int, see RTSER_MCR_xxx)
Returns
0 on success, otherwise negative error code

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

#define RTSER_RTIOC_GET_STATUS   _IOR(RTIOC_TYPE_SERIAL, 0x02, struct rtser_status)

Get serial device status.

Parameters
[out]argPointer to status buffer (struct rtser_status)
Returns
0 on success, otherwise negative error code

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
The error states RTSER_LSR_OVERRUN_ERR, RTSER_LSR_PARITY_ERR, RTSER_LSR_FRAMING_ERR, and RTSER_SOFT_OVERRUN_ERR that may have occured during previous read accesses to the device will be saved for being reported via this IOCTL. Upon return from RTSER_RTIOC_GET_STATUS, the saved state will be cleared.

Rescheduling: never.

#define RTSER_RTIOC_SET_CONFIG   _IOW(RTIOC_TYPE_SERIAL, 0x01, struct rtser_config)

Set serial device configuration.

Parameters
[in]argPointer to configuration buffer (struct rtser_config)
Returns
0 on success, otherwise:
  • -EPERM is returned if the caller's context is invalid, see note below.
  • -ENOMEM is returned if a new history buffer for timestamps cannot be allocated.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
If rtser_config contains a valid timestamp_history and the addressed device has been opened in non-real-time context, this IOCTL must be issued in non-real-time context as well. Otherwise, this command will fail.

Rescheduling: never.

Examples:
cross-link.c.
#define RTSER_RTIOC_SET_CONTROL   _IOW(RTIOC_TYPE_SERIAL, 0x04, int)

Set serial device's modem contol register.

Parameters
[in]argNew control register content (int, see RTSER_MCR_xxx)
Returns
0 on success, otherwise negative error code

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

#define RTSER_RTIOC_WAIT_EVENT   _IOR(RTIOC_TYPE_SERIAL, 0x05, struct rtser_event)

Wait on serial device events according to previously set mask.

Parameters
[out]argPointer to event information buffer (struct rtser_event)
Returns
0 on success, otherwise:
  • -EBUSY is returned if another task is already waiting on events of this device.
  • -EBADF is returned if the file descriptor is invalid or the device has just been closed.

Environments:

This service can be called from:

  • Kernel-based task
  • User-space task (RT)

Rescheduling: possible.

Examples:
cross-link.c.