path: root/share/doc/iso/wisc/debug.nr

.\"$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