struct termiox

data structure containing hardware flow control information 

Data Structure


SYNOPSIS

#include <termiox.h>

struct termiox {
	unsigned short x_hflag;
	unsigned short x_cflag;
	unsigned short x_rflag[NFF];
	unsigned short x_sflag;
};


DESCRIPTION

The termiox extended general terminal interface supplements the termios general terminal interface by adding support for asynchronous hardware flow control, isochronous flow control and clock modes, and local implementations of additional asynchronous features. This interface is for use with serial communications ports only.

At this time, the NuTCRACKER Platform only implements support for setting hardware flow control modes through the termiox interface.

Hardware Flow Control Modes

Hardware flow control supplements the termios IXON and IXOFF character flow control. Character flow control occurs when one device controls the data transfer of another device by the insertion of control characters in the data stream between devices. Hardware flow control occurs when one device controls the data transfer of another device using electrical control signals on wires (circuits) of the asynchronous interface. Isochronous hardware flow control occurs when one device controls the data transfer of another device by asserting or removing the transmit clock signals of that device. Character flow control and hardware flow control may be simultaneously set. In asynchronous, full duplex applications, the use of the Electronic Industries Association's EIA-232-D Request-To-Send (RTS) and Clear-To-Send (CTS) circuit standards is the preferred method to control hardware flow. An interface to other hardware flow control methods is included to provide a standard interface to these existing methods.

The EIA-232-D standard specified only unidirectional hardware flow control - the Data Circuit-terminating Equipment or Data Communications Equipment (DCE) indicates to the Data Terminal Equipment (DTE) to stop transmitting data. The termiox interface allows both unidirectional and bi-directional hardware flow control; when bi-directional flow control is enabled, either the DCE or DTE can indicate to each other to stop transmitting data across the interface. Note: It is assumed that the asynchronous port is configured as a DTE. If the connected device is also a DTE and not a DCE, then DTE to DTE (for example, terminal or printer connected to computer) hardware flow control is possible by using a null modem to interconnect the appropriate data and control circuits.

Clock Modes

Isochronous communication is a variation of asynchronous communication whereby two communicating devices may provide transmit and/or receive clock to each other. Incoming clock signals can be taken from the baud rate generator on the local isochronous port controller, from CCITT V.24 circuit 114, Transmitter Signal Element Timing—DCE source (EIA-232-D pin 15), or from CCITT V.24 circuit 115, Receiver Signal Element Timing—DCE source (EIA-232-D pin 17). Outgoing clock signals can be sent on CCITT V.24 circuit 113, Transmitter Signal Element Timing—DTE source (EIA-232-D pin 24), on CCITT V.24 circuit 128, Receiver Signal Element Timing—DTE source (no EIA-232-D pin), or not sent at all.

In terms of clock modes, traditional asynchronous communication is implemented simply by using the local baud rate generator as the incoming transmit and receive clock source and not outputting any clock signals.

Terminal Parameters

When a com port is opened, the NuTCRACKER Platform initializes the x_hflag field from the underlying device settings. The rest of the fields are ignored and silently forced to zero.

The x_hflag field describes hardware flow control modes:

The NuTCRACKER Platform currently does not support CDXON or ISXOFF.

The EIA-232-D DTR and DSR circuits are used to establish a connection between two systems. The RTS circuit is also used to establish a connection with a modem. Thus, both DTR and RTS are activated when an asynchronous port is opened. If DTR is used for hardware flow control, then RTS must be used for connectivity. If DSR is used for hardware flow control, then CTS must be used for connectivity. Thus, RTS and DTR (or CTS and DSR) cannot both be used for hardware flow control at the same time. Other mutual exclusions may apply.

Variations of different hardware flow control methods may be selected by setting the appropriate bits. For example, bi-directional RTS/CTS flow control is selected by setting both the RTSXOFF and CTSXON bits and bi-directional DTR/CTS flow control is selected by setting both the DTRXOFF and CTSXON. Modem control or unidirectional CTS hardware flow control is selected by setting only the CTSXON bit. As previously mentioned, it is assumed that the local asynchronous port (for example, computer) is configured as a DTE. If the connected device (for example, printer) is also a DTE, it is assumed that the device is connected to the computer's asynchronous port via a null modem that swaps control circuits (typically RTS and CTS). The connected DTE drives RTS and the null modem swaps RTS and CTS so that the remote RTS is received as CTS by the local DTE. In the case that CTSXON is set for hardware flow control, printer's lowering of its RTS would cause CTS seen by the computer to be lowered. Output to the printer is suspended until the printer's raising of its RTS, which would cause CTS seen by the computer to be raised.

If RTSXOFF is set, the Request-To-Send (RTS) circuit (line) is raised, and if the asynchronous port needs to have its input stopped, it lowers the Request-To-Send (RTS) line. If the RTS line is lowered, it is assumed that the connected device stops its output until RTS is raised.

Note:

The Windows communications driver lowers RTS when the typeahead (input) buffer is more than three-quarters full and raises it again when it is less than half full.

If CTSXON is set, output occurs only if the Clear-To-Send (CTS) circuit (line) is raised by the connected device. If the CTS line is lowered by the connected device, output is suspended until CTS is raised.

If DTRXOFF is set, the DTE Ready (DTR) circuit (line) is raised, and if the asynchronous port needs to have its input stopped, it lowers the DTE Ready (DTR) line. If the DTR line is lowered, it is assumed that the connected device stops its output until DTR is raised.

If DSRXON is set, output occurs only if the Data Set Ready (DSR) circuit (line) is raised by the connected device. If the DSR line is lowered by the connected device, output is suspended until DSR is raised.

Supported ioctls

The following commands to the ioctl() function are used to manipulate the termiox structure:

TCGETX  

The argument is a pointer to a termiox structure. The current terminal parameters are fetched and stored into that structure.

TCSETX  

The argument is a pointer to a termiox structure. The current terminal parameters are set from the values stored in that structure. The change is immediate.

TCSETXW  

The argument is a pointer to a termiox structure. The current terminal parameters are set from the values stored in that structure. The change occurs after all characters queued for output have been transmitted. This form should be used when changing parameters that affect output.

TCSETXF  

The argument is a pointer to a termiox structure. The current terminal parameters are set from the values stored in that structure. The change occurs after all characters queued for output have been transmitted; all characters queued for input are discarded and then the change occurs.


CONFORMANCE

SVR4, with exceptions.


PORTING ISSUES

The NuTCRACKER Platform only implements a subset of the SVR4 termiox extensions, as listed in the DESCRIPTION section.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
ioctl()

Miscellaneous:
struct termios


PTC MKS Toolkit 10.4 Documentation Build 39.