            ------------------------------------------------------
                                   pfmon-3.2:
	            a tool to monitor performance on Linux
            ------------------------------------------------------
 	 Copyright (c) 2001-2006 Hewlett-Packard Development Company, L.P.
	            Stephane Eranian <eranian@hpl.hp.com>

This package provides a tool, called pfmon, which monitors performance
on unmodified binaries or for an entire system. On each supported processor,
it exploits the Performance Monitoring Unit (PMU) which implements the hardware performance
counters. This package uses the perfmon2 kernel support interface to access the
PMU and the libpfm library.

This version of pfmon supports the following processors:
	- Itanium (Merced), Itanium2 (McKinley, Madison, Deerfield, DP), Dual-core Itanium 2 (Montecito) processors
	- Intel PIII, Intel Pentium M, Intel architected IA-32 PMU, Intel Core Duo/Solo, Intel Core 2 Duo processors
	- AMD X86-64 (both 32 and 64 bit modes) Opteron processors
	- various MIPS processors

REQUIREMENTS
------------

         - For all architectures, you must use a 2.6.x kernels.
	   For IA-64, it can be any 2.6.x kernels but preferrably above 2.6.5,
	   and it can implement either perfmon2 v2.0 or v2.2 or higher.

	   For all other architectures, the kernel must implement perfmon2 v2.4
	   or higher (kernel 2.6.21 or higher). Note that v2.2 or higher is
	   currrently available as a kernel patch from:
	   	http://perfmon2.sf.net/

	 - you need libpfm-3.2 dated 070507 or more recent.
	   The is available from:
	   	http://perfmon2.sf.net/

	 - you need the libelf development package or equivalent such as
	   elfutils-devel depending on your Linux distribution.

	 - if you want pfmon crash dump support you need to download libunwind.
	   You can download this library from the following site: 
	   http://savannah.nongnu.org/projects/libunwind

WHAT'S THERE
-------------

	- the pfmon tool (pfmon directory) which collects performance data on 
	  unmodified binaries or for the entire system (UP & SMP).

	- a small set of test programs (tests directory) including pfdbg to 
	  turn on/off kernel perfmon2 debugging. 

	- a small man pages. More extensive documentation is available on
	  the web site.

INSTALLATION
------------

	- you must have the libpfm-3.2 package already installed. At a minimum,
	  the runtime package. You need the development package to compile
	  pfmon.

	- edit config.mk to :

	  - update some config variables to suit your installation, in particular
	    where to find the libpfm headers and library

	  - if you have libunwind and want call stack dumping on pfmon crash,
	    say 'y' for CONFIG_PFMON_LIBUNWIND

	  - select your compiler options

	  - select which PMU you want to support. Multiple PMUs for the same
	    processor architecture can be supported by a single binary

	- type make

	- type make install

	- you're done, type pfmon --help for a list of options

DOCUMENTATION
-------------
	- More up to date information can be found on pfmon web site: 
	  http://perfmon2.sf.net/
