share/man/man7d/zsh.7d

   1 '\" te
   2 .\" Copyright (c) 1997, Sun Microsystems, Inc.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH ZSH 7D "Jan 1, 1997"
   7 .SH NAME
   8 zsh \- On-board serial HDLC/SDLC interface
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <fcntl.h>
  13 .fi
  14
  15 .LP
  16 .nf
  17 open(/dev/zsh\fIn, mode \fR\fB);\fR
  18 .fi
  19
  20 .LP
  21 .nf
  22 open(/dev/zsh\fI, mode \fR\fB);\fR
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBzsh\fR module is a loadable \fBSTREAMS\fR driver that implements the
  29 sending and receiving of data packets as \fBHDLC\fR frames over synchronous
  30 serial lines. The module is not a standalone driver, but instead depends upon
  31 the \fBzs\fR module for the hardware support required by all on-board serial
  32 devices. When loaded this module acts as an extension to the \fBzs\fR driver,
  33 providing access to an \fBHDLC\fR interface through character-special devices.
  34 .sp
  35 .LP
  36 The \fBzsh\fR\fIn\fR devices provide what is known as a \fBdata path\fR which
  37 supports the transfer of data via \fBread\fR(2) and \fBwrite\fR(2) system
  38 calls, as well as \fBioctl\fR(2) calls. Data path opens are exclusive in order
  39 to protect against injection or diversion of data by another process.
  40 .sp
  41 .LP
  42 The \fBzsh\fR device provides a separate \fBcontrol path\fR for use by programs
  43 that need to configure or monitor a connection independent of any exclusive
  44 access restrictions imposed by data path opens.  Up to three control paths may
  45 be active on a particular serial channel at any one time.  Control path
  46 accesses are restricted to \fBioctl\fR(2) calls only; no data transfer is
  47 possible.
  48 .sp
  49 .LP
  50 When used in synchronous modes, the \fBZ8530 SCC\fR supports several options
  51 for \fBclock sourcing\fR and \fBdata encoding\fR. Both the transmit and receive
  52 clock sources can be set to be the external \fBT\fRransmit \fBC\fRlock
  53 (\fBTRxC\fR), external \fBR\fReceive \fBC\fRlock (\fBRTxC\fR), the internal
  54 \fBB\fRaud \fBR\fRate \fBG\fRenerator (\fBBRG\fR), or the output of the
  55 \fBSCC\fR's \fBD\fRigital \fBP\fRhase-\fBL\fRock \fBL\fRoop (\fBDPLL\fR).
  56 .sp
  57 .LP
  58 The \fBB\fRaud \fBR\fRate \fBG\fRenerator is a programmable divisor that
  59 derives a clock frequency from the \fBPCLK\fR input signal to the \fBSCC\fR. A
  60 programmed baud rate is translated into a 16-bit \fBtime\fR \fBconstant\fR that
  61 is stored in the \fBSCC\fR. When using the \fBBRG\fR as a clock source the
  62 driver may answer a query of its current speed with a value different from the
  63 one specified.  This is because baud rates translate into time constants in
  64 discrete steps, and reverse translation shows the change.  If an exact baud
  65 rate is required that cannot be obtained with the \fBBRG\fR, an external clock
  66 source must be selected.
  67 .sp
  68 .LP
  69 Use of the \fBDPLL\fR option requires the selection of \fBNRZI\fR data encoding
  70 and the setting of a non-zero value for the baud rate, because the \fBDPLL\fR
  71 uses the \fBBRG\fR as its reference clock source.
  72 .sp
  73 .LP
  74 A \fBlocal loopback mode\fR is available, primarily for use by the
  75 \fBsyncloop\fR(8) utility for testing purposes, and should not be confused
  76 with \fBSDLC\fR loop mode, which is not supported on this interface.  Also, an
  77 \fBauto-echo\fR feature may be selected that causes all incoming data to be
  78 routed to the transmit data line, allowing the port to act as the remote end of
  79 a digital loop. Neither of these options should be selected casually, or left
  80 in use when not needed.
  81 .sp
  82 .LP
  83 The \fBzsh\fR driver keeps running totals of various hardware generated events
  84 for each channel.  These include numbers of packets and characters sent and
  85 received, abort conditions detected by the receiver, receive \fBCRC\fR errors,
  86 transmit underruns, receive overruns, input errors and output errors, and
  87 message block allocation failures. Input errors are logged whenever an incoming
  88 message must be discarded, such as when an abort or \fBCRC\fR error is
  89 detected, a receive overrun occurs, or when no message block is available to
  90 store incoming data.  Output errors are logged when the data must be discarded
  91 due to underruns, \fBCTS\fR drops during transmission, \fBCTS\fR timeouts, or
  92 excessive watchdog timeouts caused by a cable break.
  93 .SH IOCTLS
  94 .sp
  95 .LP
  96 The \fBzsh\fR driver supports several \fBioctl()\fR commands, including:
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBS_IOCGETMODE\fR\fR
 101 .ad
 102 .RS 17n
 103 Return a \fBstruct scc_mode\fR containing parameters currently in use. These
 104 include the transmit and receive clock sources, boolean loopback and
 105 \fBNRZI\fR mode flags and the integer baud rate.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBS_IOCSETMODE\fR\fR
 112 .ad
 113 .RS 17n
 114 The argument is a \fBstruct scc_mode\fR from which the \fBSCC\fR channel will
 115 be programmed.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBS_IOCGETSTATS\fR\fR
 122 .ad
 123 .RS 17n
 124 Return a \fBstruct sl_stats\fR containing the current totals of
 125 hardware-generated events. These include numbers of packets and characters sent
 126 and received by the driver, aborts and \fBCRC\fR errors detected, transmit
 127 underruns, and receive overruns.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBS_IOCCLRSTATS\fR\fR
 134 .ad
 135 .RS 17n
 136 Clear the hardware statistics for this channel.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBS_IOCGETSPEED\fR\fR
 143 .ad
 144 .RS 17n
 145 Returns the currently set baud rate as an integer.  This may not reflect the
 146 actual data transfer rate if external clocks are used.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBS_IOCGETMCTL\fR\fR
 153 .ad
 154 .RS 17n
 155 Returns the current state of the \fBCTS\fR and \fBDCD\fR incoming modem
 156 interface signals as an integer.
 157 .RE
 158
 159 .sp
 160 .LP
 161 The following structures are used with \fBzsh\fR \fBioctl()\fR commands:
 162 .sp
 163 .in +2
 164 .nf
 165 struct  scc_mode {
 166         char  sm_txclock;   /* transmit clock sources */
 167         char  sm_rxclock;   /* receive clock sources */
 168         char  sm_iflags;    /* data and clock inversion flags (non-zsh) */
 169         uchar_t  sm_config; /* boolean configuration options */
 170         int  sm_baudrate;   /* real baud rate */
 171         int  sm_retval;     /* reason codes for ioctl failures */
 172 };
 173 struct  sl_stats {
 174         long  ipack;        /* input packets */
 175         long  opack;        /* output packets */
 176         long  ichar;        /* input bytes */
 177         long  ochar;        /* output bytes */
 178         long  abort;        /* abort received */
 179         long  crc;          /* CRC error */
 180         long  cts;          /* CTS timeouts */
 181         long  dcd;          /* Carrier drops */
 182         long  overrun;      /* receive overrun */
 183         long  underrun;     /* transmit underrun */
 184         long  ierror;       /* input error */
 185         long  oerror;       /* output error */
 186         long  nobuffers;    /* receive side memory allocation failure */
 187 };
 188 .fi
 189 .in -2
 190
 191 .SH ERRORS
 192 .sp
 193 .LP
 194 An \fBopen()\fR will fail if a \fBSTREAMS\fR message block cannot be allocated,
 195 or:
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBENXIO\fR\fR
 200 .ad
 201 .RS 9n
 202 The unit being opened does not exist.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBEBUSY\fR\fR
 209 .ad
 210 .RS 9n
 211 The device is in use by another serial protocol.
 212 .RE
 213
 214 .sp
 215 .LP
 216 An \fBioctl()\fR will fail if:
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBEINVAL\fR\fR
 221 .ad
 222 .RS 10n
 223 An attempt was made to select an invalid clocking source.
 224 .RE
 225
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBEINVAL\fR\fR
 230 .ad
 231 .RS 10n
 232 The baud rate specified for use with the baud rate generator would translate to
 233 a null time constant in the \fBSCC\fR's registers.
 234 .RE
 235
 236 .SH FILES
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fB/dev/zsh[0-1]\fR,\fB/dev/zsh\fR\fR
 241 .ad
 242 .sp .6
 243 .RS 4n
 244 character-special devices
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fB/usr/include/sys/ser_sync.h\fR\fR
 251 .ad
 252 .sp .6
 253 .RS 4n
 254 header file specifying synchronous serial communication definitions
 255 .RE
 256
 257 .SH ATTRIBUTES
 258 .sp
 259 .LP
 260 See \fBattributes\fR(5) for descriptions of the following attributes:
 261 .sp
 262
 263 .sp
 264 .TS
 265 box;
 266 c | c
 267 l | l .
 268 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 269 _
 270 Architecture    x86
 271 .TE
 272
 273 .SH SEE ALSO
 274 .sp
 275 .LP
 276 \fBsyncinit\fR(8), \fBsyncloop\fR(8), \fBsyncstat\fR(8), \fBioctl\fR(2),
 277 \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5), \fBzs\fR(7D)
 278 .sp
 279 .LP
 280 Refer to the \fIZilog Z8530 SCC Serial Communications Controller Technical
 281 Manual\fR for details of the \fBSCC\fR's operation and capabilities.
 282 .SH DIAGNOSTICS
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBzsh data open failed, no memory, rq=\fR\fInnn\fR\fR
 287 .ad
 288 .sp .6
 289 .RS 4n
 290
 291 .RE
 292
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fBzsh clone open failed, no memory, rq=\fR\fInnn\fR\fR
 297 .ad
 298 .sp .6
 299 .RS 4n
 300 A kernel memory allocation failed for one of the private data structures. The
 301 value of \fInnn\fR is the address of the read queue passed to \fBopen\fR(2).
 302 .RE
 303
 304 .sp
 305 .ne 2
 306 .na
 307 \fB\fBzsh_open: can't alloc message block\fR\fR
 308 .ad
 309 .sp .6
 310 .RS 4n
 311 The open could not proceed because an initial \fBSTREAMS\fR message block could
 312 not be made available for incoming data.
 313 .RE
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fBzsh: clone device \fR\fId\fR\fB must be attached before use!\fR\fR
 319 .ad
 320 .sp .6
 321 .RS 4n
 322 An operation was attempted through a control path before that path had been
 323 attached to a particular serial channel.
 324 .RE
 325
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fBzsh\fR\fIn\fR\fB: invalid operation for clone dev.\fR\fR
 330 .ad
 331 .sp .6
 332 .RS 4n
 333 An inappropriate \fBSTREAMS\fR message type was passed through a control path.
 334 Only \fBM_IOCTL\fR and \fBM_PROTO\fR message types are permitted.
 335 .RE
 336
 337 .sp
 338 .ne 2
 339 .na
 340 \fB\fBzsh\fR\fIn\fR\fB: not initialized, can't send message\fR\fR
 341 .ad
 342 .sp .6
 343 .RS 4n
 344 An \fBM_DATA\fR message was passed to the driver for a channel that had not
 345 been programmed at least once since the driver was loaded.  The \fBSCC\fR's
 346 registers were in an unknown state.  The \fBS_IOCSETMODE\fR ioctl command
 347 performs the programming operation.
 348 .RE
 349
 350 .sp
 351 .ne 2
 352 .na
 353 \fB\fBzsh\fR\fIn\fR\fB: transmit hung\fR\fR
 354 .ad
 355 .sp .6
 356 .RS 4n
 357 The transmitter was not successfully restarted after the watchdog timer
 358 expired.
 359 .RE
 360