1zsh(7D) Devices zsh(7D)
2
6 zsh - On-board serial HDLC/SDLC interface
7
9 #include <fcntl.h>
10 open(/dev/zshn, mode );
13 open(/dev/zsh, mode );
16
19 The zsh module is a loadable STREAMS driver that implements the sending
20 and receiving of data packets as HDLC frames over synchronous serial
21 lines. The module is not a standalone driver, but instead depends upon
22 the zs module for the hardware support required by all on-board serial
23 devices. When loaded this module acts as an extension to the zs driver,
24 providing access to an HDLC interface through character-special
25 devices.
26 The zshn devices provide what is known as a data path which supports
29 the transfer of data via read(2) and write(2) system calls, as well as
30 ioctl(2) calls. Data path opens are exclusive in order to protect
31 against injection or diversion of data by another process.
32 The zsh device provides a separate control path for use by programs
35 that need to configure or monitor a connection independent of any
36 exclusive access restrictions imposed by data path opens. Up to three
37 control paths may be active on a particular serial channel at any one
38 time. Control path accesses are restricted to ioctl(2) calls only; no
39 data transfer is possible.
40 When used in synchronous modes, the Z8530 SCC supports several options
43 for clock sourcing and data encoding. Both the transmit and receive
44 clock sources can be set to be the external Transmit Clock (TRxC),
45 external Receive Clock (RTxC), the internal Baud Rate Generator (BRG),
46 or the output of the SCC's Digital Phase-Lock Loop (DPLL).
47 The Baud Rate Generator is a programmable divisor that derives a clock
50 frequency from the PCLK input signal to the SCC. A programmed baud rate
51 is translated into a 16-bit time constant that is stored in the SCC.
52 When using the BRG as a clock source the driver may answer a query of
53 its current speed with a value different from the one specified. This
54 is because baud rates translate into time constants in discrete steps,
55 and reverse translation shows the change. If an exact baud rate is
56 required that cannot be obtained with the BRG, an external clock source
57 must be selected.
58 Use of the DPLL option requires the selection of NRZI data encoding and
61 the setting of a non-zero value for the baud rate, because the DPLL
62 uses the BRG as its reference clock source.
63 A local loopback mode is available, primarily for use by the syn‐
66 cloop(1M) utility for testing purposes, and should not be confused with
67 SDLC loop mode, which is not supported on this interface. Also, an
68 auto-echo feature may be selected that causes all incoming data to be
69 routed to the transmit data line, allowing the port to act as the
70 remote end of a digital loop. Neither of these options should be
71 selected casually, or left in use when not needed.
72 The zsh driver keeps running totals of various hardware generated
75 events for each channel. These include numbers of packets and charac‐
76 ters sent and received, abort conditions detected by the receiver,
77 receive CRC errors, transmit underruns, receive overruns, input errors
78 and output errors, and message block allocation failures. Input errors
79 are logged whenever an incoming message must be discarded, such as when
80 an abort or CRC error is detected, a receive overrun occurs, or when no
81 message block is available to store incoming data. Output errors are
82 logged when the data must be discarded due to underruns, CTS drops dur‐
83 ing transmission, CTS timeouts, or excessive watchdog timeouts caused
84 by a cable break.
85
87 The zsh driver supports several ioctl() commands, including:
88 S_IOCGETMODE Return a struct scc_mode containing parameters cur‐
90 rently in use. These include the transmit and receive
91 clock sources, boolean loopback and NRZI mode flags
92 and the integer baud rate.
93 S_IOCSETMODE The argument is a struct scc_mode from which the SCC
96 channel will be programmed.
97 S_IOCGETSTATS Return a struct sl_stats containing the current totals
100 of hardware-generated events. These include numbers of
101 packets and characters sent and received by the
102 driver, aborts and CRC errors detected, transmit
103 underruns, and receive overruns.
104 S_IOCCLRSTATS Clear the hardware statistics for this channel.
107 S_IOCGETSPEED Returns the currently set baud rate as an integer.
110 This may not reflect the actual data transfer rate if
111 external clocks are used.
112 S_IOCGETMCTL Returns the current state of the CTS and DCD incoming
115 modem interface signals as an integer.
116 The following structures are used with zsh ioctl() commands:
120 struct scc_mode {
122 char sm_txclock; /* transmit clock sources */
123 char sm_rxclock; /* receive clock sources */
124 char sm_iflags; /* data and clock inversion flags (non-zsh) */
125 uchar_t sm_config; /* boolean configuration options */
126 int sm_baudrate; /* real baud rate */
127 int sm_retval; /* reason codes for ioctl failures */
128 };
129 struct sl_stats {
130 long ipack; /* input packets */
131 long opack; /* output packets */
132 long ichar; /* input bytes */
133 long ochar; /* output bytes */
134 long abort; /* abort received */
135 long crc; /* CRC error */
136 long cts; /* CTS timeouts */
137 long dcd; /* Carrier drops */
138 long overrun; /* receive overrun */
139 long underrun; /* transmit underrun */
140 long ierror; /* input error */
141 long oerror; /* output error */
142 long nobuffers; /* receive side memory allocation failure */
143 };
144
147 An open() will fail if a STREAMS message block cannot be allocated, or:
148 ENXIO The unit being opened does not exist.
150 EBUSY The device is in use by another serial protocol.
153 An ioctl() will fail if:
157 EINVAL An attempt was made to select an invalid clocking source.
159 EINVAL The baud rate specified for use with the baud rate generator
162 would translate to a null time constant in the SCC's regis‐
163 ters.
164
167 /dev/zsh[0-1],/dev/zsh
168 character-special devices
170 /usr/include/sys/ser_sync.h
173 header file specifying synchronous serial communication definitions
175
178 See attributes(5) for descriptions of the following attributes:
179 ┌─────────────────────────────┬─────────────────────────────┐
184 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
185 ├─────────────────────────────┼─────────────────────────────┤
186 │Architecture │x86 │
187 └─────────────────────────────┴─────────────────────────────┘
188
190 syncinit(1M), syncloop(1M), syncstat(1M), ioctl(2), open(2), read(2),
191 write(2), attributes(5), zs(7D)
192 Refer to the Zilog Z8530 SCC Serial Communications Controller Technical
195 Manual for details of the SCC's operation and capabilities.
196
198 zsh data open failed, no memory, rq=nnn
199 zsh clone open failed, no memory, rq=nnn
204 A kernel memory allocation failed for one of the private data
206 structures. The value of nnn is the address of the read queue
207 passed to open(2).
208 zsh_open: can't alloc message block
211 The open could not proceed because an initial STREAMS message block
213 could not be made available for incoming data.
214 zsh: clone device d must be attached before use!
217 An operation was attempted through a control path before that path
219 had been attached to a particular serial channel.
220 zshn: invalid operation for clone dev.
223 An inappropriate STREAMS message type was passed through a control
225 path. Only M_IOCTL and M_PROTO message types are permitted.
226 zshn: not initialized, can't send message
229 An M_DATA message was passed to the driver for a channel that had
231 not been programmed at least once since the driver was loaded. The
232 SCC's registers were in an unknown state. The S_IOCSETMODE ioctl
233 command performs the programming operation.
234 zshn: transmit hung
237 The transmitter was not successfully restarted after the watchdog
239 timer expired.
240SunOS 5.11 1 Jan 1997 zsh(7D)