txt3 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. .\" Logging
  2. .\"
  3. .\" $Id$
  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.