int.1 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200
  1. .\" Manual page
  2. .\"
  3. .\" $Id$
  4. .TH INT 1 "$Revision$"
  5. .ad
  6. .SH NAME
  7. int \- Interpreter for EM Machine Language
  8. .SH SYNOPSIS
  9. \fBint\fP [ intargs ] [ emfile [ emargs ] ]
  10. .SH DESCRIPTION
  11. This program interprets the EM machine-language, and replaces
  12. the pascal written EM interpreter described in [1].
  13. The program interprets load files in \fIe.out\fP format (see [1], sec. 10.3).
  14. .LP
  15. \fIEmfile\fP is the name of the load file; if no name is
  16. specified, the default name \fIe.out\fP is used.
  17. The program can handle several word size / pointer size combinations.
  18. The combinations presently supported are 2/2, 2/4 and 4/4.
  19. .LP
  20. \fIEmargs\fP are the arguments for the program being interpreted.
  21. If any arguments are given, then \fIemfile\fP must be present.
  22. .PP
  23. The interpreter can generate diagnostic messages (warnings) about the
  24. interpreted program.
  25. Some of these warnings are given very frequently,
  26. which may result in a large, non-functional message file.
  27. To avoid this behavior, counters keep track of the number of times
  28. a given warning occurs in a given file at a given line number.
  29. Only when this counter is a power of 4, the warning will actually be
  30. given.
  31. `Logarithmic warning generation' is established in this way.
  32. .PP
  33. \fIInt\fP preempts the highest two file descriptors available, for
  34. diagnostic purposes.
  35. Interpreted programs can use the other file descriptors without
  36. clash problems.
  37. .PP
  38. .I "Interpreter parameters"
  39. .br
  40. \fIInt\fP itself accepts the following options, all given as separate flags:
  41. .IP \fB\-d\fP
  42. The program will not be run; a disassembly listing of the program will
  43. be written to standard output file instead.
  44. The original names are lost, but the procedure structure is recovered.
  45. .IP \fB\-h\fP\fIN\fP
  46. The maximum size of the heap will be limited to \fIN\fP bytes. This can be
  47. used to force a heap overflow trap.
  48. .IP \fB\-I\fP\fIN\fP
  49. It is possible to tell \fIint\fP to ignore traps in the range 0-15.
  50. If a trap is ignored, every time the trap would have happened
  51. a warning is generated instead.
  52. The argument \fIN\fP is the trap number, as described in [1], sec. 9.
  53. For ignoring more than one trap, several \fB\-I\fP flags are needed.
  54. .IP \fB\-m\fP\fIfile\fP
  55. The argument \fIfile\fP is the name of a file on which the messages will
  56. appear.
  57. The default file name is \fIint.mess\fP.
  58. .IP \fB\-r\fP\fIN\fP
  59. Determines the size of the Function Return Area.
  60. Default: 2 \(mu pointer size.
  61. .IP \fB\-s\fP\fIN\fP
  62. The maximum size of the stack will be limited to \fIN\fP bytes. This can be
  63. used to force a stack overflow trap.
  64. .IP \fB\-t\fP
  65. If given, a file \fIint.tally\fP will be produced upon program termination.
  66. For each source file, it contains a list of line numbers visited,
  67. with the number of times the line was visited and
  68. the number of EM instructions executed on the line.
  69. .IP \fB\-W\fP\fIN\fP
  70. This option can be used to disable warnings.
  71. The argument \fIN\fP is the number of the warning to be suppressed,
  72. as found in the \fIint\fP documentation [3].
  73. For disabling more than one warning, several \fB\-W\fP flags are needed.
  74. .PP
  75. .I "The Logging Machine"
  76. .br
  77. The EM machine is monitored continually by a Logging Machine. This logging
  78. machine keeps an instruction count and
  79. can produce a trace of the actions of the EM machine, make readable
  80. dumps of the stack, heap and global data area, and stop the EM machine after a
  81. given instruction number.
  82. The actions of the logging machine are controlled by
  83. its internal variables, the values of which can be set by assignments on the
  84. command line, much like setting macro names in a call of \fImake\fP.
  85. These assignments can be interspersed with the options for the EM machine.
  86. .PP
  87. The logging machine has the following internal variables:
  88. .IP \fBLOG\fP=\fIN\fP
  89. Logging will start when the instruction count has reached \fIN\fP.
  90. .IP \fBLOGMASK\fP=\fIstring\fP
  91. The tracing actions are controlled by a log mask; the log mask consists of a
  92. list of pairs of action classes and logging levels.
  93. E.g. \fBLOGMASK\fP=\fIm9\fP means: trace all monitor calls.
  94. The action classes are described fully in [3].
  95. The default log mask is reasonably suitable.
  96. .IP \fBLOGFILE\fP=\fIstring\fP
  97. The \fIstring\fP is the name of a file on which all logging information is
  98. written.
  99. The default file name is \fIint.log\fP.
  100. .IP \fBSTOP\fP=\fIN\fP
  101. The logging machine stops the EM machine after instruction \fIN\fP.
  102. .PP
  103. Stack dumps can be made after each instruction; they are controlled by the pair
  104. \fBd4\fP in the log mask; gda and heap dumps can only be made after a specific
  105. instruction.
  106. The following internal variables pertain to memory dumps:
  107. .IP \fBGDA\fP=\fIN\fP
  108. The contents of the Global Data Area are dumped after instruction \fIN\fP. The
  109. extent can be adjusted by setting \fBGMIN\fP=\fINmin\fP (default 0) and
  110. \fBGMAX\fP=\fINmax\fP (default HB).
  111. .IP \fBHEAP\fP=\fIN\fP
  112. The contents of the heap are dumped after instruction \fIN\fP.
  113. .IP \fBSTDSIZE\fP=\fIN\fP
  114. The stack dump is restricted to the \fIN\fP topmost bytes.
  115. .IP \fBRAWSTACK\fP=\fIN\fP
  116. Normally the stack dump produced is divided into activation records
  117. separated by formatted dumps of the Return Status Blocks.
  118. If \fIN\fP is non-zero, this dividing and formatting is suppressed, and the
  119. stack is dumped raw.
  120. .PP
  121. Some combinations of variable settings are generally useful and can be
  122. abbreviated:
  123. .IP \fBAT\fP=\fIN\fP
  124. Is an abbreviation of \fBLOG\fP=\fIN\-1\fP \fBSTOP\fP=\fIN+1\fP.
  125. The default log mask applies.
  126. .IP \fBL\fP=\fIstring\fP
  127. Is an abbreviation of \fBLOG\fP=\fI0\fP \fBLOGMASK\fP=\fIstring\fP.
  128. E.g., \fBL\fP=\fIm9\fP will log all monitor calls
  129. and \fBL\fP=\fIA\-Z9\fP will log all instructions (give a full trace).
  130. .PP
  131. When the interpreter forks, the child continues logging on a new file named
  132. \fIint.log_1\fP, etc.
  133. In principle it reevaluates the interpreter arguments, now looking for
  134. \fBLOG_1\fP, \fBLOGMASK_1\fP, etc., but this feature has not been fully
  135. implemented.
  136. .PP
  137. .I "Diagnostics"
  138. .br
  139. All diagnostics are written to the message file.
  140. Diagnostics come in three flavors:
  141. .IP \-
  142. (messages): These mention NOP instructions, give more information
  143. about incoming signals and display the exit status of the program.
  144. .IP \-
  145. (warnings): These are generated as a result of the checking.
  146. In most cases the diagnostic is self-explanatory.
  147. A complete description of the warnings can be found in the \fIint\fP
  148. documentation [3].
  149. .IP \-
  150. (fatal errors): This diagnostic is the result of an irrecoverable
  151. error, generally before the program has started: incorrect call of the
  152. interpreter, cannot access file, incorrect format of load file. A few follow
  153. during interpretation: out of memory, uncaught traps, floating point operation
  154. on a version without floating point;
  155. execution stops immediately after the diagnostic is generated.
  156. .PP
  157. Further diagnostics are generated (on \fIstderr\fP) if files cannot
  158. be opened or found.
  159. .SH "SEE ALSO"
  160. e.out(5), ack(1), em22(1), em24(1), em44(1).
  161. .IP [1]
  162. Andrew S. Tanenbaum, Hans van Staveren, Ed G. Keizer and Johan W. Stevenson,
  163. \fIDescription of a Machine Architecture for use with Block
  164. Structured Languages\fP, Informatica rapport IR-81.
  165. .IP [2]
  166. Amsterdam Compiler Kit, reference manual and UNIX manual pages.
  167. .IP [3]
  168. Eddo de Groot, Leo van den Berge, Dick Grune,
  169. \fIThe EM Interpreter\fP.
  170. .SH "FILES"
  171. .ta 20n
  172. int.mess contains messages
  173. .br
  174. int.log contains logging info, if requested
  175. .br
  176. int.tally contains tally results, if requested
  177. .br
  178. int.core produced upon fatal error; format provisional
  179. .SH "BUGS"
  180. The monitor calls
  181. .IR mpxcall ,
  182. .I ptrace
  183. and
  184. .I profile
  185. have not been implemented.
  186. .br
  187. The maximum number of bytes for rotation is 4.
  188. .br
  189. The UNIX V7 struct tchars is not emulated under System V.
  190. .br
  191. The P and N restrictions on operands are not checked.
  192. .br
  193. The start-up has a quadratic component in the number of procedures in the EM
  194. program.
  195. .SH "AUTHORS"
  196. L.J.A. van den Berge.
  197. .br
  198. E.J. de Groot.
  199. .br
  200. D. Grune