            ------------------------------------------------------
                                    libpfm-3.10:
      a helper library to program the Performance Monitoring Unit (PMU)
            ------------------------------------------------------
 	  Copyright (c) 2001-2007 Hewlett-Packard Development Company, L.P.
	                Contributed by Stephane Eranian <eranian@hpl.hp.com>
	

This package provides a library, called libpfm, which can be used
to develop monitoring tools which use the Performance Monitoring Unit (PMU)
of several modern processors.


This version of libpfm supports:
	- For Intel IA-64:
		Itanium (Merced), Itanium 2 (McKinley, Madison, Deerfield),
		Itanium 2 9000/9100 (Montecito, Montvale) and Generic
	- For AMD X86:
		AMD64 (K8, family 10h)
	- For Intel X86: 
		Intel P6 (Pentium II, Pentium Pro, Pentium III, Pentium M)
		Intel Yonah (Core Duo/Core Solo),
		Intel Netburst (Pentium 4, Xeon)
		Intel Core (Merom, Penryn, Dunnington) Core 2 and Quad
		Intel Atom
		Intel Nehalem (Nehalem, Westmere)
		Intel architectural perfmon v1, v2, v3
	- For MIPS:
		5K, 20K, 25KF, 34K, 5KC, 74K, R10000, R12000, RM7000, RM9000,
		SB1, VR5432, VR5500, SiCortex ICA9A/ICE9B
	- For Cray:
		XT3, XT4, XT5, XT5h, X2
	- For IBM:
		IBM Cell processor
		POWER: PPC970, PPC970MP, POWER4+, POWER5, POWER5+, POWER6, POWER7
	- For Sun:
		 Sparc: Ultra12, Ultra3, Ultra3i, Ultra3Plus, Ultra4Plus,
		 Sparc: Niagara1, Niagara2

The core library is generic and does not depend on the perfmon interface. It is
possible to use it on other operating systems.

WHAT'S THERE
-------------
	- the library source code including support for all processors listed
	  above

	- a set of examples showing how the library can be used with the
	  perfmon2 and perfmon3 kernel interface.

	- a set of older examples for IA-64 only using the legacy perfmon2
	  interface (v2.0).

	- a set of library header files and the perfmon2 and perfmon3 kernel
	  interface headers

	- libpfms: a simple library to help setup SMP system-wide monitoring
	  sessions. It comes with a simple example. This library is not part
	  of libpfm.

	- man pages for all the library entry points

	- Python bindings for libpfm and the perfmon interface (experimental).

INSTALLATION
------------
	- edit config.mk to :
		- update some of the configuration variables
		- make your compiler options

	- type make
	- type make install

 	- To compile and install the Python bindings, you need to go to the
	  python sub-directory and type make. Python is not systematically
	  built

	- to compile the library for another ABI (e.g. 32-bit x86 on a
	  64-bit x86) system, you can pass the ABI flag to the compiler as
	  follows (assuming you have the multilib version of gcc):
		$ make OPTION="-m32 -O2"

REQUIREMENTS:
-------------
	- to run the programs in the examples subdir, you MUST be using a linux
	  kernel with perfmon3. Perfmon3 is available as a branch of the
	  perfmon kernel GIT tree on kernel.org.

	- to run the programs in the examples_v2x subdir, you MUST be using a
	  linux kernel with perfmon2. Perfmon2 is available as the main branch
	  of the perfmon kernel GIT tree on kernel.org.

	- On IA-64, the examples in old_interface_ia64_examples work with
	  any 2.6.x kernels.

	- to compile the Python bindings, you need to have SWIG and the python
	  development packages installed

DOCUMENTATION
-------------
	- man pages for all entry points
	- More information can be found on library web site:
			http://perfmon2.sf.net
