123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200 |
- .\" Manual page
- .\"
- .\" $Id$
- .TH INT 1 "$Revision$"
- .ad
- .SH NAME
- int \- Interpreter for EM Machine Language
- .SH SYNOPSIS
- \fBint\fP [ intargs ] [ emfile [ emargs ] ]
- .SH DESCRIPTION
- This program interprets the EM machine-language, and replaces
- the pascal written EM interpreter described in [1].
- The program interprets load files in \fIe.out\fP format (see [1], sec. 10.3).
- .LP
- \fIEmfile\fP is the name of the load file; if no name is
- specified, the default name \fIe.out\fP is used.
- The program can handle several word size / pointer size combinations.
- The combinations presently supported are 2/2, 2/4 and 4/4.
- .LP
- \fIEmargs\fP are the arguments for the program being interpreted.
- If any arguments are given, then \fIemfile\fP must be present.
- .PP
- The interpreter can generate diagnostic messages (warnings) about the
- interpreted program.
- Some of these warnings are given very frequently,
- which may result in a large, non-functional message file.
- To avoid this behavior, counters keep track of the number of times
- a given warning occurs in a given file at a given line number.
- Only when this counter is a power of 4, the warning will actually be
- given.
- `Logarithmic warning generation' is established in this way.
- .PP
- \fIInt\fP preempts the highest two file descriptors available, for
- diagnostic purposes.
- Interpreted programs can use the other file descriptors without
- clash problems.
- .PP
- .I "Interpreter parameters"
- .br
- \fIInt\fP itself accepts the following options, all given as separate flags:
- .IP \fB\-d\fP
- The program will not be run; a disassembly listing of the program will
- be written to standard output file instead.
- The original names are lost, but the procedure structure is recovered.
- .IP \fB\-h\fP\fIN\fP
- The maximum size of the heap will be limited to \fIN\fP bytes. This can be
- used to force a heap overflow trap.
- .IP \fB\-I\fP\fIN\fP
- It is possible to tell \fIint\fP to ignore traps in the range 0-15.
- If a trap is ignored, every time the trap would have happened
- a warning is generated instead.
- The argument \fIN\fP is the trap number, as described in [1], sec. 9.
- For ignoring more than one trap, several \fB\-I\fP flags are needed.
- .IP \fB\-m\fP\fIfile\fP
- The argument \fIfile\fP is the name of a file on which the messages will
- appear.
- The default file name is \fIint.mess\fP.
- .IP \fB\-r\fP\fIN\fP
- Determines the size of the Function Return Area.
- Default: 2 \(mu pointer size.
- .IP \fB\-s\fP\fIN\fP
- The maximum size of the stack will be limited to \fIN\fP bytes. This can be
- used to force a stack overflow trap.
- .IP \fB\-t\fP
- If given, a file \fIint.tally\fP will be produced upon program termination.
- For each source file, it contains a list of line numbers visited,
- with the number of times the line was visited and
- the number of EM instructions executed on the line.
- .IP \fB\-W\fP\fIN\fP
- This option can be used to disable warnings.
- The argument \fIN\fP is the number of the warning to be suppressed,
- as found in the \fIint\fP documentation [3].
- For disabling more than one warning, several \fB\-W\fP flags are needed.
- .PP
- .I "The Logging Machine"
- .br
- The EM machine is monitored continually by a Logging Machine. This logging
- machine keeps an instruction count and
- can produce a trace of the actions of the EM machine, make readable
- dumps of the stack, heap and global data area, and stop the EM machine after a
- given instruction number.
- The actions of the logging machine are controlled by
- its internal variables, the values of which can be set by assignments on the
- command line, much like setting macro names in a call of \fImake\fP.
- These assignments can be interspersed with the options for the EM machine.
- .PP
- The logging machine has the following internal variables:
- .IP \fBLOG\fP=\fIN\fP
- Logging will start when the instruction count has reached \fIN\fP.
- .IP \fBLOGMASK\fP=\fIstring\fP
- The tracing actions are controlled by a log mask; the log mask consists of a
- list of pairs of action classes and logging levels.
- E.g. \fBLOGMASK\fP=\fIm9\fP means: trace all monitor calls.
- The action classes are described fully in [3].
- The default log mask is reasonably suitable.
- .IP \fBLOGFILE\fP=\fIstring\fP
- The \fIstring\fP is the name of a file on which all logging information is
- written.
- The default file name is \fIint.log\fP.
- .IP \fBSTOP\fP=\fIN\fP
- The logging machine stops the EM machine after instruction \fIN\fP.
- .PP
- Stack dumps can be made after each instruction; they are controlled by the pair
- \fBd4\fP in the log mask; gda and heap dumps can only be made after a specific
- instruction.
- The following internal variables pertain to memory dumps:
- .IP \fBGDA\fP=\fIN\fP
- The contents of the Global Data Area are dumped after instruction \fIN\fP. The
- extent can be adjusted by setting \fBGMIN\fP=\fINmin\fP (default 0) and
- \fBGMAX\fP=\fINmax\fP (default HB).
- .IP \fBHEAP\fP=\fIN\fP
- The contents of the heap are dumped after instruction \fIN\fP.
- .IP \fBSTDSIZE\fP=\fIN\fP
- The stack dump is restricted to the \fIN\fP topmost bytes.
- .IP \fBRAWSTACK\fP=\fIN\fP
- Normally the stack dump produced is divided into activation records
- separated by formatted dumps of the Return Status Blocks.
- If \fIN\fP is non-zero, this dividing and formatting is suppressed, and the
- stack is dumped raw.
- .PP
- Some combinations of variable settings are generally useful and can be
- abbreviated:
- .IP \fBAT\fP=\fIN\fP
- Is an abbreviation of \fBLOG\fP=\fIN\-1\fP \fBSTOP\fP=\fIN+1\fP.
- The default log mask applies.
- .IP \fBL\fP=\fIstring\fP
- Is an abbreviation of \fBLOG\fP=\fI0\fP \fBLOGMASK\fP=\fIstring\fP.
- E.g., \fBL\fP=\fIm9\fP will log all monitor calls
- and \fBL\fP=\fIA\-Z9\fP will log all instructions (give a full trace).
- .PP
- When the interpreter forks, the child continues logging on a new file named
- \fIint.log_1\fP, etc.
- In principle it reevaluates the interpreter arguments, now looking for
- \fBLOG_1\fP, \fBLOGMASK_1\fP, etc., but this feature has not been fully
- implemented.
- .PP
- .I "Diagnostics"
- .br
- All diagnostics are written to the message file.
- Diagnostics come in three flavors:
- .IP \-
- (messages): These mention NOP instructions, give more information
- about incoming signals and display the exit status of the program.
- .IP \-
- (warnings): These are generated as a result of the checking.
- In most cases the diagnostic is self-explanatory.
- A complete description of the warnings can be found in the \fIint\fP
- documentation [3].
- .IP \-
- (fatal errors): This diagnostic is the result of an irrecoverable
- error, generally before the program has started: incorrect call of the
- interpreter, cannot access file, incorrect format of load file. A few follow
- during interpretation: out of memory, uncaught traps, floating point operation
- on a version without floating point;
- execution stops immediately after the diagnostic is generated.
- .PP
- Further diagnostics are generated (on \fIstderr\fP) if files cannot
- be opened or found.
- .SH "SEE ALSO"
- e.out(5), ack(1), em22(1), em24(1), em44(1).
- .IP [1]
- Andrew S. Tanenbaum, Hans van Staveren, Ed G. Keizer and Johan W. Stevenson,
- \fIDescription of a Machine Architecture for use with Block
- Structured Languages\fP, Informatica rapport IR-81.
- .IP [2]
- Amsterdam Compiler Kit, reference manual and UNIX manual pages.
- .IP [3]
- Eddo de Groot, Leo van den Berge, Dick Grune,
- \fIThe EM Interpreter\fP.
- .SH "FILES"
- .ta 20n
- int.mess contains messages
- .br
- int.log contains logging info, if requested
- .br
- int.tally contains tally results, if requested
- .br
- int.core produced upon fatal error; format provisional
- .SH "BUGS"
- The monitor calls
- .IR mpxcall ,
- .I ptrace
- and
- .I profile
- have not been implemented.
- .br
- The maximum number of bytes for rotation is 4.
- .br
- The UNIX V7 struct tchars is not emulated under System V.
- .br
- The P and N restrictions on operands are not checked.
- .br
- The start-up has a quadratic component in the number of procedures in the EM
- program.
- .SH "AUTHORS"
- L.J.A. van den Berge.
- .br
- E.J. de Groot.
- .br
- D. Grune
|