stc(7D) (man pages section 7: Device and Network Interfaces)

man pages section 7: Device and Network Interfaces

stc(7D)

NAME

stc– Serial Parallel Communications driver for SBus

DESCRIPTION

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 characters o p u u | u l l l correspond to the bits in the minor number. They are mnemonic indicators of the function of the corresponding bit.

o: set if this device is an outgoing serial line
p: set if this is a parallel port device
u: device unit number
l: device line number if this is the parallel port line, 'p' should be 1 and 'lll' should be all 0's if this is the control line, both 'p' and 'lll' should be set to all 1's

IOCTLS

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

DEVICE-SPECIFIC IOCTLS

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.

SOFTCAR, DTR and CTS/RTS FLOW CONTROL

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.

SETTING DEFAULT LINE PARAMETERS

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

Valid boolean tokens for serial ports are:

soft_carrier-: Defaullt value, enables the soft carrier on the specified line. When the soft carrier is set, transitions on the carrier detect line will be ignored. Use drt_assert to clear this value.
dtr_assert-: Causes the DTR to be asserted on the next open of the port.
dtr_force-: Causes DTR to be continuously asserted. It overrides any other DTR operations and ioctl() calls.
dtr_close-: Use alternate semantics when dealing with DTR in close. If this is clear, DTR will drop on the close of the port. If this is set, DTR will not drop on close() if TS_SOFTCAR (see termiox(7I)) is set in the t_flags.
cflow_flush-: Flush any data being held off by remote flow control on close().
cflow_msg-: Display a message on the console if data transmission is stalled due to remote flow control blocking the transfer in close().
instantflow-: If transmission is stopped by software flow control and the flow control is disabled via an ioctl() call, the transmitter will be enabled immediately.

Note –

The display- token is not supported.

Valid tokens requiring values are:

drain_size-: The size of STREAMS buffers allocated when passing data from the receive interrupt handler upstream.
hiwater, lowwater-: The high water and low water thresholds in the receive interrupt handler 1024 byte buffer.
rtpr-: The inter-character receive timer.
rxfifo-: The UART receive fifo threshold.

For serial ports, the value-carrying tokens have the following defaults and ranges:

token	default value	min value	max value
hiwater	1010 bytes	2 bytes	1022 bytes
lowwater	512 bytes	2 bytes	hiwater minus 2 bytes
drain_size	64 bytes	4 bytes	1024 bytes
rtpr	18 millisecs	1 millisecs	255 millisecs
rxfifo	4 bytes	1 bytes	8 bytes

Tokens for Parallel Ports

Valid boolean tokens for parallel ports are

paper_out-: If set, the PAPER OUT signal from the port is monitored. If clear, the signal is ignored.
error-: Monitor the ERROR signal from the port. Ignore the signal if clear.
busy-: Monitor the BUSY signal from the port. Ignore the signal if clear.
select-: Monitor the SELECT, or ON LINE, signal from the port. Ignore the signal if clear.
pp_message-: If this token is clear, a console message will be printed when any of the above four enabled conditions are detected, and another when the condition is cleared. If set, a console message will be printed every 60 seconds until the condition is cleared.
pp_signal-: If this token is set, the parallel port's controlling process will get a PP_SIGTYPE signal whenever one of the above four conditions is detected. PP_SIGTYPE is defined in stcio.h, which is available to the user.

Valid tokens requiring parameters for the parallel ports are

ack_timeout-: The amount of time in seconds to wait for an ACK from the port after asserting STROBE and transferring a byte of data.
error_timeout-: Amount of time in seconds to wait for an error to go away.
busy_timeout-: The amount of time in seconds to wait for a BUSY signal to clear, or zero for an infinite BUSY timeout.
data_setup-: The amount of time in microseconds between placing data ont the parallel lines and asserting the STROBE.
strobe_width-: width of the STROBE pulse, in microseconds.

For value-carrying tokens for parallel ports:

token	default value	min value	max value
strobe_width	2 microsecs	1 microsecs	30 microsecs
data_setup	2 microsecs	0 microsecs	30 microsecs
ack_timeout	60 seconds	5 seconds	7200 seconds
errror_timeout	5 seconds	1 seconds	480 seconds
busy_timeout	10 seconds	0 seconds	7200 seconds

PARALLEL PORT PARAMETERS

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.

LOADABLE ISSUES

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.

ERRORS

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.

FILES

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

DIAGNOSTICS

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

The following messages can be generated during initialization of the driver or board.

stc_attach: can't allocate memory for unit structs: FATAL. kmem_zalloc() failed to allocate memory for the driver's internal data structures.
stc_attach: board revision undeterminable: FATAL. The driver did not get a hardware revision level from the board's onboard FCode PROM.
stc_attach: board revision 0x%x not supported by driver.: FATAL. This revision of the board is not supported by the driver.
stc_attach: oscillator revision undeterminable: FATAL. The driver did not get an oscillator revision level from the board's onboard FCode PROM.
stc_attach: weird oscillator revision (0x%x), assuming 10Mhz: ADVISORY. The board's onboard FCode PROM returned an unanticipated baud-rate oscillator value, so the driver assumes that a 10Mhz oscillator is installed.
stc_attach: error initializing stc%d: FATAL. An error occured while trying to initialize the board; perhaps a memory access failed.
stc_attach: bad number of interrupts: %d: FATAL. An incorrect number of interrupts was read from the board's onboard FCode PROM.
stc_attach: bad number of register sets: %d: FATAL. An incorrect number of register sets was read from the board's onboard FCode PROM.
stc_init: stc%d GIVR was not 0x0ff, was: 0x%x: FATAL. Either the cd-180 8-channel UART failed to initialize properly or a memory fault occured while trying to access the chip.
cd180_init: stc%d GIVR was not 0x0ff, was: 0x%x: FATAL. Either the cd-180 8-channel UART failed to initialize properly or a memory fault occured while trying to access the chip.
stc%d: board revision: 0x%x should be updated: ADVISORY. Two versions of the FCode PROM on the SPC/S card, V1.0 (0x4) and V1.1 (0x5), have been released. The V1.1 PROM fixes some incompatabilities between the V1.0 FCode PROM on the SPC/S and the V2.0 OpenBOOT PROM on your system. An SPC/S card in a system running Solaris 2.X. requires a V1.1 PROM.
stc%d: system boot PROM revision V%d.%d should be updated: ADVISORY. Your system's BOOT PROM should be updated to at least V1.3 because prior versions of the BOOT PROM did not correctly map the SBus interrupt levels that the SPC/S uses.

Messages Related To The Serial Port

SET_CCR: CCR timeout: ERROR. The cd-180's CCR register did not return to zero within the specified timeout period after it was issued a command
PUTSILO: unit %d line %d soft silo overflow: ERROR. The driver's internal receive data silo for the enunciated line has overflowed because the system has not gotten around to pulling data out of the silo. Make sure you are using the correct flow control and that all data in the silo is flushed. This message frequently appears becasue of a hardware crosstalk problem that was fixed in later releases of the board.
stc_rcvex: unit %d line %d receiver overrun, char: 0x%x: ERROR. The driver could not get around to service the cd-180 receive data interrupt before the cd-180's receive data FIFO filled up. This message frequently appears becasue of a hardware crosstalk problem that was fixed in later releases of the board.
stc_drainsilo: unit %d line %d can't allocate streams buffer: ERROR. The driver could not get a STREAMS message buffer from bufcall(9F). All data in the driver's receive data silo is flushed.
stc_drainsilo: unit %d line %d punting put retries: ERROR. After trying several times to send data down the stream from the driver to the application and finding the path blocked, the driver gives up. All data in the driver's receive data silo is flushed.
stc_modem: unit %d line %d interesting modem control: ADVISORY. The cd-180 posted a modem control line change interrupt, but upon examination by the driver, no modem control lines had changed state since the last time a scan was conducted. If you see this problem frequently, it is likely that your data cables are either too long or picking up induced noise.

Messages Related To The Parallel Port

ppc_stat: unit %d PAPER OUT: ADVISORY. The device connected to the parallel port on the enumerated BOARD has signalled that it is out of paper (PAPER OUT line asserted).
ppc_stat: unit %d PAPER OUT condition cleared: ADVISORY. The previously-detected PAPER OUT condition has been cleared by the device connected to the parallel port on the enumerated board (PAPER OUT line de-asserted).
ppc_stat: unit %d OFFLINE: ADVISORY. The device connected to the parallel port on the enumerated board has signaled that it is offline (SLCT line de-asserted).
ppc_stat: unit %d OFFLINE condition cleared: ADVISORY. The previously-detected off line condition has been cleared by the device connected to the parallel port on the enumerated board (SLCT line asserted).
ppc_stat: unit %d ERROR: ADVISORY. The device connected to the parallel port on the enumerated board has signalled that it has encountered an error of some sort (ERROR line asserted).
ppc_stat: unit %d ERROR condition cleared: ADVISORY. The previously-detected error condition has been cleared by the device connected to the parallel port on the enumerated board (ERROR line de-asserted).
ppc_acktimeout: unit %d ACK timeout: ERROR. The ACK line from the device connected to the parallel port did not assert itself within the configurable timeout period. Check to be sure that the device is connected and powered on.
ppc_acktimeout: unit %d BUSY timeout: ERROR. The BUSY line from the device connected to the parallel port did not de-assert itself within the configurable timeout period. Check to be sure that the device is connected and powered on.
ppc_int: unit %d stray interrupt: ADVISORY. The parallel port controller (ppc) chip generated an interrupt while the device was closed. This was unexpected, and if you see it frequently, your parallel cable may be picking up induced noise, causing the ppc to generate an unwanted interrupt; or this could indicate an internal problem in the ppc.
ppc_acktimeout: unit %d can't get pointer to read q: ERROR. The driver's internal ppc data structure became corrupted.
ppc_acktimeout: unit %d can't send M_ERROR message: ERROR. The driver can't send an M_ERROR STREAMS message to the application.
ppc_signal: unit %d can't get pointer to read q: ERROR. The driver's internal ppc data structure became corrupted.
ppc_signal: unit %d can't send M_PCSIG(PP_SIGTYPE 0x%x) message: ERROR. The driver can't send an M_PCSIG STREAMS message to the application (which could cause a signal to be posted).

Messages Related To STREAMS Processing

stc_wput: unit %d trying to M_STARTI on ppc or control device: ADVISORY. An M_STARTI STREAMS message was sent to the parallel port or the board control device, which should only happen if an application explicitly sends this message.
stc_wput: unit %d line %d unknown message: 0x%x: ADVISORY. An unknown STREAMS message was sent to the driver. Check your application coding.
stc_start: unit %d line %d unknown message: 0x%x: ADVISORY. An unknown STREAMS message was sent to the driver. Check your application coding.

Messages Related To Serial Port Control

stc_ioctl: unit %d line %d can't allocate streams buffer for ioctl: ERROR. The driver could not get a STREAMS message buffer from bufcall() for the requested ioctl(); theioctl() will not be executed.
stc_ioctl: unit %d line %d can't allocate STC_DCONTROL block: ERROR. The driver could not allocate a data block from allocb(9F) for the STC_DCONTROL return value; the ioctl() does not get executed.
stc_ioctl: unit %d line %d can't allocate STC_GPPC block: ERROR. The driver could not allocate a data block from allocb() for the STC_GPPC return value; the ioctl() does not get executed.
stc_ioctl: unit %d line %d can't allocate TIOCMGET block: ERROR. The driver could not allocate a data block from allocb() for the TIOCMGET return value; the ioctl() does not get executed.
stc_vdcmd: unit %d cd-180 firmware revision: 0x%x: ADVISORY. This message displays the firmware revision level of the cd-180 when the driver is first loaded.

SunOS 5.9 Last Revised 6 Feb 2002