diff options
Diffstat (limited to 'share/doc/iso/wisc/debug.nr')
| -rw-r--r-- | share/doc/iso/wisc/debug.nr | 1043 |
1 files changed, 1043 insertions, 0 deletions
diff --git a/share/doc/iso/wisc/debug.nr b/share/doc/iso/wisc/debug.nr new file mode 100644 index 0000000..352eeee --- /dev/null +++ b/share/doc/iso/wisc/debug.nr @@ -0,0 +1,1043 @@ +.\"$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 |
