util/int/int.1

   1 .\"     Manual page
   2 .\"
   3 .\"     $Id: int.1,v 2.4 1994/06/24 10:47:35 ceriel Exp $
   4 .TH INT 1 "$Revision: 2.4 $"
   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