README for lcomp and lprint
cheap dynamic instruction counting

This package is based on Peter Weinberger's "Cheap Dynamic Instruction
Counting" from the AT&T Bell Labs Tech Journal Unix(tm) issue of a
few years ago (Vol 63, No 8, Oct 1984, pp 1815-1826).  These programs
were written for a class taught by David Hanson at Princeton University
in Spring 1988.  (Computer Science 596, Systems Programming Workshop)

This code runs on Sun-3s (68020s) and Vaxen (4.3 bsd and ultrix).  Since it
works with the assembly language output of compilers, it needs to make
some assumptions.  The files 68020.l and vax.l are lex programs that match
the instructions in an assembly program.  For new machines, if the assembler
is a unix-like assembler and the compiler doesn't do too many strange things,
it should be possible to easily change one of the included .l files to work
if you look at the code a bit and know the relevant assembly language.  If
people are interested, I will maintain a library of machine.l files.

To get this working on a vax or a sun, edit the makefile to set TARGET
to 68020 or vax, and  change BIN, LIB, and MAN and do a make install.
BIN, LIB, and MAN may not be the current directory.  If you do not want
to install the programs, edit lcomp to change the LIB directory to the
current directory.

See the enclosed manual page (and Weinberger's paper) for how to use
and interpret the results of these programs.

The interesting thing about this package is the use of lex to drive the
instruction recognizer.  I like this approach, and would defend it,
because i did my port to the sun 68020 compiler in less than an hour by
changing the patterns matched and the inserted assembly code (all in
the lex source).  Only two small changes had to be made to the machine
independent code (bb.c) to support the sun, but this was just because
of a few vax-centrist assumptions I had made when writing the original code.
See the file INTERNALS for a description of how to write the driver for
a new machine.

lcomp functions as either cc or f77.  I have not found a case where it
breaks.  Note that you must use -F when linking fortran .o files if
there are no .f files listed as arguments.

lprint is modelled on the Ninth Edition manual page for Weinberger's code,
but I wrote it from memory and confused the meaning of all of his
options.  Since my lprint and his have different functionality and I
thought my names made more sense for my program, I kept my version of
the option names.

For a different approach to writing a package like this, see Sun's tcov,
which add profiling code to C source rather than compiler output.


This code is wholly within the public domain.  It is not copy(right|left)ed
by anyone or any organization.  Do with it what you wish.

Paul Haahr
princeton!haahr (haahr@princeton.edu)
