zsh(7D) Devices zsh(7D)NAMEzsh - On-board serial HDLC/SDLC interface
SYNOPSIS
#include <fcntl.h>
open(/dev/zshn, mode );
open(/dev/zsh, mode );
DESCRIPTION
The zsh module is a loadable STREAMS driver that implements the sending
and receiving of data packets as HDLC frames over synchronous serial
lines. The module is not a standalone driver, but instead depends upon
the zs module for the hardware support required by all on-board serial
devices. When loaded this module acts as an extension to the zs driver,
providing access to an HDLC interface through character-special
devices.
The zshn devices provide what is known as a data path which supports
the transfer of data via read(2) and write(2) system calls, as well as
ioctl(2) calls.
Data path opens are exclusive in order to protect against injection or
diversion of data by another process.
The zsh device provides a separate control path 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 ioctl(2) calls only; no
data transfer is possible.
When used in synchronous modes, the Z8530 SCC supports several options
for clock sourcing and data encoding. Both the transmit and receive
clock sources can be set to be the external Transmit Clock (TRxC),
external Receive Clock (RTxC), the internal Baud Rate Generator (BRG),
or the output of the SCC's Digital Phase-Lock Loop (DPLL).
The Baud Rate Generator is a programmable divisor that derives a clock
frequency from the PCLK input signal to the SCC. A programmed baud rate
is translated into a 16-bit time constant that is stored in the SCC.
When using the BRG 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 BRG, an external clock source
must be selected.
Use of the DPLL option requires the selection of NRZI data encoding and
the setting of a non-zero value for the baud rate, because the DPLL
uses the BRG as its reference clock source.
A local loopback mode is available, primarily for use by the syn‐
cloop(1M) utility for testing purposes, and should not be confused with
SDLC loop mode, which is not supported on this interface. Also, an
auto-echo 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.
The zsh driver keeps running totals of various hardware generated
events for each channel. These include numbers of packets and charac‐
ters sent and received, abort conditions detected by the receiver,
receive CRC 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 CRC 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, CTS drops dur‐
ing transmission, CTS timeouts, or excessive watchdog timeouts caused
by a cable break.
IOCTLS
The zsh driver supports several ioctl() commands, including:
S_IOCGETMODE Return a struct scc_mode containing parameters
currently in use. These include the transmit
and receive clock sources, boolean loopback and
NRZI mode flags and the integer baud rate.
S_IOCSETMODE The argument is a struct scc_mode from which
the SCC channel will be programmed.
S_IOCGETSTATS Return a struct sl_stats containing the current
totals of hardware-generated events.
These include numbers of packets and charac‐
ters sent and received by the driver, aborts
and CRC errors detected, transmit underruns,
and receive overruns.
S_IOCCLRSTATS Clear the hardware statistics for this channel.
S_IOCGETSPEED Returns the currently set baud rate as an inte‐
ger. This may not reflect the actual data
transfer rate if external clocks are used.
S_IOCGETMCTL Returns the current state of the CTS and DCD
incoming modem interface signals as an integer.
The following structures are used with zshioctl() commands:
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 */
};
ERRORS
An open() will fail if a STREAMS message block cannot be allocated, or:
ENXIO The unit being opened does not exist.
EBUSY The device is in use by another serial protocol.
An ioctl() will fail if:
EINVAL An attempt was made to select an invalid clocking
source.
EINVAL The baud rate specified for use with the baud rate gen‐
erator would translate to a null time constant in the
SCC's registers.
FILES
/dev/zsh[0-1],/dev/zsh character-special devices
/usr/include/sys/ser_sync.h header file specifying synchronous
serial communication definitions
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Architecture │x86 │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOsyncinit(1M), syncloop(1M), syncstat(1M), ioctl(2), open(2), read(2),
write(2), attributes(5), zs(7D)
Refer to the Zilog Z8530 SCC Serial Communications Controller Technical
Manual for details of the SCC's operation and capabilities.
DIAGNOSTICSzsh data open failed, no memory, rq=nnn
zsh clone open failed, no memory, rq=nnn
A kernel memory allocation failed for one of the private data
structures. The value of nnn is the address of the read queue
passed to open(2).
zsh_open: can't alloc message block
The open could not proceed because an initial STREAMS message block
could not be made available for incoming data.
zsh: clone device d must be attached before use!
An operation was attempted through a control path before that path
had been attached to a particular serial channel.
zshn: invalid operation for clone dev.
An inappropriate STREAMS message type was passed through a control
path. Only M_IOCTL and M_PROTO message types are permitted.
zshn: not initialized, can't send message
An M_DATA message was passed to the driver for a channel that had
not been programmed at least once since the driver was loaded. The
SCC's registers were in an unknown state. The S_IOCSETMODE ioctl
command performs the programming operation.
zshn: transmit hung
The transmitter was not successfully restarted after the watchdog
timer expired.
SunOS 5.10 1 Jan 1997 zsh(7D)
