ack/util/int/int.1

.\"	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