------------------------------------------------------

                                    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