--- /dev/null
+.\" $Header$
+.TH EM 1ACK
+.ad
+.SH NAME
+em \- calling program for em interpreters
+.SH SYNOPSIS
+em [-t] [+fcp] [loadfile [args ... ...] ]
+.SH DESCRIPTION
+The loadfile ("e.out" if not specified) is opened to read the first 8 word header.
+The format of this header is explained in e.out(5).
+One of these 8 words is a flag word
+specifying the interpreter options requested at compile time.
+The usual setting of these options is +t -f -c -p.
+These options may be overridden at runtime as follows:
+em -t turns the test option of; em +c turns count on ; em +p turns profile
+on ; em +c +p turns both count and profile on.
+Based on these options the name of the appropriate interpreter
+is constructed.
+Two versions exist, one for two byte words and four byte pointers and
+one for four byte words and pointers.
+The information in the header of the e.out file is used by em to select the
+right interpreter for the word size of used in the e.out file.
+.PP
+This interpreter is searched for in ~em/lib/int[24]4.
+.PP
+The flags control the following options that can be turned off
+or on by prepending them with - or + respectively:
+.IP t
+run time tests for undefined variables, array bounds etc...
+This option costs a small amount of memory and some time.
+However, it is very useful for debugging.
+.IP p
+profiling of the entire program. The interpreter maintains tables containing
+an estimate of the number of processor state cycles used per source line.
+A processor state cycle is equal to two internal clock cycles.
+This option is expensive in time as well as in memory space.
+The result tables made at run time are dumped in a human readable
+format onto a file named
+em_profile.
+.IP f
+maintain a bit map of all source lines that have been executed.
+This map is written onto a file em_flow .
+This option is almost free in time and space.
+The file is not easy to read.
+Of each procedure only the lines between the first statement and the last
+statement are represented in the bit map.
+Currently this option is not installed in the em tree.
+.IP c
+count line usage in tables that
+contains for every source line the number of times it
+was entered.
+These tables are written onto em_count, a human readable file .
+This option is cheap in time, but costs some in memory space.
+.IP l
+dump the line numbers of the last 64 lines entered onto a file named
+em_last.
+This file will be in a human readable format.
+This option is used simultaneously with the test option.
+.PP
+These flags
+give rise to 5 different interpreters which are in the
+directory ~em/lib/int24 or in ~em/lib/int44
+for the two byte word or the four byte word options, respectively.
+.PP
+.SH "FILES"
+.IP ~em/lib/int[24]4/em_???? 35
+interpreters proper
+.IP em_profile
+profile data
+.IP em_count
+source line count data
+.IP em_flow
+source line flow data
+.IP em_last
+last lines executed
+.PD
+.SH "SEE ALSO"
+\fIack\fP(I),
+.SH BUGS
+Most error messages are self explanatory.
+If runtime flags are turned on it is advisable to try again
+with the default options.
+If the interpreter does not work most probably your particular
+machine has an other format for the system calls then assumed
+in the source.
+In that case adapt source file mloopc to your machine.
+Also the instruction that causes the machine to allocate stack
+space might differ .
+In that case adapt the macro \fIclaimstack\fP in deffile.
+.SH AUTHOR
+Freek van Schagen
--- /dev/null
+.\" $Header$
+.TH EM 1ACK
+.ad
+.SH NAME
+em \- calling program for em interpreters
+.SH SYNOPSIS
+em [-t] [+fcp] [loadfile [args ... ...] ]
+.SH DESCRIPTION
+The loadfile ("e.out" if not specified) is opened to read the first 8 word header.
+The format of this header is explained in e.out(5).
+One of these 8 words is a flag word
+specifying the interpreter options requested at compile time.
+The usual setting of these options is +t -f -c -p.
+One of these options may be overridden at run time
+by the corresponding flag of em.
+Based on these options the name of the appropriate interpreter
+is constructed.
+.PP
+The flags control the following options that can be turned off
+or on by prepending them with - or + respectively:
+.IP t
+run time tests for undefined variables, array bounds etc...
+This option costs a small amount of memory and some time.
+However, it is very useful for debugging.
+.IP p
+profiling of the entire program. The interpreter maintain tables containing
+an estimate of the number of memory cycles used per source line.
+This option is expensive in time as well as in memory space.
+The result tables made at run time are dumped onto a file named
+em_runinf. This file is converted to human readable format
+by the program eminform(1) which writes the profiling information
+on a file called em_profile.
+.IP f
+maintain a bit map of all source lines that have been executed.
+This map is written also onto the file em_runinf and can be interpreted by eminform(1) which writes in this case the file em_flow.
+This option is almost free in time and space.
+.IP c
+count line usage in tables that
+contains for every source line the number of times it
+was entered.
+These tables are also written onto em_runinf.
+Eminform(1) can be used to convert this information into the
+file em_count.
+Cheap in time, expensive in memory space.
+.PP
+These flags
+give rise to 5 different interpreters which are in the
+directory ~em/lib/int22/em_????
+.PP
+If the interpreter exits with a non-zero exit status, then the line numbers
+of the 64 last executed source lines are dumped on the file
+em_runinf
+in the current directory. Eminform(1) writes this information
+on the human readable file em_last.
+.SH "FILES"
+.IP ~em/lib/int22/em_???? 35
+interpreters proper
+.IP em_runinf
+memory dump containing runtime information
+.IP em_profile
+profile data
+.IP em_count
+source line count data
+.IP em_flow
+source line flow data
+.IP em_last
+last lines executed
+.PD
+.SH "SEE ALSO"
+eminform(1), ack(1),
+.SH BUGS
+Most error messages are self explanatory.
+The interpreter stops in case of lack of space with an error
+message SEGVIO stack overflow.
+If runtime flags are turned on it is advisable to try again
+with the default options.
+Bugs should be reported to Evert Wattel.
--- /dev/null
+.\" $Header$
+.tr ~
+.TH EMINFORM 1ACK
+.ad
+.SH NAME
+eminform \- converts runtime information of interpreted em to
+human readable form.
+.SH SYNOPSIS
+eminform
+.SH DESCRIPTION
+The EM interpreter, em(1), has several debugging features built in.
+They can be activated by flag options to em(1).
+The EM interpreter collects the information while it runs the program.
+When the program is terminated, the interpreter dumps this information onto
+a file called em_runinf.
+Eminform converts this information in human readable form onto
+a set of files with fixed names, the file em_runinf itself is unlinked.
+.PP
+.in +15
+.ti -13
+~~em_last~~~~A circular buffer is used to keep track of
+the last collection of executed source lines.
+.ti -13
+~~em_flow~~~~A bit map for all source lines tells which lines
+are executed.
+.ti -13
+~~em_count~~~Count the number of times each source line was entered.
+.ti -13
+~~em_profile~Estimate the number of memory cycles
+spent on each source line.
+.in -15
+.LP
+The most common use of eminform is to print the numbers of the last executed
+source lines if an execution error occurred.
+No arguments are needed in this case.
+.LP
+Eminform will create only those files for which there were
+interpreter flags turned on. If no runtime error occurred and
+no flag was turned on the file em_runinf is not created. In
+this case eminform will give the error message "read header
+failed".
+.SH FILES
+em_runinf, em_last, em_flow, em_count, em_profile
+.SH "SEE ALSO"
+ack(1), em(1).
+.SH BUGS
+If an entire procedure is not touched, the the file name in
+which this procedure occured is unknown.
+If no em_runinf is available the error message is "read header
+failed" and a core dump is created.
+Bugs should be reported to Evert Wattel
public / ack.git / commitdiff