doc/int/txt3

   1 .\"     Logging
   2 .\"
   3 .\"     $Id: txt3,v 2.3 1994/06/24 10:05:39 ceriel Exp $
   4 .bp
   5 .NH
   6 THE LOGGING MACHINE.
   7 .PP
   8 Since messages and warnings provided by \fBint\fP include source code file
   9 names and line numbers, they alone often suffice to identify the error.
  10 If, however, the necessity arises, much more extensive debugging information
  11 can be obtained by activating the the Logging Machine.
  12 This Logging Machine, which monitors all actions of the EM machine, is the
  13 subject of this chapter.
  14 .NH 2
  15 Implementation.
  16 .PP
  17 When inspecting the source code of \fBint\fP, many lines in the
  18 following format will show up:
  19 .DS
  20 LOG(("@<\fIletter\fP><\fIdigit\fP> message", args));
  21 .DE
  22 or
  23 .DS
  24 LOG(("\ <\fIletter\fP><\fIdigit\fP> message", args));
  25 .DE
  26 The double parentheses are needed, because \fILOG()\fP is
  27 declared as a define, and has a printf-like argument structure.
  28 .PP
  29 The <\fIletter\fP> classifies the log message and corresponds to an entry in
  30 the \fIlogmask\fP, which holds a threshold for each class of messages.
  31 The following classes exist:
  32 .TS
  33 tab(@);
  34 l l l.
  35 \(bu  A\-Z@the flow of instructions:
  36 @A:    array
  37 @B:    branch
  38 @C:    convert
  39 @F:    floating point arithmetic
  40 @I:    integer arithmetic
  41 @L:    load
  42 @M:    miscellaneous
  43 @P:    procedure call
  44 @R:    pointer arithmetic
  45 @S:    store
  46 @T:    compare
  47 @U:    unsigned arithmetic
  48 @X:    logical
  49 @Y:    sets
  50 @Z:    increment/decrement/zero
  51 \(bu  d@stack dumping.
  52 \(bu  g@gda & heap manipulation.
  53 \(bu  s@stack manipulation.
  54 \(bu  r@reading the loadfile.
  55 \(bu  q@floating point calculations during reading the loadfile.
  56 \(bu  x@the instruction count, contents and file position.
  57 \(bu  m@monitor calls.
  58 \(bu  p@procedure calls and returns.
  59 \(bu  t@traps.
  60 \(bu  w@warnings.
  61 .TE
  62 .LP
  63 When the interpreter reaches a LOG(()) statement it scans its first argument;
  64 if \fIletter\fP
  65 occurs in the logmask, and if \fIdigit\fP is lower or equal to the
  66 threshold in the logmask, the message is given.
  67 Depending on the first character, the message will be preceded by a
  68 position indication (with the @) or will be printed as is (with the
  69 space).
  70 The \fIletter\fP is determines the message class
  71 and the \fIdigit\fP is used to distinguish various levels
  72 of logging, with a lower digit indicating a more important message.
  73 We will call the <\fIletter\fP><\fIdigit\fP> combination the \fBid\fP of
  74 the logging.
  75 .LP
  76 In general, the lower the \fIdigit\fP following the \fIletter\fP,
  77 the more important the message.
  78 E.g. m5 reports about unsuccessful monitor calls only, m9 also reports
  79 about successful monitors (which are obviously less interesting).
  80 New logging messages can be added to the source code on relevant places.
  81 .LP
  82 Reasonable settings for the logmask are:
  83 .TS
  84 tab(@);
  85 l l l.
  86   @A\-Z9d4twx9@advised setting when trouble shooting (default).
  87   @A\-Zx9@shows the flow of instructions & global information.
  88   @pm9@shows the procedure & monitor calls.
  89   @tw9@shows warning & trap information.
  90 .TE
  91 .PP
  92 An EM interpreter without a Logging Machine can be obtained by undefining the
  93 macro \fICHECKING\fP in the file \fIchecking.h\fP.
  94 .NH 2
  95 Controlling the Logging machine.
  96 .PP
  97 The actions of the Logging Machine are controlled by a set of internal
  98 variables (one of which is the log mask).
  99 These variables can be set through assignments on the command line, as
 100 explained int the manual page \fIint.1\fP, q.v.
 101 Since there are a great many logging statements in the program, of which only a
 102 few will be executed in any call of the interpreter, it is important to be able
 103 to decide quickly if a given \fIid\fP has to be checked at all.
 104 To this end all logging statements are guarded (in the #define) by a test for
 105 the boolean variable \fIlogging\fP.
 106 This variable will only be set if the command line assignments show the
 107 potential need for logging (\fImust_log\fP) and the instruction count
 108 (\fIinr\fP) is at least equal to \fIlog_start\fP (which derives from the
 109 parameter \fBLOG\fP).
 110 .LP
 111 The log mask can be set by the assignment
 112 .DS
 113 "LOGMASK=\fIlogstring\fP"
 114 .DE
 115 which sets the current logmask to \fIlogstring\fP.
 116 A logstring has the following form:
 117 .DS
 118 [ [ \fIletter\fP | \fIletter\fP \- \fIletter\fP ]+ \fIdigit\fP ]+
 119 .DE
 120 E.g. LOGMASK=A\-D8x9R7c0hi4 will print all messages belonging to loggings
 121 with \fBid\fPs:
 122 \fIA0..A8,B0..B8,C0..C8,D0..D8,x0..x9,R0..R7,c0,h0..h4,i0..i4\fP.
 123 .PP
 124 The logging variable STOP can be used to prevent run-away logging
 125 past the point where the user expects an error to occur.
 126 STOP=\fInr\fP will stop the interpreter after instruction number \fInr\fP.
 127 .PP
 128 To simplify the use of the logging machine, a number of abbreviations have been
 129 defined.
 130 E.g., AT=\fInr\fP can be thought of as an abbreviation of LOG=\fInr\-1\fP
 131 STOP=\fInr+1\fP; this causes three stack dumps, one before the suspect
 132 instruction, one on it and one after it; then the interpreter stops.
 133 .PP
 134 Logging results will appear in a special logging file (default: \fIint.log\fP).
 135 .NH 2
 136 Dumps.
 137 .PP
 138 There are three routines available to examine the memory contents:
 139 .TS
 140 tab(@);
 141 l l l.
 142   @\fIstd_all()\fP@dumps the contents of the stack (\fId1\fP or \fId2\fP must be in the logmask).
 143   @\fIgdad_all()\fP@dumps the contents of the gda (\fI+1\fP must be in the logmask).
 144   @\fIhpd_all()\fP@dumps the contents of the heap (\fI*1\fP must be in the logmask).
 145 .TE
 146 .LP
 147 These routines can be used everywhere in the program to examine the
 148 contents of memory.
 149 The internal variables allow the
 150 gda and heap to be dumped only once (according to the
 151 corresponding internal variable).
 152 The stack is dumped after each
 153 instruction if the log mask contains d1 or d2; d2 gives a full formatted
 154 dump, d1 produces a listing of the Return Status Blocks only.
 155 An attempt is made to format the stack correctly, based on the shadow
 156 bytes, which identify the Return Status Block.
 157 .LP
 158 Remember to set the correct \fBid\fP in the LOGMASK, and to give
 159 LOG the correct value.
 160 If dumping is needed before the first instruction, then LOG must  be
 161 set to 0.
 162 .LP
 163 The dumps of the global data area and the heap are controlled internally by
 164 the id-s +1 and *1 resp.; the corresponding logmask entries are set
 165 automatically by setting the GDA and HEAP variables.
 166 .NH 2
 167 Forking.
 168 .PP
 169 As mentioned earlier, a call to \fIfork()\fP, causes an image of the current
 170 program to start running.
 171 To prevent a messy logfile, the child process gets its own logfile
 172 (and message file, tally file, etc.).
 173 These logfiles are distinguished from the parent logfile by the a
 174 postfix, e.g.,
 175 \fIlogfile_1\fP for the first child, \fIlogfile_2\fP for the second child,
 176 \fIlogfile_1_2\fP for the second child of the first child, etc.
 177 .br
 178 \fINote\fP: the implementation of this feature is shaky; it works for the log
 179 file but should also work for other files and for the names of the logging
 180 variables.