Serial Devices
[Device Profiles]
Collaboration diagram for Serial Devices:
|
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 (Xenomai-core@gna.org) or directly to the author (jan.kiszka@web.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)
Specific return values: none
Close
Environments: non-RT (RT optional)
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)
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... | |
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. | |
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_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_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 |
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 |
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. | |
| #define | RTSER_RTIOC_SET_CONFIG _IOW(RTIOC_TYPE_SERIAL, 0x01, struct rtser_config) |
| Set serial device configuration. | |
| #define | RTSER_RTIOC_GET_STATUS _IOR(RTIOC_TYPE_SERIAL, 0x02, struct rtser_status) |
| Get serial device status. | |
| #define | RTSER_RTIOC_GET_CONTROL _IOR(RTIOC_TYPE_SERIAL, 0x03, int) |
| Get serial device's modem contol register. | |
| #define | RTSER_RTIOC_SET_CONTROL _IOW(RTIOC_TYPE_SERIAL, 0x04, int) |
| Set serial device's modem contol register. | |
| #define | RTSER_RTIOC_WAIT_EVENT _IOR(RTIOC_TYPE_SERIAL, 0x05, struct rtser_event) |
| Wait on serial device events according to previously set mask. | |
Defines | |
| #define | RTSER_RTIOC_BREAK_CTL _IOR(RTIOC_TYPE_SERIAL, 0x06, int) |
| Set or clear break on UART output line. | |
Define Documentation
| #define RTSER_RTIOC_BREAK_CTL _IOR(RTIOC_TYPE_SERIAL, 0x06, int) |
Set or clear break on UART output line.
- Parameters:
-
[in] arg RTSER_BREAK_SETorRTSER_BREAK_CLR(int)
- Returns:
- 0 on success, otherwise negative error code
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.
| #define RTSER_RTIOC_GET_CONFIG _IOR(RTIOC_TYPE_SERIAL, 0x00, struct rtser_config) |
Get serial device configuration.
- Parameters:
-
[out] arg Pointer to configuration buffer (struct rtser_config)
- Returns:
- 0 on success, otherwise negative error code
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] arg Pointer to variable receiving the content (int, see RTSER_MCR_xxx)
- Returns:
- 0 on success, otherwise negative error code
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] arg Pointer to status buffer (struct rtser_status)
- Returns:
- 0 on success, otherwise negative error code
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, andRTSER_SOFT_OVERRUN_ERRthat may have occured during previous read accesses to the device will be saved for being reported via this IOCTL. Upon return fromRTSER_RTIOC_GET_STATUS, the saved state will be cleared.
| #define RTSER_RTIOC_SET_CONFIG _IOW(RTIOC_TYPE_SERIAL, 0x01, struct rtser_config) |
Set serial device configuration.
- Parameters:
-
[in] arg Pointer 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.
- Examples:
- cross-link.c.
| #define RTSER_RTIOC_SET_CONTROL _IOW(RTIOC_TYPE_SERIAL, 0x04, int) |
Set serial device's modem contol register.
- Parameters:
-
[in] arg New control register content (int, see RTSER_MCR_xxx)
- Returns:
- 0 on success, otherwise negative error code
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] arg Pointer 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.
