+.\"$Header: debug.nr,v 1.4 88/12/06 16:05:36 nhall Exp $
+.\"$Source: /usr/argo/doc/kernel/RCS/debug.nr,v $
+.\"
+.\" Program names should be in italics
+.\"
+.NC "Debugging, Testing, and Statistics"
+.sh 1 "Introduction"
+.pp
+This section describes the methods used
+to test and debug the ARGO kernel.
+Three facilities are used in combination:
+debug options,
+simple statistics gathering,
+and
+protocol event tracing.
+Many of the debug options
+simply cause information to be printed on the console, but
+several of these options cause
+TP to behave pathologically
+so that errors are be introduced in desirable ways.
+.pp
+TP and CLNP keep simple statistics.
+These statistics include such things as the total
+number of PDUs that are sent and received,
+a count of various types of errors
+that can be encountered when parsing an incoming PDU,
+and the average and standard deviation of round trip times for
+transport PDUs.
+These statistics are useful for debugging.
+For example,
+if an incoming CC TPDU is rejected because one of the optional
+parameters is faulty, this are noted in the statistics.
+The statistics are kept on a system-wide basis rather than
+on a per-connection basis.
+They can be printed or cleared by user-level utility programs.
+.pp
+The tracing facility allows selective tracing of events.
+Events are grouped into categories relating to different
+functions of TP.
+For example, it is possible to
+trace only the events that pertain to acknowledgments.
+.pp
+At run time the debugging and tracing options can
+be set and cleared by privileged utility programs.
+Each of these facilities is described in more
+detail below.
+.sh 1 "Debugging"
+.pp
+Most of the debugging options
+print messages on the console.
+Kernel printing is done by busy-waiting at high priority,
+so debugging options should be used very sparingly.
+A sample of the code is:
+.(b
+.nf
+\fC
+IFDEBUG(D_TPINPUT)
+ printf("tp_input m 0x%x tpdu_len 0x%x\n", m, tpdu_len);
+ENDDEBUG
+\fR
+.fi
+.)b
+.sp 1
+.lp
+IFDEBUG and ENDDEBUG are macros that are defined in one of two ways.
+If the system is configured with the ARGO_DEBUG
+option, an array
+\fCargo_debug[128]\fR
+is declared, and
+IFDEBUG and ENDDEBUG are defined thus:
+.(b
+.nf
+\fC
+#define IFDEBUG(option) if(argo_debug[option]) {
+#define ENDDEBUG ; }
+\fR
+.fi
+.)b
+.lp
+If the system is configured without the ARGO_DEBUG option, these
+two macros resolve to the C comment delimiters, \fC/*\fR and \fC*/\fR,
+causing all the debugging code lying between the macros
+to be elided.
+.pp
+TP, CLNP, and CONS debugging can be enabled independently.
+All debugging requires that the code be compiled with the
+option ARGO_DEBUG.
+The \fIconfig(8)\fR option CLNP_DEBUG will include debugging printfs for CLNP.
+TP_DEBUG has the same effect for TP.
+.pp
+The array elements of \fCargo_debug[]\fR are set by
+the utility program
+\fIbark\fR,
+which reads and writes
+\fC/dev/kmem\fIN\fR.
+See the manual page \fIbark(8)\fR.
+.pp
+Several debugging options cause TP to behave pathologically,
+for the purpose of reproducing difficult-to-reproduce
+error conditions that the protocol must correct.
+For example, the
+\fID_DROP\fR, or \fIbark -on T.drop\fR
+option causes
+\fItp_input()\fR
+to discard TPDUs on a pseudo-random basis.
+These will be described below.
+.sh 1 "Statistics"
+.pp
+.sh 2 "CLNP Statistics"
+.pp
+CLNP keeps a set of statistics related to its operation.
+Statistics include such things as NPDUs sent, received, and dropped.
+These statistics are stored in the global structure \fIclnp_stat\fR.
+The utility program \fInetstat(8)\fR may be used to print these statistics.
+.sh 2 "TP Statistics"
+.pp
+TP keeps a set of running counts of certain events.
+The statistics include such things as the numbers
+of each type of TPDU sent and received, TPDUs dropped,
+and the numbers of occurrences of certain types of errors.
+The statistics are stored in the global structure \fItp_stat\fR.
+The utility programs
+\fItpstat\fR and
+\fItpmon\fR
+read \fC/dev/kmem\fIN\fR
+and prints the contents of the statistics structure
+in a human-readable form.
+\fITpstat\fR prints the statistics on any ascii screen or printer.
+\fITpmon\fR uses the \fIcurses\fR library and assumes that is has
+a screen or window of size 53(long) X 80(wide), and it updates the
+screen every 30 seconds.
+.pp
+\fITpstat\fR and \fItpmon\fR can be used to clear the statistics (set them
+all to zero); the \fB-c\fR option causes the statistics to be cleared.
+.pp
+Statistics are observed using \fItpstat(8)\fR
+to clear statistics before a test, and to print
+the statistics after the test.
+See the manual pages \fItpstat(8)\fR and \fItpmon(8)\fR.
+.sh 1 "Tracing"
+.pp
+.sh 2 "CLNP Tracing"
+.pp
+CLNP does not support event tracing.
+.sh 2 "TP Tracing"
+.pp
+The tracing facility consists of a circular buffer (an array)
+of structures that are written by the kernel at various times,
+and a utility program that reads \fC/dev/kmem\fIN\fR
+to interpret the contents of the buffer.
+The trace structure is a union of the structures that
+will be interpreted by the utility program.
+A trace event consists of a call to the trace routine \fItpTrace\fR
+with a set of arguments containing the information relevant to the
+event being traced.
+The procedure tpTrace is actually called through a macro \fItptrace\fR.
+For example,
+.(b
+.nf
+\fC
+IFTRACE(D_INPUT)
+ tptrace(TPPTtpduin, h->tpdu_type, h, h->tpdu_li+1, 0, 0);
+ENDTRACE
+\fR
+.fi
+.)b
+.pp
+The tracing macros are defined in the same manner as the
+debugging macros:
+.(b
+.nf
+\fC
+#define IFTRACE(option) if(tp_traceflags[option]) {
+#define ENDTRACE }
+\fR
+.fi
+.)b
+.lp
+If the kernel is configured with the option TPPT, these macros
+are defined as shown above, but if the TPPT option is not
+used, these macros become C-style comment delimiters.
+.pp
+The tracing procedure copies \fIh->tpdu_li + 1\fR bytes beginning at
+location \fIh\fR into a trace structure in the circular buffer.
+The utility program \fItppt\fR
+reads the trace structure,
+interprets the data as a TPDU header,
+and prints the header in hexadecimal form, with a banner identifying
+the event as an incoming TPDU:
+.(b
+.nf
+\fC
+1a: Ref 22 arg 14(0xe), @ 91990 : 0000.453125 tpdu
+INPUT total len 22
+HDRLEN: 21+1 CR_TPDU_type cdt 0(0x0) dref 0x0
+ + 0: 0x15 0xe0 0x00 0x00 4: 0x00 0x03 0x00 0xc1
+ + 8: 0x06 0x74 0x70 0x70 12: 0x69 0x6e 0x67 0xc2
+ +16: 0x02 0x00 0x07 0xc0 20: 0x01 0x08 0x00 0x00
+
+\fR
+.fi
+.)b
+.pp
+In addition to the data copied from the arguments to tpTrace(),
+each trace structure contains
+a time stamp and an event sequence number, and in many cases, the
+connection reference to which the traced event applies.
+The utility program \fItppt\fR is be used to turn on and off the
+tracing options.
+.pp
+This facility can be used for debugging the source
+code as well as for studying the behavior of the protocol.
+For example, by adding the appropriate trace events,
+it is possible to "see" the resequencing function of TP
+working when a debug option is used to cause
+TPDUs to be dropped occasionally.
+.pp
+See the manual page \fItppt(8)\fR.
+.sh 1 "Testing"
+.pp
+.sh 2 "CLNP Testing"
+.pp
+CLNP was tested in two rather different ways.
+The first method of testing used the
+raw CLNP interface with the program \fIclnptest\fR.
+\fIclnptest\fR allows a user to send or receive CLNP NSDUs.
+With \fIclnptest\fR, a user can send CLNP NSDUs with various
+combinations of options and observe the result.
+.pp
+The second method of testing CLNP was to have TP use CLNP as its network
+layer protocol.
+This method provides a good stress test for CLNP.
+Unfortunately, TP generally calls CLNP in the same manner, so that not all
+of the CLNP options are exercised.
+.sh 3 "Clnptest"
+.pp
+The program \fIclnptest\fR can be invoked as either
+a reader or as a writer:
+.(b
+\fC
+clnptest <options>
+\fR
+.)b
+The \fI-r\fR option invokes \fIclnptest\fR as a reader, the
+\fI-w\fR option invokes it as a writer.
+Other options allow the user to indicate the destination, number of NSDUs,
+size of NSDUs,
+and NSDUs options.
+See \fIclnptest(8)\fR for more information.
+.pp
+\fIclnptest\fR is normally used in the following manner.
+On one machine, invoke \fIclnptest\fR as a reader:
+.(b
+\fC
+clnptest -r
+\fR
+.)b
+On a different machine, transmit an NSDU.
+For example, to test the source route function, one invokes:
+.(b
+\fC
+clnptest -w -h a -oR "b, c, d"
+\fR
+.)b
+This sends an NSDU to host 'a', source routing it via
+hosts 'b', 'c', and 'd'.
+.sh 3 "The Troll"
+In order to test CLNP reassembly certain errors must be generated.
+The mechanism used has two parts,
+the user program \fIclnptroll\fR, which enables and disables
+the generation of these errors, and the
+kernel resident error-creation routines.
+.pp
+Troll options allow one to duplicate an NSDU with a specified frequency.
+The kernel must be compiled with the \fIconfig\fR option \fITROLL\fR
+in order to include troll code.
+See \fIclnptroll(8)\fR for more information.
+.sh 3 "Debugging CLNP"
+.pp
+The following sections describe the \fIbark\fR options
+appropriate for testing parts of CLNP.
+Refer to \fIbark(8)\fR for more information about debugging
+using \fIbark\fR..
+.sh 4 "Sending NSDUs"
+.pp
+Turning on the \fIbark\fR
+option \fIC.output\fR causes information to be
+printed whenever an NSDU is transmitted.
+Translation of NSAP addresses to SNPA can be monitored by turning on
+the \fIC.un\fR, or \fIC.lan\fR options.
+Parts of outgoing NSDUs can be dumped when the \fIC.dumpout\fR
+option is on.
+Routing activity can be watched by turning on \fIC.route\fR and \fIC.iso\fR.
+Information about CLNP option processing is available with \fIC.options\fR.
+.sh 4 "Forwarding NSDUs"
+.pp
+The \fIforward\fR switch will cause debugging information to be displayed
+whenever NSDUs are forwarded.
+.sh 4 "Receiving NSDUs"
+.pp
+Information is displayed about incoming NSDUs when the \fIC.input\fR
+option is enabled.
+A portion of incoming NSDUs can be dumped by turning on the
+\fIC.dumpin\fR option.
+.sh 4 "Fragmentation and Reassembly"
+.pp
+The options \fIC.frag\fR and \fIC.reass\fR turn on debugging for the
+CLNP fragmentation and reassembly functions.
+.sh 2 "TP Testing"
+.pp
+Five services were used for most of the testing:
+the \fIdiscard\fR service,
+the \fIecho\fR service,
+the \fIremote login\fR service,
+the \fIremote shell\fR service,
+and
+the \fIsimple file transfer\fR service.\**
+.(f
+\** In fact, ancestors of these services were used for testing the
+ARGO transport implementation during development.
+These programs in their original forms were very cumbersome to use;
+consequently they evolved to become the services described here.
+.)f
+Each service consists of a daemon process or server that listens
+on a well-known transport selector (which is listed in the
+ARGO directory service), and an active process that contacts the
+server.
+Four of these services,
+discard, echo, remote login, and remote shell,
+are supported by the
+\fIisod\fR suite of daemons, which is a
+version of the \fIinetd\fR programs that uses
+the ISO protocol suite.
+.sh 3 "The Discard Service"
+The discard server listens on the transport selector
+registered in the ARGO directory service for the application
+"discard".
+The server accepts incoming connection requests,
+receives TSDUs, and throws away the TSDUs.
+It never initiates a disconnect, but expects its peer
+to disconnect the transport connection.
+.PP
+The program \fItpdiscard\fR connects to the
+discard server.
+The transport service and protocol options it uses are those
+indicated in the ARGO directory service.
+By changing the directory service entry for the
+discard service, each of the transport service options and
+protocol options can be demonstrated.
+See the manual pages
+\fItpdiscard(8)\fR,
+\fItp(4p)\fR,
+and
+\fIisodir(5)\fR
+for more information.
+.sh 3 "The Echo Service"
+The echo server listens on the transport selector
+registered in the ARGO directory service for the application
+"echo".
+The server accepts incoming connection requests,
+receives TSDUs, and returns the TSDUs to the sender.
+It never initiates a disconnect, but expects its peer
+to disconnect the transport connection.
+.pp
+The
+program \fItpping\fR connects to the
+echo server.
+The transport service and protocol options it uses are those
+indicated in the ARGO directory service.
+By changing the directory service entry for the
+echo service, each of the transport service options and
+protocol options can be demonstrated.
+See the manual pages
+\fItpping(8)\fR,
+\fItp(4p)\fR,
+and
+\fIisodir(5)\fR
+for more information.
+.sh 3 "The Remote Login Service"
+The remote login server listens on the transport selector
+registered in the ARGO directory service for the application
+"login".
+The server accepts incoming connection requests,
+implements the BSD remote login protocol, checks permissions using
+the \fC~/.rhosts\fR, and \fC/etc/passwd\fR files, and
+uses the ARGO directory service to discover name-to-NSAP-address
+mappings.
+If the remote user is authorized to log in to the end system on which
+the server runs, a login is started.
+.pp
+The program \fIrlogin.iso\fR connects to the remote login server.
+The transport service and protocol options it uses are those
+indicated in the ARGO directory service.
+By changing the directory service entry for the
+login service, each of the transport service options and
+protocol options can be demonstrated.
+See the manual pages
+\fIrlogin.iso(8)\fR,
+\fItp(4p)\fR,
+and
+\fIisodir(5)\fR
+for more information.
+.sh 3 "The Remote Shell Service"
+The remote shell server listens on the transport selector
+registered in the ARGO directory service for the application
+"shell".
+The server accepts incoming connection requests,
+implements the BSD remote command authorization protocol,
+checks permissions using
+the \fC~/.rhosts\fR, and \fC/etc/passwd\fR files, and
+uses the ARGO directory service to discover name-to-NSAP-address
+mappings.
+If the remote user is authorized to execute a shell on
+the end system on which
+the server runs, a shell is started.
+.pp
+The program \fIrcp.iso\fR connects to the remote shell server to
+effect a remote copy.
+The transport service and protocol options it uses are those
+indicated in the ARGO directory service.
+By changing the directory service entry for the
+shell service, each of the transport service options and
+protocol options can be demonstrated.
+See the manual pages
+\fIrcp.iso(8)\fR,
+\fItp(4p)\fR,
+and
+\fIisodir(5)\fR
+for more information.
+.sh 3 "The Simple File Transfer Service"
+.pp
+The last service consists of a pair of programs,
+\fItpfileget\fR and
+\fItpfileput\fR,
+which cooperate to transfer one file.
+The passive program, \fItpfileget\fR,
+listens on the transport selector registered in the ARGO directory service
+to support the application named "tptestsel".
+The sending program, \fItpfileput\fR,
+connects to the passive program, transfers in one TSDU
+the file named on the \fItpfileput\fR command line, and waits for the
+passive end to close the connection.
+\fITpfileget\fR
+opens a file of the name given on its command line,
+accepts one connection request, receives
+one TSDU, writes the contents of that TSDU to the opened file,
+and when it receives the end-of-TSDU indication,
+\fItpfileget\fR closes the transport connection.
+The transport service options and protocol options used by
+\fItpfileput\fR are determined by the ARGO directory service
+record that describes the applicaition "tptestsel".
+See the manual pages
+\fItpfileget(8)\fR,
+\fItp(4p)\fR,
+and
+\fIisodir(5)\fR
+for more information.
+.sh 3 "Internal TP Testing"
+.pp
+The methods used to test each of the various functions
+of TP are described in this section.
+One or more of the services described above were used, while
+the TP activity was observed with tracing or debugging or both.
+The statistics were cleared before each test and inspected
+after each test.
+Each test can be run with different protocol and service options,
+by changing the transport parameters in records
+in the ARGO directory service file.
+See the manual pages
+\fItpstat(8)\fR,
+\fItpmon(8)\fR,
+\fItppt(8)\fR,
+\fIbark(8)\fR,
+\fItp(4p)\fR,
+and
+\fIisodir(5)\fR
+for more information.
+.sh 4 "Normal and Expedited Data Transfer:"
+.pp
+TSDUs are
+distinguished by the presence or absence of the
+EOTSDU bit in the \fIflags\fR parameter of the
+\fIsendv()\fR system call.
+The data of a TSDU are copied into chains of \fImbufs\fR
+in the kernel so that the end of a TSDU lies in an mbuf
+with the \fIm_act\fR field non-zero.
+The end of a TSDU never lies in the middle of an
+mbuf.
+This is true on the receiving side as well.
+On output, the segmenting function,
+the function that copies user data into mbuf chains
+reorganizes mbuf chains into TPDUs,
+is observed using several debug options
+and trace options
+in the routines \fIsosend()\fR
+and \fItp_sbsend()\fR.
+On input, the reassembling mechanism
+is observed in the routine \fItp_stash()\fR.
+The debug options
+\fBT.ndata\fR,
+\fBT.sb\fR, and
+\fBT.xpd\fR
+print information
+pertinent to this function.
+.pp
+Expedited data complicates the matter of segmenting
+because markers must be kept in the chains of outgoing
+TPDUs to indicate the precedence of expedited data TPDUs
+over normal data TPDUs.
+The pertinent trace options are \fBT.sb\fR and \fBT.ndata\fR.
+With the trace and (or) debugging options on,
+and with \fItpdiscard\fR running, one can observe the segmentation
+and reassembly of TPDUs.
+.pp
+Using the file transfer programs to transfer a file,
+then transferring it back with \fIrcp\fR (the TCP version) if necessary, and
+using
+\fIdiff\fR, one can see that data are transferred correctly.
+The \fBT.input\fR trace option creates a readable hexadecimal dump of incoming TPDUs.
+The
+\fBT.emit\fR
+trace option creates the same sort of dump for outgoing
+TPDUs in \fItp_emit()\fR.
+Sequencing
+can be observed by using the
+\fBT.ndata\fR
+and
+\fBT.input\fR
+or
+\fBT.emit\fR
+trace options
+to see the sequence numbers assigned to TPDUs.
+.pp
+The
+\fBT.drop\fR
+debug option causes \fItp_input()\fR
+to throw away occasional TPDUs.
+(The formula for determining when to discard a TPDU
+is ad hoc and simplistic. It causes TPDUs to be
+discarded frequently but not so frequently that the
+receiving side has no chance to recover.)
+With tracing on and the file transfer programs running,
+resequencing can be observed
+and the correctness of the transferred data
+can be verified with \fIdiff(1)\fR.
+.pp
+The use of both normal and extended formats
+can be observed with the \fBT.input\fR and \fBT.emit\fR trace options.
+.pp
+The following statistics are of interest:
+.(b
+.nf
+\fIn\fR connections used extended format
+\fIn\fR connections allowed transport expedited data
+\fIn\fR connections turned off checksumming
+\fIn\fR connections dropped due to retrans limit
+\fIn\fR EOT bits on incoming TPDUs
+\fIn\fR EOT bits on outgoing TPDUs
+\fIn\fR XPD marks discarded
+\fIn\fR XPD stopped data flow \fIm\fR times
+\fIn\fR DTs out of order
+\fIn\fR DTs not in window
+\fIn\fR duplicate DTs
+\fIn\fR XPDs not in window
+\fIn\fR XPDs w/o credit to stash
+\fIn\fR DT (sent)
+\fIn\fR DT (received)
+\fIn\fR DT (retransmitted)
+\fIn\fR XPD (sent)
+\fIn\fR XPD (received)
+\fIn\fR random DTs dropped
+.fi
+.)b
+.sh 4 "Checksumming, use and non-use:"
+.pp
+The checksum generation and checking
+routines were first written and debugged as user-level
+routines before they were modified for kernel use.
+The kernel routines may be observed with the
+\fBT.chksum\fR
+debug option.
+Various sizes of mbufs can be created by creative use of the
+ARGO directory service, particularly by changing the value of the
+attribute \fItp.tpdusize\fR.
+There is no trace option for checksumming.
+Checksumming has been used with transfers to and from at least
+one other TP implementation.
+.pp
+The statistics that are pertinent to checksumming are:
+.(b
+.nf
+\fIn\fR connections turned off checksumming
+\fIn\fR invalid checksums
+.fi
+.)b
+.sh 4 "Acknowledgment:"
+.pp
+Acknowledgment can be observed by using the
+debug and trace options
+\fBT.aks\fR,
+\fBT.akr\fR,
+\fBT.input\fR,
+\fBT.emit\fR,
+and
+\fBT.driver\fR.
+The transport driver (finite state machine) and the routine
+\fItp_goodack()\fR dump information appropriate to acknowledgments.
+If the \fBT.ndata\fR, and \fBT.emit\fR or \fBT.input\fR trace options are used
+along with the \fBT.aks\fR and \fBT.akr\fR trace options,
+a complete picture of the data transfer and acknowledgment
+activity can be created.
+The acknowledgments for expedited data are traced with
+the
+\fBT.xpd\fR
+trace option.
+The routine \fItp_goodXack()\fR and the finite state
+machine dump information when the
+\fBT.xpd\fR
+debug and trace options are used.
+To cause expedited data to be generated,
+the -e or -E option on the discard programs or the file
+transfer programs are used.
+To observe the different acknowledgment strategies,
+the protocol options were changed in the ARGO directory service.
+.pp
+The pertinent statistics are:
+.(b
+.nf
+\fIn\fR AK (received)
+\fIn\fR AK (sent)
+ACK reasons:
+\fIn\fR not acked immediately
+\fIn\fR strategy==each
+\fIn\fR strategy==fullwindow
+\fIn\fR duplicate DT
+\fIn\fR EOTSDU
+\fIn\fR reordered
+\fIn\fR user rcvd
+\fIn\fR fcc reqd
+.fi
+.)b
+.pp
+The smoothed average round trip time is kept
+for outgoing TPDUs for each transport connection
+and for the entire TP entity.
+The time each TPDU is transmitted is recorded, and when an acknowledgment
+arrives, the round trip time is computed for the lowest
+sequence number that this AK TPDU acknowledges.
+The computation of round trip times can be observed
+in a trace with the
+\fBT.rtt\fR
+option.
+.pp
+In addition to average round trip times, the kernel
+maintains the standard deviation of the round trip times.
+This statistic is kept for each connection and for the entire
+TP entity.
+In fact, four such sets of statistics are kept for the TP entity:
+.np
+for traffic not on a public data network (PDN) and on the same network as this end system,
+.np
+for traffic not on a public data network (PDN) and on not the same network as this end system,
+.np
+for traffic on a public data network (PDN) and on the same network as this end system,
+and
+.np
+for traffic on a public data network (PDN) and not on the same network as this end system.
+The determination of whether traffic is on the same network as this end system
+is based on the "network portion" of the peer's NSAP-address.
+For more information about this, see the section of this document titled
+\fB"Network Layer Routing"\fR.
+.pp
+The smoothed average round trip time statistics for a given
+can be observed with the -t option to
+\fItpstat(8)\fR.
+The global round trip statistics can be observed with the -s option to
+\fItpmon(8)\fR.
+.sh 4 "Flow Control:"
+.pp
+Flow control activity is the transfer of credit information
+from end to end and the proper use of that information.
+To see that it works properly, one must observe three
+things:
+the receiving window must shut down and reopen,
+the sender must transmit enough TPDUs to fill the receiver's window
+but no more, and the receiver must renege previously advertised credit.
+These three behaviors have been observed as follows.
+.pp
+Tracing with the
+\fBT.ndata\fR,
+\fBT.aks, \fR
+\fBT.akr, \fR
+\fBT.emit\fR
+and
+\fBT.input\fR
+trace options
+are used.
+The program \fItpdiscard\fR or a simple file transfer
+is run with various window
+and maximum TPDU sizes, various acknoledgment strategies, and
+various retransmission strategies,
+and the activity is observed with the trace.
+The debug option
+\fBT.reneg\fR
+must be used to fake a reneging of credit, since
+the ARGO transport entity does not renege its advertised credit
+under normal operation.
+At the beginning of a connection a closed window may almost always
+be observed.
+The receiving user process may be stopped
+to force a window to shut down.
+The interesting statistics are
+.(b
+.nf
+\fIn\fR times local cdt reneged (receiving)
+\fIn\fR foreign window closed (sending)
+\fIn\fR faked reneging of cdt
+\fIn\fR DT TPDUs (sent)
+\fIn\fR DT TPDUs (received)
+\fIn\fR AK TPDUs (sent)
+\fIn\fR AK TPDUs (received)
+ACK reasons:
+\fIn\fR not acked immediately
+\fIn\fR strategy==each
+\fIn\fR strategy==fullwindow
+\fIn\fR duplicate DT
+\fIn\fR EOTSDU
+\fIn\fR reordered
+\fIn\fR user rcvd
+\fIn\fR fcc reqd
+.fi
+.)b
+.sh 4 "Retransmission and retention until acknowledgment:"
+.pp
+To observe that the sender retains TPDUs until they are
+acknowledged, one needs only to use the
+\fBT.drop\fR
+debug option to cause TPDUs to be dropped by the receiving side.
+They are then retransmitted by the sender
+and finally dropped when the acknowledgment arrives.
+That the buffers used to hold retained TPDUs are freed
+can be observed by
+running \fInetstat(8)\fR with the -m option
+on a quiescent system to observe the number of mbufs in use,
+then
+running a test with the
+\fBT.drop\fR debug option on to cause retransmission,
+and
+finally
+running netstat -m again after the test is over,
+to see that all the mbufs have been freed by TP.
+The actual retransmission activity can be observed in a trace
+with the
+\fBT.ndata, \fR
+\fBT.emit\fR and
+\fBT.input\fR trace options.
+The retransmission strategy to be used is controlled by the
+ARGO directory service.
+The statistics
+.(b
+.nf
+\fIn\fR DT (retransmissions)
+\fIn\fR XPD (retransmissions)
+\fIn\fR CR (retransmissions)
+\fIn\fR CC (retransmissions)
+\fIn\fR DR (retransmissions)
+.fi
+.)b
+.lp
+indicate the number of retransmissions that actually occurred.
+.sh 4 "Timers:"
+.pp
+The debug and trace option
+\fBT.timer\fR
+dumps information about the timers as they are set,
+as they are cancelled, and as they expire.
+The statistics
+.(b
+.nf
+\fIn\fR ticks
+\fIn\fR timers set
+\fIn\fR timers expired
+\fIn\fR timers cancelled
+\fIn\fR inactive timers cancelled
+\fIn\fR connections dropped due to retrans limit
+\fIn\fR CCs sent to zero dref
+.fi
+.)b
+.lp
+are printed for both the E-type timers and for the C-type timers.
+The effect of timers can be seen by observing retransmissions.
+Two simple ways to force retransmissions are:
+.np
+to use the \fBT.zdref\fR debug option,
+which causes CCs to contain a zero destination reference,
+so that connection establishment will time out, and
+.np
+to attempt to open a connection to a transport selector on which
+no process is listening.
+Either of these actions, along with the
+\fBT.connect\fR
+trace or debug option will permit
+observation of the timeout facilities.
+.sh 4 "TPDU creation and parsing:"
+.pp
+TPDUs are created for output in
+\fItp_emit()\fR.
+The
+\fBT.emit\fR
+trace
+option dumps TPDUs as they are transmitted.
+\fITp_input()\fR parses TPDUs on input.
+The
+\fBT.input\fR
+trace
+option dumps TPDUs as they are received.
+The debug options \fBT.emit\fR and \fBT.input\fR dump a lot of excess information
+to the console, and are used primarily for debugging
+extremely pathological behavior.
+.pp
+By tracing the execution of
+\fItpdiscard\fR or a simple file transfer,
+with a variety protocol and service options,
+using the
+\fBT.connect,\fR
+\fBT.emit,\fR
+\fBT.input,\fR
+\fBT.ndata,\fR
+\fBT.aks,\fR
+\fBT.akr,\fR
+and
+\fBT.xpd\fR
+options,
+one can verify the correct placement of TPDU options
+on all types of TPDUs.
+The interesting statistics are
+.(b
+.nf
+\fIn\fR variable parameters ignored
+\fIn\fR invalid parameter codes
+\fIn\fR invalid parameter values
+\fIn\fR invalid dutypes
+\fIn\fR invalid negotiation failures
+\fIn\fR invalid destinagion referencess
+\fIn\fR invalid suffix parameters
+\fIn\fR invalid checksums
+\fIn\fR connections used extended format
+\fIn\fR connections allowed transport XPD
+\fIn\fR connections turned off checksumming
+\fIn\fR TP 4 connections
+\fIn\fR TP 0 connections
+.fi
+.)b
+.sh 4 "Separation and concatenation:"
+.pp
+Concatenation is not supported by this implementation.
+Separation is supported, however, and to test separation,
+some sort of concatenated TPDUs had to be created.
+The code for this is no longer supported.
+After testing locally with some temporary code to create concatenated
+TPDUs,
+the ARGO transport implementation was tested with another transport
+implementation that does generate concatenated TPDUs.
+The interesting statistics are:
+.(b
+.nf
+\fIn\fR concatenated TPDUs
+\fIn\fR TPDUs input
+.fi
+.)b
+.sh 4 "Length limits for TPDUs:"
+.pp
+Some TPDUs may take user data:
+the CR, CC, DR, DT, and XPD.
+All of these but the DT TPDU have limits to the amount
+of data they may carry.
+The limits are enforced for CR, CC, and DR TPDUs by
+\fItp_ctloutput()\fR,
+the routine that accepts data from the user.
+The limit for XPD TPDUs is enforced by
+\fItp_usrreq()\fR, which accepts expedited
+data from the user.
+To test the effectiveness of the checks on output, one may attempt
+to send expedited data with amounts larger than the limit (16 bytes).
+.pp
+On input the limits are checked in
+\fItp_input()\fR.
+To test the effectiveness of the checks on input, it was necessary
+to create an illegally large TPDU.
+The
+\fBT.badsize\fR
+debug option
+does this - it will turn a legitimate
+XPD TPDU into a XPD TPDU with 18 bytes
+of expedited data.
+The interesting statistics are:
+.(b
+.nf
+\fIn\fR illegally large XPD TPDU
+\fIn\fR invalid length
+.fi
+.)b
+.sh 4 "Frozen References:"
+.pp
+The key issue here is to see that references are not reassigned
+until the reference timer expires.
+This can be observed by watching the timer activity as described
+above and by observing the reference numbers chosen for sockets
+with the \fBT.emit\fR
+or \fBT.input\fR trace options, which trace the TPDU headers.
+.sh 4 "Inactivity Control:"
+.pp
+Inactivity control can be observed by turning on the trace options
+\fBT.aks\fR, \fBT.akr\fR and \fBT.emit\fR
+during a simple file transfer.
+In the middle of the transfer, if the sender process
+is stopped, both TP entities continue
+to send acknowledgments.
+This can be observed in the trace.
+If the file tranfer is between machines, taking down one of the machines
+will cause the inactivity timer on the other machine to expire.
+The TP entity will respond to this by sending a DR TPDU
+to close the connection, which can be observed in the trace.
+The expiration of the timer can be observed in a trace if the
+\fBT.driver\fR option is used.
+This option traces all events and state changes in the
+TP
+finite state machine.
+.sh 4 "Connection establishment:"
+.pp
+The process of connection establishment can be observed with the
+\fBT.connect\fR
+trace and debug options, and
+the
+\fBT.driver \fR
+trace option.
+Various states of the connection establishment state machine
+may be observed with the
+the debug option
+\fBT.zdref\fR.
+This option
+causes \fItp_input()\fR
+to change the foreign reference on an incoming CC TPDU to zero,
+eventually causing the CC TPDU to be dropped,
+retransmissions of the CC to occur,
+and the connection to time out before being established.
+The statistics of interest are:
+.(b
+.nf
+\fIn\fR CCs sent to zero dref
+\fIn\fR invalid dest refs
+\fIn\fR CC (received)
+\fIn\fR CC (sent)
+\fIn\fR CC (retransmitted)
+\fIn\fR (connections) timed out on retrans
+.fi
+.)b
+.sh 4 "Disconnection:"
+.pp
+Various states of the connection breakdown part of the state machine
+may be observed with the
+the trace options
+\fBT.input\fR
+or
+\fBT.emit\fR,
+\fBT.driver\fR
+and
+running the
+discard or file transfer programs.
+.sh 4 "Association of TPDUs with Transport Connection:"
+.pp
+The problem of locating a transport connection
+given a TPDU is handled in
+\fItp_input()\fR in one of two ways.
+For an incoming CR TPDU, the transport suffix
+is used to locate a transport protocol
+control block (PCB), to which a transport
+connection is made by creating a new socket and PCB.
+For all other TPDU types, the destination reference is used
+to locate the appropriate transport connection.
+This is done by scanning the list of reference blocks.
+Debug and trace options
+were used to debug these sections of code but have since been
+removed due to their effect on the readability
+and maintainability of this code.
+The trace options
+\fBT.connect\fR
+and
+\fBT.newsock\fR
+creates trace records that contain the address of the
+socket as well as that of the PCB
+when a socket is opened.
+When a TPDU arrives for a given socket,
+the trace records created by the
+\fBT.input \fR
+option will also contain the address of the PCB that is found
+in
+\fItp_input()\fR.
+These two addresses can be compared in the trace output to observe
+that the proper association is made.
+.sh 4 "Protocol Errors and the ER TPDU:"
+.pp
+Certain types of errors are intended to evoke the response
+from the TP entity of sending an ER or a DR TPDU.
+The routine
+\fItp_error_emit()\fR
+creates ER and DR TPDUs for this purpose.
+The debug and trace option
+\fBT.erroremit\fR
+dumps information about the activity of this routine.
+Since ER TPDUs are not generated under normal circumstances,
+the parsing of ER TPDUs was tested in this
+implementation by code that generated (illegitimate) ER TPDUs,
+This code was removed because it significantly complicated code maintenance.
+.sh 4 "User Interface:"
+.pp
+The debug and trace options
+\fBT.request\fR,
+\fBT.params,\fR
+\fBT.indication\fR
+and
+\fBT.syscall\fR and
+dump information about the user interface.
+Most of the debugging code added to the socket-layer
+routines for debugging has since been removed so that
+the source (which is functionally unchanged from the 4.3 release)
+would not unnecessarily be changed.
+\fIRlogin.iso\fR, the TP version of remote login,
+exercises some of the original BSD data transfer system calls
+(\fIread()\fR and \fIwrite()\fR)
+rather than \fIsendv()\fR and \fIrecv()\fR.
+The interesting statistics are
+.(b
+.nf
+\fIn\fR EOT indications
+\fIn\fR user rcvd
+\fIn\fR connections used extended format
+\fIn\fR connections allowed transport XPD
+\fIn\fR connections turned off checksumming
+\fIn\fR TP 4 connections
+\fIn\fR TP 0 connections
+.fi
+.)b
projects / unix-history / commitdiff