NAME | DESCRIPTION | IOCTLS | DEVICE-SPECIFIC IOCTLS | SOFTCAR, DTR and CTS/RTS FLOW CONTROL | SETTING DEFAULT LINE PARAMETERS | PARALLEL PORT PARAMETERS | LOADABLE ISSUES | ERRORS | FILES | SEE ALSO | DIAGNOSTICS
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.
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.
set if this device is an outgoing serial line
set if this is a parallel port device
device unit number
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
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:
honor PAPER OUT from port; returned HIGH means PAPER OUT.
honor ERROR from port; returned HIGH means ERROR.
honor BUSY from port; returned HIGH means BUSY.
honor SELECT from port; returned HIGH means OFFLINE.
print console message on every error scan.
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.
Valid boolean tokens for serial ports are:
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.
Causes the DTR to be asserted on the next open of the port.
Causes DTR to be continuously asserted. It overrides any other DTR operations and ioctl() calls.
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.
Flush any data being held off by remote flow control on close().
Display a message on the console if data transmission is stalled due to remote flow control blocking the transfer in close().
If transmission is stopped by software flow control and the flow control is disabled via an ioctl() call, the transmitter will be enabled immediately.
The display- token is not supported.
Valid tokens requiring values are:
The size of STREAMS buffers allocated when passing data from the receive interrupt handler upstream.
The high water and low water thresholds in the receive interrupt handler 1024 byte buffer.
The inter-character receive timer.
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 |
Valid boolean tokens for parallel ports are
If set, the PAPER OUT signal from the port is monitored. If clear, the signal is ignored.
Monitor the ERROR signal from the port. Ignore the signal if clear.
Monitor the BUSY signal from the port. Ignore the signal if clear.
Monitor the SELECT, or ON LINE, signal from the port. Ignore the signal if clear.
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.
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
The amount of time in seconds to wait for an ACK from the port after asserting STROBE and transferring a byte of data.
Amount of time in seconds to wait for an error to go away.
The amount of time in seconds to wait for a BUSY signal to clear, or zero for an infinite BUSY timeout.
The amount of time in microseconds between placing data ont the parallel lines and asserting the STROBE.
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 |
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:
The unit being opened does not exist.
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.
The open was interrupted by the delivery of a signal.
The control port for the board was opened by a process whose uid was not root.
An ioctl() will fail with errno set to:
A STREAMS data block could not be allocated to return data to the caller.
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.
An STC_GSTATS ioctl() was requested by a process whose uid was not root.
An unrecognized ioctl() command was received.
The stc driver uses the following files:
Hardwired and dial-in tty lines
Dial-out tty lines
Parallel port lines
Control port
Driver configuration file
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:
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.
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.
The device driver has detected a condition that may be of interest, usually a transient condition that clears itself.
The following messages can be generated during initialization of the driver or board.
FATAL. kmem_zalloc() failed to allocate memory for the driver's internal data structures.
FATAL. The driver did not get a hardware revision level from the board's onboard FCode PROM.
FATAL. This revision of the board is not supported by the driver.
FATAL. The driver did not get an oscillator revision level from the board's onboard FCode PROM.
ADVISORY. The board's onboard FCode PROM returned an unanticipated baud-rate oscillator value, so the driver assumes that a 10Mhz oscillator is installed.
FATAL. An error occured while trying to initialize the board; perhaps a memory access failed.
FATAL. An incorrect number of interrupts was read from the board's onboard FCode PROM.
FATAL. An incorrect number of register sets was read from the board's onboard FCode PROM.
FATAL. Either the cd-180 8-channel UART failed to initialize properly or a memory fault occured while trying to access the chip.
FATAL. Either the cd-180 8-channel UART failed to initialize properly or a memory fault occured while trying to access the chip.
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.
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.
ERROR. The cd-180's CCR register did not return to zero within the specified timeout period after it was issued a command
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.
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.
ERROR. The driver could not get a STREAMS message buffer from bufcall(9F). All data in the driver's receive data silo is flushed.
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.
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.
ADVISORY. The device connected to the parallel port on the enumerated BOARD has signalled that it is out of paper (PAPER OUT line asserted).
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).
ADVISORY. The device connected to the parallel port on the enumerated board has signaled that it is offline (SLCT line de-asserted).
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).
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).
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).
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.
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.
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.
ERROR. The driver's internal ppc data structure became corrupted.
ERROR. The driver can't send an M_ERROR STREAMS message to the application.
ERROR. The driver's internal ppc data structure became corrupted.
ERROR. The driver can't send an M_PCSIG STREAMS message to the application (which could cause a signal to be posted).
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.
ADVISORY. An unknown STREAMS message was sent to the driver. Check your application coding.
ADVISORY. An unknown STREAMS message was sent to the driver. Check your application coding.
ERROR. The driver could not get a STREAMS message buffer from bufcall() for the requested ioctl(); theioctl() will not be executed.
ERROR. The driver could not allocate a data block from allocb(9F) for the STC_DCONTROL return value; the ioctl() does not get executed.
ERROR. The driver could not allocate a data block from allocb() for the STC_GPPC return value; the ioctl() does not get executed.
ERROR. The driver could not allocate a data block from allocb() for the TIOCMGET return value; the ioctl() does not get executed.
ADVISORY. This message displays the firmware revision level of the cd-180 when the driver is first loaded.
NAME | DESCRIPTION | IOCTLS | DEVICE-SPECIFIC IOCTLS | SOFTCAR, DTR and CTS/RTS FLOW CONTROL | SETTING DEFAULT LINE PARAMETERS | PARALLEL PORT PARAMETERS | LOADABLE ISSUES | ERRORS | FILES | SEE ALSO | DIAGNOSTICS