


PROTO(3C)           UNIX Programmer's Manual            PROTO(3C)



NAME
     proto, pinit, psend, precv - multiplexed channels protocol

SYNOPSIS
     #include <proto.h>

     int pinit(channels)
     int channels;

     void precv(ptr, size)
     char *ptr;
     int size;

     int psend(channel, ptr, size)
     int channel;
     char *ptr;
     int size;

     void ptimeout(sig)
     int sig;

     struct Pchannel pconvs[];

     struct Pconfig pconfig;

DESCRIPTION
     These routines implement a machine independent driver for
     full duplex multiplexed multi-buffered channels with
     guaranteed delivery of ordered data via an 8 bit byte data
     stream.

CONFIGURATION
     The protocol driver assumes an 8 bit byte data stream
     described by the field _x_f_d_e_s_c in the user initialised struc-
     ture _p_c_o_n_f_i_g.  The user must also supply the addresses of
     routines with which to write packets to the data stream, and
     to receive unpacked data from the stream, and control infor-
     mation from the stream.  These are initialised in the fields
     _x_f_u_n_c_p, _r_f_u_n_c_p and _r_c_f_u_n_c_p.

     The routine *_x_f_u_n_c_p will be invoked with arguments as for
     the _w_r_i_t_e(2) system call.  The first argument will be
     _x_f_d_e_s_c, and the next two a pointer to a packet, and its
     size.

     The routines *_r_f_u_n_c_p and *_r_c_f_u_n_c_p are invoked with three
     arguments, the first a channel number, and the next two a
     pointer to data from that channel, and its size.  If *_r_f_u_n_c_p
     returns a non-zero result, the packet will be negatively
     acknowledged, causing a later re-transmission.  The routine
     *_r_c_f_u_n_c_p will only be called with data from a control
     packet.  This data is generated by placing a (non-zero) byte



Printed 6/21/83                                                 1






PROTO(3C)           UNIX Programmer's Manual            PROTO(3C)



     in the _p_c_o_n_f_i_g field _c_d_a_t_a during an invocation of the rou-
     tine *_r_f_u_n_c_p.  The control byte will be returned to the
     remote channel in the acknowledgement packet, there to be
     delivered by an invocation of *_r_c_f_u_n_c_p.  Caveat: control
     data can be delivered asynchronously to stream data, and its
     delivery is uncertain.  It is intended that control data be
     used primarily as an aid to flow control.

PROTOCOL
     The protocol uses packets with a 2 byte header containing
     sequence number (modulo SEQMOD), channel number, control
     flag, and data size.  The data part of a packet may not be
     larger than MAXPKTDSIZE. The trailer contains a CRC-16 code
     in 2 bytes.  Each channel is multi-buffered, the number of
     buffers being defined by the parameter NPCBUFS.

     Correctly received packets in sequence are acknowledged with
     a control packet containing an ACK, out of sequence packets
     generate a control packet containing a NAK , which will
     cause the retransmission in sequence of all un-acknowledged
     packets.

     Unacknowledged packets are retransmitted after a timeout
     specified by the _p_c_o_n_f_i_g field _x_t_i_m_o in the same units as
     the field _t_s_c_a_n which is the period of a timeout scan.
     Incomplete receive packets are discarded after a timeout
     specified by the field _r_t_i_m_o.  These fields, if zero, will
     be initialised to a default setting appropriate for a 1200
     baud RS-232 data stream.  If other data stream speeds are
     used, the timeout fields should be preset as follows:-

     If _s_p_e_e_d is in bytes per _t_s_c_a_n unit, then _x_t_i_m_o should be
     set to:
     max(3,(NCHAN*NPCBUFS*sizeof(struct Packet)+speed-1)/speed)
     and _r_t_i_m_o to:
          max(2,(sizeof(struct rPacket)+speed-1)/speed)

INITIALISATION
     _P_i_n_i_t initialises the transmitter and receiver data.
     Transmitter structures must be declared by the caller in an
     array struct Pchannelpconvs[NCHAN]; and the size NCHAN
     passed as first argument to _p_i_n_i_t.  NCHAN must not be
     greater than MAXPCHAN. _P_i_n_i_t also enables SIGALRM to call
     the timeout handler _p_t_i_m_e_o_u_t.  _P_i_n_i_t returns a non-zero
     result if an initialisation inconsistency is detected.

USAGE
     _P_r_e_c_v is called with a pointer to data read from the data
     stream (e.g. via a _r_e_a_d(2) system call), and its size.  It
     will collect a packet, or acknowledgement, from the incoming
     data, and invoke *_r_f_u_n_c_p, (or *_r_c_f_u_n_c_p) when a good packet
     has been identified, calling *_x_f_u_n_c_p to send



Printed 6/21/83                                                 2






PROTO(3C)           UNIX Programmer's Manual            PROTO(3C)



     acknowledgements.

     _P_s_e_n_d is called with three arguments, the first a channel
     number, and the next two a pointer to data destined for that
     channel, and its size.  It returns -1 if the channel is
     blocked and it cannot accept the data, otherwise it returns
     the value returned by *_x_f_u_n_c_p.

     In each _P_c_h_a_n_n_e_l structure a field _f_r_e_e_p_k_t_s is set to the
     number of free packet buffers available for the channel;
     there is also a spare byte, _u_s_e_r.

DEFAULTS
     MAXPCHAN     8  (3 bits in header)
     SEQMOD       8  (3 bits in header)
     NPCBUFS      2  (maximum SEQMOD/2)
     MAXPKTDSIZE  32 (limited by buffering in system)

STATISTICS
     Optional statistics are available by recompiling the source
     with the C compiler flag -D_P_S_T_A_T_I_S_T_I_C_S.  This declares an
     array _p_s_t_a_t_s of type _s_t_r_u_c_t _P_s_t_a_t_i_s_t_i_c_s of size PS_NSTATS.
     Additional descriptive strings are initialised by the flag
     -D_P_S_T_A_T_S_D_E_S_C.  A particular statistic i may then be obtained
     on standard output by:
      printf("%s: %ld", pstats[i].descp, (long)pstats[i].count);

SEE ALSO
     cc(1), alarm(2), read(2), signal(2), write(2).


























Printed 6/21/83                                                 3



