NAME

SPC/S − Serial Parallel Communications driver for SBus (stc)

KERNEL CONFIG

device-driverstc# SPC/S octal serial/parallel board

MODLOAD

/dev/stc_config -l
modload -sym -o /dev/stc /dev/stc.o -entry _stc_vdcmd

SYNOPSIS

#include <fcntl.h>
#include <sys/termios.h>
#include <sbusdev/stcio.h>
open("/dev/ttyy[00-3f]", mode);
open("/dev/ttyz[00-3f]", mode);
open("/dev/stclpn", mode);
open("/dev/stcn", mode);

DESCRIPTION

The SPC/S SBus communications board consists of 8 asynchronous serial ports and one IBM PS/2-compatiable parallel port. The stc driver supports up to 3 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, plus 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(4) device control functions specified by flags in the c_cflag word of the termios(4) structure; in addition, the serial ports support the IGNPAR, PARMRK, INPCK, IXON, IXANY and IXOFF flags in the c_iflag word of the termios(4) 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(4) (c_iflag) parameters apply to it.  Trying to execute a nonsensical ioctl() on the parallel port is dicey at best.  All other termios(4) functions are performed by STREAMS modules pushed atop the driver; when an stc device is opened, the ldterm(4M) and ttcompat(4M) STREAMS modules are automatically pushed on top of the stream, providing the standard termios(4) interface.  Driver-specific ioctl()’s can be found in /usr/include/sbusdev/stcio.h

Of the synopsis lines above, the line for /dev/ttyyn specifies the serial I/O port(s) provided on the SPC/S board, conventionally as incoming lines; the line for /dev/ttyzn specifies the serial I/O port(s) provided on the SPC/S board, conventionally as outgoing lines; the line for /dev/stclpn specifies the parallel port, and the line for /dev/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/ttyyn, where n is a number indicating which dial-in line it is (so that /dev/ttyy00 is the first dial-in line), and 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/ttyzn, where n is the number of the dial-in line.  The /dev/ttyzn devices correspond to the UNIX convention of /dev/cuan naming for "outgoing" (or call-unit) lines. 

The /dev/ttyzn lines are special in that they can be opened even when there is no carrier on the line.  Once a /dev/ttyzn line is opened, the corresponding /dev/ttyyn line can not be opened until the /dev/ttyzn line is closed; a blocking open will wait until the /dev/ttyzn line is closed (which will drop DTR, after which DCD will usually drop as well) and carrier is detected again, and a non-blocking open will return an error.  Also, if the /dev/ttyyn line has been opened successfully (usually only when carrier is recognized on the modem) the corresponding /dev/ttyzn line can not be opened.  This allows a modem to be attached to e.g.  /dev/ttyy00 and used for dial-in (by enabling the line for login in /etc/ttytab) and also used for dial-out (by tip(1C) or uucp(1C)) as /dev/ttyz00 when no one is logged in on the line. 

MINOR NUMBERS

o p u u | u l l l - these correspond to bits in the minor number

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 are supported by the stc driver on both the serial and parallel ports. 

If the CRTSCTS flag in the c_cflag is set, output will be generated only if CTS is high; 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(4). 

DEVICE SPECIFIC IOCTLS

The following additional ioctl()’s are supported by the stc driver. They and the corresponding structures are defined in /usr/include/sbusdev/stcio.h:

STC_DCONTROL(struct stc_defaults_t ∗)

sets/gets default parameters for any line; flushes write queues for any line; process’s uid must be root to set; operates only on /dev/stcn port

STC_SDEFAULTS(struct stc_defaults_t ∗)

sets default parameters for line that take effect on next open(); process’s uid must be root to set

STC_GDEFAULTS(struct stc_defaults_t ∗)

get default parameters (may not be active yet)

STC_SPPC(struct ppc_params_t ∗)

set parallel port parameters (valid until changed or close())

STC_GPPC(struct ppc_params_t ∗)

get parallel port parameters (valid until changed or close())

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 or the open_inhibit flag in the driver is set due to an earlier unsucessfull VDUNLOAD request. 

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 couldn’t 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_DCONTROL or STC_SDEFAULTS ioctl() was requested by a process whose uid was not root. 

ENOTTY An unrecognized ioctl() command was received. 

A vd_cmd() will fail with errno set to:

EBUSY A VDUNLOAD was requested while at least one device on the board was in use by a process. 

EINVAL An invalid command was sent to stc_vdcmd(). 

FILES

/dev/ttyy[00-3f] hardwired and dial-in tty lines

/dev/ttyz[00-3f] dial-out tty lines

/dev/stclp[0-7] parallel port lines

/dev/stc[0-7] control port (see /usr/include/sbusdev/stcio.h for more info)

/usr/include/sbusdev/stcio.h
header file with ioctl()’s supported by this driver

/usr/etc/stc/stc_defaults
port defaults data file

/usr/etc/stc/stc_defs
program to set port defaults

/etc/loadable commands to load loadable driver on bootup and set port defaults

/etc/rc.local modified to provide a call to /etc/loadable

/usr/sys/unbundled/stc/stc_config

/dev/stc_config configuration script to load loadable version of driver and make device nodes

EXAMPLES

Check out the /usr/sys/unbundled/stc/examples directory. 

SOFTCAR, DTR and CTS/RTS FLOW CONTROL

The traditional method of specifying soft carrier for a particular serial line, setting a bit in the flags field on the kernel config line when configuring a serial device driver into the kernel, is not supported in the stc driver, since in most cases the driver is loaded at runtime rather than statically configured into the kernel.  Several methods may be used to specify that a particular serial line is to have soft carrier either enabled or disabled. The non-programmatic method is to edit the /usr/etc/stc/stc_defaults file after which you run the /usr/etc/stc/stc_defs program; see the next section, DEFAULTING OTHER 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, or by issuing the STC_SDEFAULTS ioctl() using the flags field bit SOFT_CARR (the latter is the preferred method).  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 deassert it on the last close().  To change the operation of this feature, issue the STC_SDEFAULTS ioctl() using the flags field bit DTR_ASSERT.  To control the default actions of the CTS and RTS hardware handshaking lines, issue the STC_SDEFAULTS ioctl() using the CRTSCTS bit of the cflag field in the termios structure. 

DEFAULTING OTHER LINE PARAMETERS

Many other default parameters of the serial and parallel ports can be changed using the STC_SDEFAULTS ioctl() on the particular line or via the /usr/etc/stc/stc_defs program.  See the /usr/include/sbusdev/stcio.h header file for a programmatic way to change a line’s defaults, or look at /usr/sys/unbundled/stc/stc_defaults.doc for more information on the /usr/etc/stc/stc_defs program. 

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-compatiable (Centronics-compatiable) 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 brain-dead 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 does 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 deasserted, a deadlock condition occurs.  To remedy this situation, you can change the default signal list that the stc driver will monitor on the parallel port by removing the SELECT signal from the list.  This can be done either through the /usr/etc/stc/stc_defs program or programmatically through the STC_SDEFAULTS ioctl() call.  The file /usr/etc/stc/stc_defaults contains an example of an entry for this type of printer, as well as more information on the format of this file. 

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 (i.e. open()) by a process, the driver will not be 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 sucessfully unloaded.  You cannot modload the stc device driver if it is also configured into the currently running kernel; the error you will typically see will be multiply defined symbols and the modload procedure will terminate with an error code.  If you unload and then re-load the driver using modunload and modload, you should re-run the /usr/etc/stc/stc_defs program to re-establish the default parameters of the ports; this information is not retained between unloading and loading the driver.  If you use the stc_config script to re-load the driver, the script will run the /usr/etc/stc/stc_defs program as the last step in the driver loading process, which will reestablish any default port parameters that you have set up in the /usr/etc/stc/stc_defaults file.  There is no real reason to configure the driver into the kernel unless you run out of vd slots in the cdevsw[] table for loadable drivers. 

FLUSHING WRITE QUEUES

In some instances it is is desirable to flush the downstream write queues maintained by STREAMS; this is especially true if a serial port has blocked the transfer of outgoing data due to flow control taking effect and the process sending data on that port decides to close() that port.  Due to a STREAMS bug, the close() will wait indefinitely for any remaining data to be removed from the STREAMS queues by the driver and sent to the device.  Since the attached device has asserted flow control to stop the transfer of data from the SPC/S driver to the device, and the possibility exists that the attached device may never deassert flow control, the STC_DCONTROL ioctl() has an op-field operation that will flush the write queues on any of the SPC/S’s ports by sinking the data from the STREAMS queues and depositing it into a bit bucket.  This can be carried out by the SFLUSH operation.  For example code that does this, refer to /usr/include/sys/unbundled/stc/examples/sflush.c. 

SEE ALSO

tip(1C), uucp(1C), mcp(4S), mti(4S), termio(4), ldterm(4M), ttcompat(4M)

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 get loaded and any SPC/S boards installed in the system are inacessable (usually occurs during the process of modload’ing the driver)

ERROR - some condition has caused the normal operation of the board and/or device driver to be disrupted; data loss may or may not occur; this class of message might indicate an impending hardware failure

ADVISORY - the device driver has detected a condition that may be of interest to the user of the system; usually this is a transient condition that clears itself

messages during initialization of driver/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: wierd oscillarot 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. some 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. 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. 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 that is on the SPC/S card have been released; V1.0 (0x4) and V1.1 (0x5).  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)

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 map the SBus interrupt levels that the SPC/S uses correctly

messages releated to the serial ports:

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; check that you are using the correct flow control; all data in the silo is flushed; this message may also frequently appear due to 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 may also frequently appear due to 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(); 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 releated 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’s 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 deasserted)

ppc_stat: unit %d OFFLINE

ADVISORY. the device connected to the parallel port on the enumerated board has signalled that it is off-line (SLCT line deasserted)

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

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 deassert 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 might be picking up induced noise causing the ppc to generate an unwanted interrupt, or this could indicate that the ppc might have an internal problem

ppc_acktimeout: unit %d can’t get pointer to read q

ERROR. somehow the driver’s internal ppc data structure has gotten corrupted; this should not happen

ppc_acktimeout: unit %d can’t send M_ERROR message

ERROR. the driver can’t send an M_ERROR STREAMS message to the application; this should not happen either

ppc_signal: unit %d can’t get pointer to read q

ERROR. somehow the driver’s internal ppc data structure has gotten corrupted; this should also not happen

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); this should also not happen either

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; this should only happen if an application explictly 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; the ioctl 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() for the STC_DCONTROL return value; the ioctl does not get executed

stc_ioctl: unit %d line %d can’t allocate STC_GDEFAULTS block

ERROR. the driver could not allocate a data block from allocb() for the STC_GDEFAULTS 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_restart: unit %d line %d BREAK BIT off (ERROR)

ADVISORY. the BREAK control bit for the enumerated line was observed to be set when it should have been clear; this might indicate a faulty cd-180 or corrupted software

messages related to loading/unloading driver:

stc_vdcmd: can’t unload stc driver, some device(s) are still open

ERROR. the driver could not be unloaded since at least one of the devices that the driver controls is still in use (open) by a process; invoke the stc_config -s command to determine which device(s) are open

stc_vdcmd: unit %d cd-180 firmware revision: 0x%x

ADVISORY. the firmware revision level of the cd-180, displayed when the driver is first loaded

stc_vdcmd: unit %d line %d is open

ADVISORY. the enumerated serial line on the enumerated board is still in use (open) by a process

stc_vdcmd: unit %d ppc is open

ADVISORY. the enumerated board’s parallel port is still in use (open) by a process

stc_vdcmd: unit %d control line is open

ADVISORY. the enumerated board’s board control line is still in use (open) by a process

stc_vdcmd: unknown command: 0x%x

ERROR. an unrecognized command was passed to the driver’s virtual device handler; call Sun® if you see this

Sun Release 4.1  —  Last change: 29 May 1991