For an introduction to the design and use of this package, see index.html
and subsidiary pages.  Comments and questions should be directed to
Don Heller, Ames Laboratory, dheller@scl.ameslab.gov.

This software is derived from mperfmon (pperf) and its associated library,
by M. Patrick Goda and Michael S. Warren, Los Alamos National Laboratory.
Their README file, including a disclaimer, and the Ames Laboratory codicil,
are considered as part of the software distribution.

For the current installation instructions, see the Instructions file; do
not follow the installation instructions given here.

---------------------------------------------------------------------------
> 			   *** mperfmon ***
>
> 			    VERSION NOTES
>
> This is an ``alpha'' release of mperfmon.
>
>
> 			       NOTICES
>
> This software uses the msr module developed by Stephan Meyer.
>
> mperfmon is maintained by M. Patrick Goda.  Information about mperfmon
> and mperfmon source code is available at
> <http://qso.lanl.gov/~mpg/perfmon.html>.
>
> Since mperfmon is in its infancy, bug reports are greatly appreciated
> and can be reported to <loki-info@lanl.gov>.
>
>
> 			     DESCRIPTION
>
> mperfmon is a performance monitoring utility for the Intel Pentium and
> Pentium Pro processors.  mperfmon utilizes the Model Specific Registers
> built into the processor to profile hardware performance.  For
> specific information on available profiling events please see the
> section Profiling Events.
>
> Intel Corporation has implemented Model Specific Registers (MSRs) into
> the Pentium and Pentium Pro processors which allow users greater
> control over profiling than with standard profiling tools.  In
> addition to profiling events, the Pentium and Pentium Pro contain a
> free-running 64-bit Time Stamp Counter (TSC) which increments once
> every clock cycle allowing highly accurate profiling results in time.
> The MSRs on the Pentium and Pentium Pro can be used, for example, to
> monitor memory references, cache activity, bus activity and certain
> aspects of the Floating Point Unit (FPU).
>
> 			 LIMITATIONS AND BUGS
>
> mperfmon-0.6:
> 	mperfmon multiplexes over all or some subset of avalaible
> profiling events on the Pentium and Pentium Pro.
>
> 	The program to be invoked is specified on the command line
> after the invocation of mperfmon.  In this sense mperfmon operates much
> like the GNU time command which monitors a programs execution time.
> As of version 0.6 the values of the two profiling registers are
> affected by other running processes.  That is, the profiling registers
> are not saved in a context switch and thus contain spurious event
> counts.  However, in tests on a single user Pentium and Pentium Pro
> running X-Windows the results have been found to be in error by less
> than about 2%.  Be warned though, if multiple processor intensive jobs
> are running, one of which is being profiled, the results of perfmon
> could be seriously compromised.  We are working on a fix for this
> problem by adding support for the profiling registers into the task
> structure of the kernel which will allow accurate results for multiple
> users/jobs running concurrently.
>
> 	Since mperfmon multiplexes over the profiling events the
> reported values are approximations.  In our experience mperfmon
> provides very good (1-2% error) values for profiling events as long as
> the program execution time in longer than about 5 seconds.  Users of
> SGI's perfex will be used to this limitation imposed by multiplexing.
>
> 	mperfmon uses /dev/msr (via a module developed by Stephan
> Meyer).  Currently no checking is performed to prevent multiple
> instances of mperfmon from resetting the profiling events.  Thus, if
> two users attempt to run mperfmon at the same time the results will be
> unpredicatable and will not reflect actual event counts.  Until
> context switch support for the profiling event registers is added to
> the kernel this problem can be bypassed by running only one single
> instance of mperfmon on a processor at a time.
> 				
>
> 			       COPYING
>
> mperfmon is free software.  It was developed by M. Patrick Goda
> <pgoda@lanl.gov> and Michael S. Warren <mwarren@lanl.gov>.  Copyright
> 1997 by M. Patrick Goda and Michael S. Warren.
>
> Permission to copy and modify this code is granted by the authors
> provided that:
>
> 	1) This README file is included in all distributions of
> perfmon and its variants.
>
> 	2) The authors, M. Patrick Goda and Michael S. Warren of Los
> Alamos National Laboratory, are acknowledged in all distributions.
>
> mperfmon was developed at Los Alamos National Laboratory for use on
> Loki, a Beowulf class 16 node Pentium Pro cluster.  For details
> pertaining to Loki see <http://loki-www.lanl.gov>.
>
>
> 			 WARRANTY INFORMATION
>
> mperfmon is distributed in hopes that it will be useful to others but
> is provided AS IS.  M. PATRICK GODA, MICHAEL S. WARREN, LOS ALAMOS
> NATIONAL LABORATORY, THE UNIVERSITY OF CALIFORNIA AND ANY OTHER
> AUTHORS OF THIS SOFTWARE WILL NOT BE HELD RESPONSIBLE FOR ANY DAMAGES
> RESULTING FROM THE USE OF THIS SOFTWARE OR ANY OF ITS COMPONENT PARTS.
>
> BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
> FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
> WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
> PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
> EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
> IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
> PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
> PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
> THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
>
> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
> WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
> REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
> DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
> DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
> (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
> INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
> THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER
> OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
---------------------------------------------------------------------------

The Ames Laboratory lawyer says to add this:

> ANY MODIFICATION MADE HEREIN BY DON E. HELLER OR OTHERS OF
> AMES LABORATORY, IOWA STATE UNIVERSITY, ARE PROVIDED "AS-IS"
> AND ARE SUBJECT TO THE SAME WARRANTY, DISCLAIMER AND
> ACKNOWLEDGMENT REQUIREMENTS AS PREVIOUSLY PROVIDED HEREIN.

Copyright 1998-2000 by Don E. Heller.