debug.nr

早期freebsd实现

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