zsh(7)
NAME
zsh − on-board serial HDLC interface
SYNOPSIS
#include <fcntl.h>
open(/dev/zshn, 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(7) driver, providing access to an HDLC interface through character-special devices.
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 transmitter clock (TRxC), receiver clock (RTxC), or the internal baud rate generator (BRG). Use of the Z8530 Digital Phase-Lock Loop (DPLL) option as a clock source is not supported on this interface.
The baud rate generator is a programmable divisor that derives a clock frequency from PCLK. 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.
The zsh 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 CRC errors, transmit underruns, receive overruns, input errors and output errors. 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 driver has given up trying to restart a transmission after several watchdog timeouts.
IOCTLS
The zsh driver supports four ioctl(2) commands:
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 baudrate.
S_IOCSETMODE
The argument is a struct scc_mode from which the Z8530 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 characters 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.
The following structures are used with zsh ioctl() commands:
struct scc_mode {
charsm_txclock;/∗ transmit clock sources ∗/
charsm_rxclock;/∗ receive clock sources ∗/
charsm_loopback;/∗ boolean - internal loopback ∗/
charsm_nrzi;/∗ boolean - use NRZI ∗/
intsm_baudrate;/∗ real baud rate ∗/
};
struct sl_stats {
longipack;/∗ input packets ∗/
longopack;/∗ output packets ∗/
longichar;/∗ input bytes ∗/
longochar;/∗ output bytes ∗/
longabort;/∗ abort received ∗/
longcrc;/∗ CRC error ∗/
longcts;/∗ CTS timeouts ∗/
longdcd;/∗ Carrier drops ∗/
longoverrun;/∗ receive overrun ∗/
longunderrun;/∗ transmit underrun ∗/
longierror;/∗ input error ∗/
longoerror;/∗ output error ∗/
};
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 as an asynchronous (tty or cua) device.
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 generator would translate to a null time constant in the Z8530 registers.
FILES
/dev/zsh[0-1]
character-special devices
<sys/ser_sync.h>
header specifying synchronous serial communication definitions
SEE ALSO
Refer to the Zilog Z8530 SCC Serial Communications Controller Technical Manual for details of the SCC’s operation and capabilities.
DIAGNOSTICS
zshn: unable to send up message of size s, freeing.
A message s bytes in length could not be sent up from the driver during a close() and had to be discarded.
zshn: transmit hung in state x.
The transmitter was not successfully restarted after the watchdog timer expired. The meaning of the hexadecimal state number is defined in <sys/ser_sync.h>.
zsh_open: open fails, can’t alloc message
The open(2) could not proceed because allocb() failed to return an initial message block for received messages.
BUGS
Because of the way interface signals are internally routed to the Z8530 chip on SPARCstation IPC systems, synchronous communications with externally supplied receive clocks cannot be supported on these systems.
SunOS 5.1 — Last change: 29 Sep 1991