| |
| | stc - Serial Parallel Communications
driver for SBus |
| |
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
|
|
| |
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
| |
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 |
|
|
| |
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
| |
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.
|
|
| |
