The SPC/S SBus communications board consists of eight asynchronous serial ports and one IBM PS/2-compatible parallel port. The stc driver supports up to eight SPC/S boards in an SBus system. Each serial port has full modem control: the CD, DTR, DSR, RTS, and CTS modem control lines are provided, and flow control is supported in hardware for either RTS/CTS hardware flow control or DC1/DC3 software flow control.

The parallel port is unidirectional, with support for the ACK, STROBE, BUSY, PAPER OUT, SELECT, and ERROR interface signals. Both the serial and parallel ports support those termio(7I) device control functions specified by flags in the c_cflag word of the termios(3C) structure. In addition, the serial ports support the IGNPAR, PARMRK, INPCK, IXON, IXANY, and IXOFF flags in the c_iflag word of the termios(3C) structure. The latter c_iflag functions are performed by the stc driver for the serial ports.

Since the parallel port is a unidirectional, output-only port, no input termios(3C) (c_iflag) parameters apply to it. Trying to execute a nonsensical ioctl() on the parallel port is not recommended.

All other termios(3C) functions are performed by STREAMS modules pushed on top of the driver. When an stc device is opened, the ldterm(7M) and ttcompat(7M) STREAMS modules are automatically pushed on top of the stream if they are specified in the /etc/iu.ap file (the default condition), providing the standard termio(7I) interface.

Device names of the form /dev/term/n or /dev/ttyyn specify the serial I/O ports provided on the SPC/S board, conventionally as incoming lines. Device names of the form /dev/cua/n or /dev/ttyn specify the serial I/O ports provided on the SPC/S board, conventionally as outgoing lines. Device names of the form /dev/printers/n specify the parallel port, while a device name of the form /dev/sad/stcn specifies a special control port per board.

To allow a single tty line to be connected to a modem and used for both incoming and outgoing calls, a special feature, controlled by the minor device number, has been added. Minor device numbers in the range 128-191 correspond to the same physical lines as those in the range 0-63 (that is, the same line as the minor device number minus 128).

A dial-in line has a minor device in the range 0-63 and is conventionally named /dev/term/n where n is a number that indicates which dial-in line it is (so that /dev/term/0 is the first dial-in line). The dial-out line corresponding to that dial-in line has a minor device number 128 greater than the minor device number of the dial-in line and is conventionally named /dev/cua/n wheren is the number of the dial-in line. These devices also have the compatibility names /dev/ttyn.

The /dev/cua/n lines are special in that they can be opened even when there is no carrier on the line. Once a /dev/cua/n line is opened, the corresponding /dev/term/n line cannot be opened until the /dev/cua/n line is closed; a blocking open will wait until the /dev/cua/n line is closed (which drops DTR, after which DCD will usually drop as well) and carrier is detected again, and a non-blocking open will return an error. If the /dev/term/n line is opened successfully (usually only when carrier is recognized on the modem) the corresponding /dev/cua/n line cannot be opened. This allows a modem to be attached to /dev/term/0, for example, and used for dial-in, by enabling the line for login (using pmadm(1M)) and also used for dial-out (by tip(1) or uucp(1C)) as /dev/cua/0 when nobody is logged in on the line.

The control port, named /dev/sad/stcn where n is the SPC/S, is available. An ioctl() is provided for this special file which allow the collection of statistics maintained on serial port performance.

Minor Numbers

The standard set of termio ioctl() calls is supported by the stc driver on both the serial and parallel ports.

If the CRTSCTS flag in the c_cflag is set and if CTS is high, output will be transmitted; if CTS is low, output will be frozen. If the CRTSCTS flag is clear, the state of CTS has no effect. Breaks can be generated by the TCSBRK, TIOCSBRK and TIOCCBRK ioctl() calls. The modem control lines TIOCM_CAR, TIOCM_CTS, TIOCM_RTS, TIOCM_DSR and TIOCM_DTR are provided for the serial ports, although the TIOCMGET ioctl() call will not return the state of the TIOCM_RTS or TIOCM_DSR lines, which are output-only signals.

The serial port input and output line speeds may be set to any of the speeds supported by termio(7I).

The stc driver supports two additional ioctl()s. STC_SPPC(struct ppc_params_t *) sets parallel port parameters, and STC_GPPC(struct ppc_params_t *) gets parallel port parameters. Both are valid until changed or until a close().

struct ppc_params_t { uint_t flags; /* driver status flag */ uint_t state; /* status of the printer interface */ uint_t strobe_w; /* strobe width, in microseconds */ uint_t data_setup; /* data setup time, in microseconds */ uint_t ack_timeout; /* ACK timeout in secs */ uint_t error_timeout; /* PAPER OUT, etc... timeout in secs */ uint_t busy_timeout; /* BUSY timeout in seconds */ };

The possible values for flags defined in /usr/include/sys/stcio.h are:

PP_PAPER_OUT

honor PAPER OUT from port; returned HIGH means PAPER OUT.

PP_ERROR

honor ERROR from port; returned HIGH means ERROR.

PP_BUSY

honor BUSY from port; returned HIGH means BUSY.

PP_SELECT

honor SELECT from port; returned HIGH means OFFLINE.

PP_MSG

print console message on every error scan.

PP_SIGNAL

send a PP_SIGTYPE (SIGURG) to the process if printer error.

The state field contains the current status of the printer interface. It is analogous to the bit order of flags, but contains the status the driver maintains, masked by the flags that are set. The result of shifting state PP_SHIFT bits to the left is the actual state of the hardware.

The STC_SPPC and STC_GPPC ioctl() calls are understood only by the parallel port. STC_GSTATS(struct stc_stats_t *) gets or resets driver performance statistics on serial ports.

struct stc_stats_t { uint_t cmd; /* command */ uint_t qpunt; /* punting in stc_drainsilo() */ uint_t drain_timer; /* posted a timer in stc_drainsilo() */ uint_t no_canput; /* canput() failed in stc_drainsilo() */ uint_t no_rcv_drain; /* can't call stc_drainsilo() in stc_rcv() */ uint_t stc_drain; /* STC_DRAIN flag set on this line */ uint_t stc_break; /* BREAK requested on XMIT via stc_ioctl() */ uint_t stc_sbreak; /* start BREAK requested via stc_ioctl() */ uint_t stc_ebreak; /* end BREAK requested via stc_ioctl() */ uint_t set_modem; /* set modem control lines in stc_ioctl() */ uint_t get_modem; /* get modem control lines in stc_ioctl() */ uint_t ioc_error; /* bad ioctl() */ uint_t set_params; /* call to stc_param() */ uint_t no_start; /* can't run in stc_start(); already there */ uint_t xmit_int; /* transmit interrupts */ uint_t rcv_int; /* receive interrupts */ uint_t rcvex_int; /* receive exception interrupts */ uint_t modem_int; /* modem change interrupts */ uint_t xmit_cc; /* characters transmitted */ uint_t rcv_cc; /* characters received */ uint_t break_cnt; /* BREAKs received */ uint_t bufcall; /* times we couldn't get STREAMS buffer */ uint_t canwait; /* stc_drainsilo() called w/pending timer */ uint_t reserved; /* this field is meaningless */ };

The STC_GSTATS ioctl() works only on the SPC/S control port. The possible cmd values, defined in /usr/include/sys/stcio.h, are STAT_CLEAR, which clears the line statistics, and STAT_GET, which gets the line statistics.

Several methods may be used to enable or disable soft carrier on a particular serial line. The non-programmatic method is to edit the /platform/platform/kernel/drv/stc.conf file. For this change to take effect, the machine must be rebooted. See the next section, SETTING DEFAULT LINE PARAMETERS, for more information on this method. From within an application program, you can enable or disable the recognition of carrier on a particular line by issuing the TIOCGSOFTCAR ioctl() to the driver.

The default mode of operation for the DTR signal is to assert it on the first open() of a serial line and, if HUPCL is set, to de-assert it on the last close(). To change the operation of this feature, issue the set on the /platform/platform/kernel/drv/stc.conf parameter flags field bit DTR_ASSERT.

Many default parameters of the serial and parallel ports can be changed using the /platform/platform/kernel/drv/stc.conf file. The format of a line in the stc.conf file is:

device_tag=token[=value][:token[=value]]

For serial ports, the device_tag is stc_n, where n is between 0 and the maximum number of serial ports used by the driver. The token and parameters that follow it apply to both the /dev/term/n entries and /dev/cua/n entries.

For parallel ports, the device_tag is stc_pn, where n is between 0 and the number of parallel ports driven by stc.

The token[=value] specifies a token, and if the token takes a value, the value to assigned. Tokens that don't take a value are considered boolean. If boolean tokens don't appear in the stc.conf file, they will be cleared by the driver. If these tokens appear in the stc.conf file, they are set by the driver.

Tokens that take parameters must have a parameter specified in the token=value couplet in the stc.conf file. If no parameter or an invalid parameter is specified, the driver ignores the token and uses the driver's default value.

Tokens for Serial Ports

Tokens for Parallel Ports

The default values of certain parallel port parameters that govern data transfer between the SPC/S board and the device attached to the parallel port will usually work well with most devices; however, some devices don't strictly adhere to the IBM PS/2-compatible (Centronics-compatible) data transfer and device control/status protocol, and may require modification of one or more of the default parallel port parameters. Some printers, for example, have non-standard timing on their SELECT line, which manifests itself if you start sending data to the printer and then take it off line; when you put it back on line, the printer will not assert it's SELECT line until after the next character is sent to the printer. Since the stc driver will not send data to the device if it's SELECT line is de-asserted, a deadlock condition occurs. To remedy this situation, you can change the default signal list that the stc driver monitors on the parallel port by removing the SELECT signal from the list. This can be done through the /platform/platform/kernel/drv/stc.conf configuration file or programmatically through the STC_SPPC ioctl() call.

If you try to unload the driver, and one or more of the ports on one or more of the SPC/S boards is in use (for example, open()) by a process, the driver is not unloaded, and all lines on all SPC/S boards, with the exception of the control ports, will be marked with an open inhibit flag to prevent further opens until the driver is successfully unloaded.

An open() will fail with errno set to:

ENXIO

The unit being opened does not exist.

EBUSY

The dial-out device is being opened and the dial-in device is already open, the dial-in device is being opened with a no-delay open and the dial-out device is already open or the unit has been marked as exclusive-use by another process with a TIOCEXCL ioctl() call.

EINTR

The open was interrupted by the delivery of a signal.

EPERM

The control port for the board was opened by a process whose uid was not root.

An ioctl() will fail with errno set to:

ENOSR

A STREAMS data block could not be allocated to return data to the caller.

EINVAL

An invalid value was passed as the data argument to the ioctl() call or an invalid argument or op-field was passed in one of the driver-specific ioctl()'s.

EPERM

An STC_GSTATS ioctl() was requested by a process whose uid was not root.

ENOTTY

An unrecognized ioctl() command was received.

The stc driver uses the following files:

/dev/term/[00-3f]

/dev/ttyy[00-3f]

Hardwired and dial-in tty lines

/dev/cua/[00-3f]

/dev/ttyz[00-3f]

Dial-out tty lines

/dev/printers/[0-7]

/dev/stclp[0-7]

Parallel port lines

/dev/stc[0-7]

Control port

/platform/platform/kernel/drv/stc.conf

Driver configuration file

/usr/include/sys/stcio.h

Header file with ioctl()s supported by this driver

tip(1), uucp(1C), pmadm(1M), termios(3C), ldterm(7M), termio(7I), termiox(7I), ttcompat(7M), allocb(9F), bufcall(9F), kmem_zalloc (9F)

All diagnostic messages from the driver appear on the system console. There are three severity levels of messages displayed:

FATAL

The device driver does not load and any SPC/S boards installed in the system are inaccessible. Fatal errors usually occur during the modload process.

ERROR

Some condition has disrupted the normal operation of the board and/or device driver. There may be data loss. This class of message mayindicate an impending hardware failure.

ADVISORY

The device driver has detected a condition that may be of interest, usually a transient condition that clears itself.

Messages During Initialization Of Driver/Board

Messages Related To The Serial Port

Messages Related To The Parallel Port

Messages Related To STREAMS Processing

Messages Related To Serial Port Control