'\" te
.\" Copyright (c) 1997, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ZSH 7D "Jan 1, 1997"
.SH NAME
zsh \- On-board serial HDLC/SDLC interface
.SH SYNOPSIS
.LP
.nf
#include <fcntl.h>
.fi
.LP
.nf
open(/dev/zsh\fIn, mode \fR\fB);\fR
.fi
.LP
.nf
open(/dev/zsh\fI, mode \fR\fB);\fR
.fi
.SH DESCRIPTION
.sp
.LP
The \fBzsh\fR module is a loadable \fBSTREAMS\fR driver that implements the
sending and receiving of data packets as \fBHDLC\fR frames over synchronous
serial lines. The module is not a standalone driver, but instead depends upon
the \fBzs\fR module for the hardware support required by all on-board serial
devices. When loaded this module acts as an extension to the \fBzs\fR driver,
providing access to an \fBHDLC\fR interface through character-special devices.
.sp
.LP
The \fBzsh\fR\fIn\fR devices provide what is known as a \fBdata path\fR which
supports the transfer of data via \fBread\fR(2) and \fBwrite\fR(2) system
calls, as well as \fBioctl\fR(2) calls. Data path opens are exclusive in order
to protect against injection or diversion of data by another process.
.sp
.LP
The \fBzsh\fR device provides a separate \fBcontrol path\fR for use by programs
that need to configure or monitor a connection independent of any exclusive
access restrictions imposed by data path opens. Up to three control paths may
be active on a particular serial channel at any one time. Control path
accesses are restricted to \fBioctl\fR(2) calls only; no data transfer is
possible.
.sp
.LP
When used in synchronous modes, the \fBZ8530 SCC\fR supports several options
for \fBclock sourcing\fR and \fBdata encoding\fR. Both the transmit and receive
clock sources can be set to be the external \fBT\fRransmit \fBC\fRlock
(\fBTRxC\fR), external \fBR\fReceive \fBC\fRlock (\fBRTxC\fR), the internal
\fBB\fRaud \fBR\fRate \fBG\fRenerator (\fBBRG\fR), or the output of the
\fBSCC\fR's \fBD\fRigital \fBP\fRhase-\fBL\fRock \fBL\fRoop (\fBDPLL\fR).
.sp
.LP
The \fBB\fRaud \fBR\fRate \fBG\fRenerator is a programmable divisor that
derives a clock frequency from the \fBPCLK\fR input signal to the \fBSCC\fR. A
programmed baud rate is translated into a 16-bit \fBtime\fR \fBconstant\fR that
is stored in the \fBSCC\fR. When using the \fBBRG\fR as a clock source the
driver may answer a query of its current speed with a value different from the
one specified. This is because baud rates translate into time constants in
discrete steps, and reverse translation shows the change. If an exact baud
rate is required that cannot be obtained with the \fBBRG\fR, an external clock
source must be selected.
.sp
.LP
Use of the \fBDPLL\fR option requires the selection of \fBNRZI\fR data encoding
and the setting of a non-zero value for the baud rate, because the \fBDPLL\fR
uses the \fBBRG\fR as its reference clock source.
.sp
.LP
A \fBlocal loopback mode\fR is available, primarily for use by the
\fBsyncloop\fR(1M) utility for testing purposes, and should not be confused
with \fBSDLC\fR loop mode, which is not supported on this interface. Also, an
\fBauto-echo\fR feature may be selected that causes all incoming data to be
routed to the transmit data line, allowing the port to act as the remote end of
a digital loop. Neither of these options should be selected casually, or left
in use when not needed.
.sp
.LP
The \fBzsh\fR driver keeps running totals of various hardware generated events
for each channel. These include numbers of packets and characters sent and
received, abort conditions detected by the receiver, receive \fBCRC\fR errors,
transmit underruns, receive overruns, input errors and output errors, and
message block allocation failures. Input errors are logged whenever an incoming
message must be discarded, such as when an abort or \fBCRC\fR error is
detected, a receive overrun occurs, or when no message block is available to
store incoming data. Output errors are logged when the data must be discarded
due to underruns, \fBCTS\fR drops during transmission, \fBCTS\fR timeouts, or
excessive watchdog timeouts caused by a cable break.
.SH IOCTLS
.sp
.LP
The \fBzsh\fR driver supports several \fBioctl()\fR commands, including:
.sp
.ne 2
.na
\fB\fBS_IOCGETMODE\fR\fR
.ad
.RS 17n
Return a \fBstruct scc_mode\fR containing parameters currently in use. These
include the transmit and receive clock sources, boolean loopback and
\fBNRZI\fR mode flags and the integer baud rate.
.RE
.sp
.ne 2
.na
\fB\fBS_IOCSETMODE\fR\fR
.ad
.RS 17n
The argument is a \fBstruct scc_mode\fR from which the \fBSCC\fR channel will
be programmed.
.RE
.sp
.ne 2
.na
\fB\fBS_IOCGETSTATS\fR\fR
.ad
.RS 17n
Return a \fBstruct sl_stats\fR containing the current totals of
hardware-generated events. These include numbers of packets and characters sent
and received by the driver, aborts and \fBCRC\fR errors detected, transmit
underruns, and receive overruns.
.RE
.sp
.ne 2
.na
\fB\fBS_IOCCLRSTATS\fR\fR
.ad
.RS 17n
Clear the hardware statistics for this channel.
.RE
.sp
.ne 2
.na
\fB\fBS_IOCGETSPEED\fR\fR
.ad
.RS 17n
Returns the currently set baud rate as an integer. This may not reflect the
actual data transfer rate if external clocks are used.
.RE
.sp
.ne 2
.na
\fB\fBS_IOCGETMCTL\fR\fR
.ad
.RS 17n
Returns the current state of the \fBCTS\fR and \fBDCD\fR incoming modem
interface signals as an integer.
.RE
.sp
.LP
The following structures are used with \fBzsh\fR \fBioctl()\fR commands:
.sp
.in +2
.nf
struct scc_mode {
char sm_txclock; /* transmit clock sources */
char sm_rxclock; /* receive clock sources */
char sm_iflags; /* data and clock inversion flags (non-zsh) */
uchar_t sm_config; /* boolean configuration options */
int sm_baudrate; /* real baud rate */
int sm_retval; /* reason codes for ioctl failures */
};
struct sl_stats {
long ipack; /* input packets */
long opack; /* output packets */
long ichar; /* input bytes */
long ochar; /* output bytes */
long abort; /* abort received */
long crc; /* CRC error */
long cts; /* CTS timeouts */
long dcd; /* Carrier drops */
long overrun; /* receive overrun */
long underrun; /* transmit underrun */
long ierror; /* input error */
long oerror; /* output error */
long nobuffers; /* receive side memory allocation failure */
};
.fi
.in -2
.SH ERRORS
.sp
.LP
An \fBopen()\fR will fail if a \fBSTREAMS\fR message block cannot be allocated,
or:
.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 9n
The unit being opened does not exist.
.RE
.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 9n
The device is in use by another serial protocol.
.RE
.sp
.LP
An \fBioctl()\fR will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
An attempt was made to select an invalid clocking source.
.RE
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The baud rate specified for use with the baud rate generator would translate to
a null time constant in the \fBSCC\fR's registers.
.RE
.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/zsh[0-1]\fR,\fB/dev/zsh\fR\fR
.ad
.sp .6
.RS 4n
character-special devices
.RE
.sp
.ne 2
.na
\fB\fB/usr/include/sys/ser_sync.h\fR\fR
.ad
.sp .6
.RS 4n
header file specifying synchronous serial communication definitions
.RE
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
Architecture x86
.TE
.SH SEE ALSO
.sp
.LP
\fBsyncinit\fR(1M), \fBsyncloop\fR(1M), \fBsyncstat\fR(1M), \fBioctl\fR(2),
\fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5), \fBzs\fR(7D)
.sp
.LP
Refer to the \fIZilog Z8530 SCC Serial Communications Controller Technical
Manual\fR for details of the \fBSCC\fR's operation and capabilities.
.SH DIAGNOSTICS
.sp
.ne 2
.na
\fB\fBzsh data open failed, no memory, rq=\fR\fInnn\fR\fR
.ad
.sp .6
.RS 4n
.RE
.sp
.ne 2
.na
\fB\fBzsh clone open failed, no memory, rq=\fR\fInnn\fR\fR
.ad
.sp .6
.RS 4n
A kernel memory allocation failed for one of the private data structures. The
value of \fInnn\fR is the address of the read queue passed to \fBopen\fR(2).
.RE
.sp
.ne 2
.na
\fB\fBzsh_open: can't alloc message block\fR\fR
.ad
.sp .6
.RS 4n
The open could not proceed because an initial \fBSTREAMS\fR message block could
not be made available for incoming data.
.RE
.sp
.ne 2
.na
\fB\fBzsh: clone device \fR\fId\fR\fB must be attached before use!\fR\fR
.ad
.sp .6
.RS 4n
An operation was attempted through a control path before that path had been
attached to a particular serial channel.
.RE
.sp
.ne 2
.na
\fB\fBzsh\fR\fIn\fR\fB: invalid operation for clone dev.\fR\fR
.ad
.sp .6
.RS 4n
An inappropriate \fBSTREAMS\fR message type was passed through a control path.
Only \fBM_IOCTL\fR and \fBM_PROTO\fR message types are permitted.
.RE
.sp
.ne 2
.na
\fB\fBzsh\fR\fIn\fR\fB: not initialized, can't send message\fR\fR
.ad
.sp .6
.RS 4n
An \fBM_DATA\fR message was passed to the driver for a channel that had not
been programmed at least once since the driver was loaded. The \fBSCC\fR's
registers were in an unknown state. The \fBS_IOCSETMODE\fR ioctl command
performs the programming operation.
.RE
.sp
.ne 2
.na
\fB\fBzsh\fR\fIn\fR\fB: transmit hung\fR\fR
.ad
.sp .6
.RS 4n
The transmitter was not successfully restarted after the watchdog timer
expired.
.RE