zsh - On-board serial HDLC/SDLC interface


     #include <fcntl.h>

     open(/dev/zshn, mode );

     open(/dev/zsh, mode );


     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  stan-
     dalone  driver,  but  instead depends upon the zs module for
     the hardware support required by all  on-board  serial  dev-
     ices. 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) sys-
     tem 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  out-
     put 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

     A local loopback mode is available, primarily for use by the
     syncloop(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 digi-
     tal loop. Neither of these options should be selected  casu-
     ally, or left in use when not needed.

     The zsh driver keeps running totals of various hardware gen-
     erated  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,
     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  during  transmis-
     sion, CTS timeouts, or excessive watchdog timeouts caused by
     a cable break.


     The zsh driver supports several ioctl() commands, including:

           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.

           The argument is a struct scc_mode from which  the  SCC
           channel will be programmed.

           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.

           Clear the hardware statistics for this channel.

           Returns the currently set baud  rate  as  an  integer.
           This  may not reflect the actual data transfer rate if
           external clocks are used.

           Returns the current state of the CTS and DCD  incoming
           modem interface signals as an integer.

     The following structures are used with zsh ioctl() 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 */


     An open() will fail if a STREAMS  message  block  cannot  be
     allocated, or:

                The unit being opened does not exist.

          EBUSY The device is in use by another serial protocol.

     An ioctl() will fail if:

                An attempt was made to select an invalid clocking

                The baud rate specified for  use  with  the  baud
                rate  generator  would  translate  to a null time
                constant in the SCC's registers.


           character-special devices

           header file specifying synchronous  serial  communica-
           tion definitions


     See attributes(5) for descriptions of the  following  attri-

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Architecture                | x86                         |


     syncinit(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  Con-
     troller  Technical Manual for details of the SCC's operation
     and capabilities.


     zsh 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

     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 mes-
           sage types are permitted.

     zshn: not initialized, can't send message
           An M_DATA message was passed to the driver for a chan-
           nel  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 per-
           forms the programming operation.

     zshn: transmit hung
           The transmitter was not successfully  restarted  after
           the watchdog timer expired.

Man(1) output converted with man2html