|
Packit |
577717 |
/*
|
|
Packit |
577717 |
* File: INSTALL.txt
|
|
Packit |
577717 |
* CVS: $Id$
|
|
Packit |
577717 |
* Author: Kevin London
|
|
Packit |
577717 |
* london@cs.utk.edu
|
|
Packit |
577717 |
* Mods: Dan Terpstra
|
|
Packit |
577717 |
* terpstra@cs.utk.edu
|
|
Packit |
577717 |
* Mods: Philip Mucci
|
|
Packit |
577717 |
* mucci@cs.utk.edu
|
|
Packit |
577717 |
* Mods: <your name here>
|
|
Packit |
577717 |
* <your email address>
|
|
Packit |
577717 |
*/
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
HOW TO INSTALL PAPI ONTO YOUR SYSTEM
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
|
|
Packit |
577717 |
On some of the systems that PAPI supports, you can install PAPI right
|
|
Packit |
577717 |
out of the box without any additional setup. Others require drivers or
|
|
Packit |
577717 |
patches to be installed first.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The general installation steps are below, but first find your particular
|
|
Packit |
577717 |
Operating System's section for any additional steps that may be necessary.
|
|
Packit |
577717 |
NOTE: the configure and make files are located in the papi/src directory.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
General Installation
|
|
Packit |
577717 |
|
|
Packit |
577717 |
1. % ./configure
|
|
Packit |
577717 |
% make
|
|
Packit |
577717 |
|
|
Packit |
577717 |
2. Check for errors.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
a) Run a simple test case: (This will run ctests/zero)
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% make test
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If you get good counts, you can optionally run all the test programs
|
|
Packit |
577717 |
with the included test harness. This will run the tests in quiet mode,
|
|
Packit |
577717 |
which will print PASSED, FAILED, or SKIPPED. Tests are SKIPPED if the
|
|
Packit |
577717 |
functionality being tested is not supported by that platform.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% make fulltest (This will run ./run_tests.sh)
|
|
Packit |
577717 |
|
|
Packit |
577717 |
To run the tests in verbose mode:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% ./run_tests.sh -v
|
|
Packit |
577717 |
|
|
Packit |
577717 |
3. Create a PAPI binary distribution or install PAPI directly.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
a) To install PAPI libraries and header files from the build tree:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% make install
|
|
Packit |
577717 |
|
|
Packit |
577717 |
b) To install PAPI manual pages from the build tree:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% make install-man
|
|
Packit |
577717 |
|
|
Packit |
577717 |
c) To install PAPI test programs from the build tree:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% make install-tests
|
|
Packit |
577717 |
|
|
Packit |
577717 |
d) To install all of the above in one step from the build tree:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% make install-all
|
|
Packit |
577717 |
|
|
Packit |
577717 |
e) To create a binary kit, papi-<arch>.tgz:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% make dist
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
MORE ABOUT CONFIGURE OPTIONS
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
|
|
Packit |
577717 |
There is an extensive array of options available from the configure
|
|
Packit |
577717 |
command-line. These can differ significantly from version to versions of
|
|
Packit |
577717 |
PAPI. For complete details on the command-line options, use:
|
|
Packit |
577717 |
% ./configure --help
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
DOCUMENTATION BY DOXYGEN
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
|
|
Packit |
577717 |
PAPI now ships with documentation generated by doxygen.
|
|
Packit |
577717 |
Documentation for the public apis can be created by running
|
|
Packit |
577717 |
doxygen from the doc directory.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
More complete documentation of all internal apis and structures can be
|
|
Packit |
577717 |
generated with:
|
|
Packit |
577717 |
% doxygen Doxyfile-html
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Doxygen documentation for the currently released version of PAPI is also
|
|
Packit |
577717 |
available on the website.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
Operating System Specific Installation Steps (In Alphabetical Order by OS)
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
|
|
Packit |
577717 |
AIX - IBM POWER5 and POWER6 and POWER7
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
PAPI is supported on AIX 5.x for POWER5 and POWER6.
|
|
Packit |
577717 |
PAPI is also tested on AIX 6.1 for POWER7.
|
|
Packit |
577717 |
Use ./configure to select the desired make options for your system,
|
|
Packit |
577717 |
specifying the --with_bitmode=32 or --with-bitmode=64 to select wordlength.
|
|
Packit |
577717 |
32 bits is the default.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
1. On AIX 5.x, the bos.pmapi is a product level fileset (part of the OS).
|
|
Packit |
577717 |
However, it is not installed by default. Consult your sysadmin to
|
|
Packit |
577717 |
make sure it is installed.
|
|
Packit |
577717 |
2. Follow the general instructions for installing PAPI.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
WARNING: PAPI requires XLC version 6 or greater.
|
|
Packit |
577717 |
Your version can be determined by running 'lslpp -a -l | grep -i xlc'.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
BG/P
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
BG/P is a cross-compiled environment. The machine on which PAPI is compiled
|
|
Packit |
577717 |
is not the machine on which PAPI runs. To compile PAPI on BG/P, specify the
|
|
Packit |
577717 |
BG/P environment as shown below:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% ./configure --with-OS=bgp
|
|
Packit |
577717 |
% make
|
|
Packit |
577717 |
|
|
Packit |
577717 |
NOTE: ./configure might fail if the cross compiler is not in your path.
|
|
Packit |
577717 |
If that is the case, just add it to your path and everything should work:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
% export PATH=$PATH:/bgsys/drivers/ppcfloor/gnu-linux/bin
|
|
Packit |
577717 |
|
|
Packit |
577717 |
By default this will make a subset of tests in the ctests directory and all
|
|
Packit |
577717 |
tests in the ftests directory.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
There is an additional C test program provided for the BG/P environment
|
|
Packit |
577717 |
that exercises the specific BG/P events and demonstrates how to
|
|
Packit |
577717 |
intermix the PAPI and BG/P UPC native calls. This test program is built with
|
|
Packit |
577717 |
the normal make sequence and can be found in the ctests/bgp directory.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The testing targets in the make file will not work in the BG/P environment.
|
|
Packit |
577717 |
Since BG/P supports multiple queuing systems, you must manually execute
|
|
Packit |
577717 |
individual programs in the ctests and ftests directories to check for successful
|
|
Packit |
577717 |
library creation. You can also manually edit the run_tests.sh script to
|
|
Packit |
577717 |
automate testing for your installation.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Most papi utilities work for BGP, including papi_avail, papi_native_avail, and
|
|
Packit |
577717 |
papi_command_line. Many ctests pass for BGP, but many others produce errors due
|
|
Packit |
577717 |
to the non-traditional architecture of BGP. In particular, PAPI_TOT_CYC always
|
|
Packit |
577717 |
seems to produce 0 counts, although papi_get_virt_usec and papi_get_real_usec
|
|
Packit |
577717 |
appear to work.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The IBM RedPaper: http://www.redbooks.ibm.com/abstracts/redp4256.html provides
|
|
Packit |
577717 |
further discussion about PAPI on BGP along with other performance issues.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
BG/Q
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
Five new components have been added to PAPI to support hardware performance
|
|
Packit |
577717 |
monitoring for the BG/Q platform; in particular the BG/Q network, the I/O system,
|
|
Packit |
577717 |
the Compute Node Kernel in addition to the processing core. There are no specific
|
|
Packit |
577717 |
component configure scripts for L2unit, IOunit, NWunit, CNKunit. In order to
|
|
Packit |
577717 |
configure PAPI for BG/Q, use the following configure options at the papi/src level:
|
|
Packit |
577717 |
% ./configure --prefix=< your_choice > \
|
|
Packit |
577717 |
--with-OS=bgq \
|
|
Packit |
577717 |
--with-bgpm_installdir=/bgsys/drivers/ppcfloor \
|
|
Packit |
577717 |
CC=/bgsys/drivers/ppcfloor/gnu-linux/bin/powerpc64-bgq-linux-gcc \
|
|
Packit |
577717 |
F77=/bgsys/drivers/ppcfloor/gnu-linux/bin/powerpc64-bgq-linux-gfortran \
|
|
Packit |
577717 |
--with-components="bgpm/L2unit bgpm/CNKunit bgpm/IOunit bgpm/NWunit"
|
|
Packit |
577717 |
|
|
Packit |
577717 |
CLE - Cray XT and XE Opteron
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
The Cray XT/XE is a cross-compiled environment. You must specify the
|
|
Packit |
577717 |
perfmon version to configure as shown below.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Before running configure to create the makefile that supports a Cray XT/XE CLE
|
|
Packit |
577717 |
build of PAPI, execute the following module commands:
|
|
Packit |
577717 |
% module purge
|
|
Packit |
577717 |
% module load gcc
|
|
Packit |
577717 |
Note: do not load the programming environment module (e.g. PrgEnv-gnu)
|
|
Packit |
577717 |
but the compiler module (e.g. gcc) as shown above.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Check CLE compute nodes for the version of perfmon2 that it supports:
|
|
Packit |
577717 |
% aprun -b -a xt cat /sys/kernel/perfmon/version
|
|
Packit |
577717 |
|
|
Packit |
577717 |
and use this version when configuring PAPI for a perfmon2 substrate:
|
|
Packit |
577717 |
% configure CFLAGS="-D__crayxt" \
|
|
Packit |
577717 |
--with-perfmon=2.82 --prefix=<install-dir> \
|
|
Packit |
577717 |
--with-virtualtimer=times --with-tls=__thread \
|
|
Packit |
577717 |
--with-walltimer=cycle --with-ffsll --with-shared-lib=no \
|
|
Packit |
577717 |
--with-static-tools
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Configure PAPI for a perf events substrate:
|
|
Packit |
577717 |
% configure CFLAGS="-D__crayxt" \
|
|
Packit |
577717 |
--with-perf-events --with-pe-incdir=<perf-events-hdr-dir> \
|
|
Packit |
577717 |
--with-assumed-kernel=2.6.34 --prefix=<install-dir> \
|
|
Packit |
577717 |
--with-virtualtimer=times --with-tls=__thread \
|
|
Packit |
577717 |
--with-walltimer=cycle --with-ffsll --with-shared-lib=no \
|
|
Packit |
577717 |
--with-static-tools
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Invoke the make accordingly:
|
|
Packit |
577717 |
% make CONFIG_PFMLIB_ARCH_CRAYXT=y CONFIG_PFMLIB_SHARED=n
|
|
Packit |
577717 |
% make CONFIG_PFMLIB_ARCH_CRAYXT=y CONFIG_PFMLIB_SHARED=n install
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The testing targets in the makefile will not work in the XT/XE CLE environment.
|
|
Packit |
577717 |
It is necessary to log into an interactive session and run the tests
|
|
Packit |
577717 |
manually through the job submission system. For example, instead of:
|
|
Packit |
577717 |
% make test
|
|
Packit |
577717 |
use:
|
|
Packit |
577717 |
% aprun -n1 ctests/zero
|
|
Packit |
577717 |
and instead of:
|
|
Packit |
577717 |
% make fulltest
|
|
Packit |
577717 |
use:
|
|
Packit |
577717 |
% ./run_cat_tests.sh
|
|
Packit |
577717 |
after substituting "aprun -n1" for "yod -sz 1" in run_cat_tests.sh.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
FreeBSD - i386 & amd64
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
PAPI requires FreeBSD 6 or higher to work.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Kernel needs some modifications to provide PAPI access to the performance
|
|
Packit |
577717 |
monitoring counters. Simply, add "options HWPMC_HOOKS" and "device hwpmc" in
|
|
Packit |
577717 |
the kernel configuration file. For i386 systems, add also "device apic".
|
|
Packit |
577717 |
(You can obtain more information in hwpmc(4), see NOTE 1 to check the
|
|
Packit |
577717 |
supported HW)
|
|
Packit |
577717 |
|
|
Packit |
577717 |
After this step, just recompile the kernel and boot it.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
FreeBSD 7 (or greater) does not ship with a fortran compiler. To compile
|
|
Packit |
577717 |
fortan tests you will need to install a fortran compiler first (e.g.
|
|
Packit |
577717 |
installing it from /usr/ports/lang/gcc42), and setup the F77 environment
|
|
Packit |
577717 |
variable with the compiler you want to use (e.g. gfortran42).
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Fortran compilers may issue errors due to "Integer too big for its kind *".
|
|
Packit |
577717 |
Add to FFLAGS environment variable a compiler option to use int*8 by default
|
|
Packit |
577717 |
(in gfortran42 it is -fdefault-integer-8).
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Follow the "General Installation" steps.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
NOTE 1:
|
|
Packit |
577717 |
--
|
|
Packit |
577717 |
HWPMC driver supports the following processors: Intel Pentium 2,
|
|
Packit |
577717 |
Intel Pentium Pro, Intel Pentium 3, Intel Pentium M, Intel Celeron,
|
|
Packit |
577717 |
Intel Pentium 4, AMD K7 (AMD Athlon) and AMD K8 (AMD Athlon64 / Opteron).
|
|
Packit |
577717 |
|
|
Packit |
577717 |
FreeBSD 8 also adds support for Core/Core2/Core-i[357]/Atom processors.
|
|
Packit |
577717 |
There is also a patch for FreeBSD 7/7.1 in http://wiki.freebsd.org/PmcTools
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Linux - Xeon Phi [MIC, KNC, Knight's Corner]
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
Full PAPI support of the MIC card requires MPSS Gold Update 2 or above, and a
|
|
Packit |
577717 |
cross-compilation toolchain from Intel, the Intel C compiler is also
|
|
Packit |
577717 |
supported.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The compiler
|
|
Packit |
577717 |
-----------------------------------------------------------------------------
|
|
Packit |
577717 |
* Download one of the MPSS full source bundles at
|
|
Packit |
577717 |
[http://software.intel.com/en-us/articles/intel-manycore-platform-software-stack-mpss]
|
|
Packit |
577717 |
* Untar the download.
|
|
Packit |
577717 |
* Extract gpl/package-cross-k1om.tar.bz2
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Building PAPI - gcc cross compiler
|
|
Packit |
577717 |
-----------------------------------------------------------------------------
|
|
Packit |
577717 |
* Add usr/linux-k1om-4.7/bin or equivalent to your PATH so PAPI can find the
|
|
Packit |
577717 |
cross-build utils. (see above for instructions on acquiring the cross
|
|
Packit |
577717 |
compilation toolchain)
|
|
Packit |
577717 |
* You will need to invoke configure with options:
|
|
Packit |
577717 |
> ./configure --with-mic --host=x86_64-k1om-linux --with-arch=k1om
|
|
Packit |
577717 |
|
|
Packit |
577717 |
This sets up cross-compilation and sets options needed by PAPI.
|
|
Packit |
577717 |
* Run make to build the library.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Building PAPI - icc
|
|
Packit |
577717 |
-----------------------------------------------------------------------------
|
|
Packit |
577717 |
If icc is in your path,
|
|
Packit |
577717 |
> ./configure --with-mic
|
|
Packit |
577717 |
You may have to provide additional configuration options... try
|
|
Packit |
577717 |
> ./configure --with-mic --with-ffsll --with-walltimer=cycle --with-tls=__thread --with-virtualtimer=clock_thread_cputime_id
|
|
Packit |
577717 |
This builds a mic native version of the library.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Offload Code
|
|
Packit |
577717 |
------------
|
|
Packit |
577717 |
To use PAPI in MIC offload code, build a mic-native version of PAPI
|
|
Packit |
577717 |
as detailed above.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The PAPI utility programs can be run on the MIC using the
|
|
Packit |
577717 |
micnativeloadex tool provided by Intel. The MIC events may require
|
|
Packit |
577717 |
additional qualifiers to set the exclude_guest and exclude_host bits
|
|
Packit |
577717 |
to 0 (eventname:mg=1:mh=1). For example, get a list of events
|
|
Packit |
577717 |
available on the MIC by calling:
|
|
Packit |
577717 |
micnativeloadex ./utils/papi_native_avail
|
|
Packit |
577717 |
Then get an event count while setting the appropriate qualifiers
|
|
Packit |
577717 |
micnativeloadex ./utils/papi_command_line -a "CPU_CLK_UNHALTED:mg=1:mh=1"
|
|
Packit |
577717 |
|
|
Packit |
577717 |
To add offload code into your program, wrap the papi.h header as
|
|
Packit |
577717 |
follows:
|
|
Packit |
577717 |
#pragma offload_attribute (push,target(mic))
|
|
Packit |
577717 |
#include "papi.h"
|
|
Packit |
577717 |
#pragma offload_attribute (pop)
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Make PAPI calls from offload code as normal.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Finally add -offload-option,mic,ld,$(path_to_papi)/libpapi.a
|
|
Packit |
577717 |
to your compile incantation or if that does not recognise papi library try
|
|
Packit |
577717 |
-offload-option,mic,compiler,"-lpapi -L<path/to dir containing libpapi.a>" to
|
|
Packit |
577717 |
your compile incantation
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Linux - Itanium II & Montecito
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
PAPI on Itanium Linux links to the perfmon library. The library version and
|
|
Packit |
577717 |
the Itanium version are automatically determined by configure.
|
|
Packit |
577717 |
If you wish to override the defaults, a number of pfm options are available
|
|
Packit |
577717 |
to configure. Use:
|
|
Packit |
577717 |
% ./configure --help
|
|
Packit |
577717 |
to learn more about these options.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Follow the general installation instructions to complete your installation.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
PLATFORM NOTES:
|
|
Packit |
577717 |
The earprofile test fails under perfmon for Itanium II. It has been
|
|
Packit |
577717 |
reconfigured to work on the upcoming perfmon2 interface.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Linux - PPC64 (POWER5, POWER5+, POWER6 and PowerPC970)
|
|
Packit |
577717 |
****************************************************************************
|
|
Packit |
577717 |
Linux/PPC64 requires that the kernel be patched and recompiled with the
|
|
Packit |
577717 |
PerfCtr patch if the kernel is version 2.6.30 or older. The required patches
|
|
Packit |
577717 |
and complete installation instructions are provided in the
|
|
Packit |
577717 |
papi/src/perfctr-2.7.x directory. PPC64 is the ONLY platform that REQUIRES
|
|
Packit |
577717 |
use of PerfCtr 2.7.x.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*- IF YOU HAVE ALREADY PATCHED YOUR KERNEL AND/OR INSTALLED PERFCTR -*
|
|
Packit |
577717 |
|
|
Packit |
577717 |
WARNING: You should always use a PerfCtr distribution that has been distributed
|
|
Packit |
577717 |
with a version of PAPI or your build will fail. The reason for this is that
|
|
Packit |
577717 |
PAPI builds a shared library of the Perfctr runtime, on which libpapi.so
|
|
Packit |
577717 |
depends. PAPI also depends on the .a file, which it decomposes into component
|
|
Packit |
577717 |
objects files and includes in the libpapi.a file for convenience. If you
|
|
Packit |
577717 |
install a new perfctr, even a shared library, YOU MUST REBUILD PAPI to get
|
|
Packit |
577717 |
a proper, working libpapi.a.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
There are several options in configure to allow you to specify your perfctr
|
|
Packit |
577717 |
version and location. Use:
|
|
Packit |
577717 |
% ./configure --help
|
|
Packit |
577717 |
to learn more about these options.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Follow the general installation instructions to complete your installation.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Linux Perf Events ( with kernel 2.6.32 and newer )
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Performance counter support has been merged as the "Perf Events"
|
|
Packit |
577717 |
subsystem as of Linux 2.6.32. This means that PAPI can be built
|
|
Packit |
577717 |
without patching the kernel on new enough systems.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Perf Events support is new, and certain functionality does not work.
|
|
Packit |
577717 |
If you need any of the functionality listed below, we recommend
|
|
Packit |
577717 |
you install the PerfCtr patchset and use that in conjunction with PAPI.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
+ PAPI requires at least Linux kernel 2.6.32, as the earlier 2.6.31
|
|
Packit |
577717 |
version had some significant API changes.
|
|
Packit |
577717 |
+ Kernels before 2.6.33 have extra overhead when determining
|
|
Packit |
577717 |
whether events conflict or not.
|
|
Packit |
577717 |
+ Counter multiplexing is handled by PAPI (rather than perf_events)
|
|
Packit |
577717 |
on kernels before 2.6.33 due to a bug in the kernel perf_events code.
|
|
Packit |
577717 |
+ Nehalem EX support requires kernel 2.6.34 or newer.
|
|
Packit |
577717 |
+ Pentium 4 support requires kernel 2.6.35 or newer.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The PAPI configure script should auto-detect the availability of
|
|
Packit |
577717 |
Perf Events on new enough distributions (this mainly requires
|
|
Packit |
577717 |
that perf_event.h be available in /usr/include/linux)
|
|
Packit |
577717 |
|
|
Packit |
577717 |
On older distributions (even ones that include the 2.6.32 kernel)
|
|
Packit |
577717 |
the perf_event.h file might not be there. One fix is to install
|
|
Packit |
577717 |
your distributions linux kernel headers package, which is often
|
|
Packit |
577717 |
an optional package not installed by default.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If you cannot install the kernel headers, you can obtain the
|
|
Packit |
577717 |
perf_event.h file from your kernel and run configure as such:
|
|
Packit |
577717 |
./configure --with-pe-incdir=INCDIR
|
|
Packit |
577717 |
replacing INCDIR with the directory that perf_event.h is in.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Linux PerfCtr (requires patching the kernel)
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
When using Linux kernels before 2.6.32 the kernel must be patched with
|
|
Packit |
577717 |
the PerfCtr patch set. (This patchset can also be used on more recent
|
|
Packit |
577717 |
kernels if the support provided by Perf Events is not enough for your
|
|
Packit |
577717 |
workload). The required patches and complete installation instructions
|
|
Packit |
577717 |
are provided in the papi/src/perfctr-x.y directory. Please see the INSTALL
|
|
Packit |
577717 |
file in that directory.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Do not forget, you also need to build your kernel with APIC support in order
|
|
Packit |
577717 |
for hardware overflow to work. This is very important for accurate statistical
|
|
Packit |
577717 |
profiling ala gprof via the hardware counters.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
So, when you configure your kernel to build with PERFCTR as above, make
|
|
Packit |
577717 |
sure you turn on APIC support in the "Processor type and features" section.
|
|
Packit |
577717 |
This should be enabled by default if you are on an SMP, but it is disabled
|
|
Packit |
577717 |
by default on a UP.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
In our 2.4.x kernels:
|
|
Packit |
577717 |
> grep PIC /usr/src/linux/.config
|
|
Packit |
577717 |
/usr/src/linux/.config:CONFIG_X86_GOOD_APIC=y
|
|
Packit |
577717 |
/usr/src/linux/.config:CONFIG_X86_UP_APIC=y
|
|
Packit |
577717 |
/usr/src/linux/.config:CONFIG_X86_UP_IOAPIC=y
|
|
Packit |
577717 |
/usr/src/linux/.config:CONFIG_X86_LOCAL_APIC=y
|
|
Packit |
577717 |
/usr/src/linux/.config:CONFIG_X86_IO_APIC=y
|
|
Packit |
577717 |
|
|
Packit |
577717 |
You can verify the APIC is working after rebooting with the new kernel
|
|
Packit |
577717 |
by running the 'perfex -i' command found in the perfctr/examples/perfex
|
|
Packit |
577717 |
directory.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
PAPI on x86 assumes PerfCtr 2.6.x. NOTE: THE VERSIONS OF PERFCTR DO NOT
|
|
Packit |
577717 |
CORRESPOND TO LINUX KERNEL VERSIONS.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*- IF YOU HAVE ALREADY PATCHED YOUR KERNEL AND/OR INSTALLED PERFCTR -*
|
|
Packit |
577717 |
|
|
Packit |
577717 |
WARNING: You should always use a PerfCtr distribution that has been distributed
|
|
Packit |
577717 |
with a version of PAPI or your build may fail. Newer versions with backward
|
|
Packit |
577717 |
compatibility may also work. PAPI builds a shared library of the Perfctr
|
|
Packit |
577717 |
runtime, on which libpapi.so depends. PAPI also depends on the .a file,
|
|
Packit |
577717 |
which it decomposes into component objects files and includes in the libpapi.a
|
|
Packit |
577717 |
file for convenience. If you install a new PerfCtr, even a shared library,
|
|
Packit |
577717 |
YOU MUST REBUILD PAPI to get a proper, working libpapi.a.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
There are several options in configure to allow you to specify your perfctr
|
|
Packit |
577717 |
version and location. Use:
|
|
Packit |
577717 |
% ./configure --help
|
|
Packit |
577717 |
to learn more about these options.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Follow the general installation instructions to complete your installation.PERFCT
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*- IF PERFCTR IS INSTALLED BUT PAPI FAILS TO INITIALIZE -*
|
|
Packit |
577717 |
|
|
Packit |
577717 |
You may be running udev, which is not smart enough to know the permissions of
|
|
Packit |
577717 |
dynamically created devices. To fix this, find your udev/devices directory,
|
|
Packit |
577717 |
often /lib/udev/devices or /etc/udev/devices and perform the following actions:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
mknod perfctr c 10 182
|
|
Packit |
577717 |
chmod 644 perfctr
|
|
Packit |
577717 |
|
|
Packit |
577717 |
On Ubuntu 6.06 (and probably other debian distros), add a line to
|
|
Packit |
577717 |
/etc/udev/rules.d/40-permissions.rules like this:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
KERNEL=="perfctr", MODE="0666"
|
|
Packit |
577717 |
|
|
Packit |
577717 |
On SuSE, you may need to add something like the following to
|
|
Packit |
577717 |
/etc/udev/rules.d/50-udev-default.rules:
|
|
Packit |
577717 |
(SuSE does not have the 40-permissions.rules file in it.]
|
|
Packit |
577717 |
|
|
Packit |
577717 |
# cpu devices
|
|
Packit |
577717 |
KERNEL=="cpu[0-9]*", NAME="cpu/%n/cpuid"
|
|
Packit |
577717 |
KERNEL=="msr[0-9]*", NAME="cpu/%n/msr"
|
|
Packit |
577717 |
KERNEL=="microcode", NAME="cpu/microcode", MODE="0600"
|
|
Packit |
577717 |
KERNEL=="perfctr", NAME="perfctr", MODE="0644"
|
|
Packit |
577717 |
|
|
Packit |
577717 |
These lines tell udev to always create the device file with the appropriate permissions.
|
|
Packit |
577717 |
Use 'perfex -i' from the perfctr distribution to test this fix.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
PLATFORM NOTES:
|
|
Packit |
577717 |
Opteron fails the matrix-hl test because the default definition of PAPI_FP_OPS
|
|
Packit |
577717 |
overcounts speculative floating point operations.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Solaris 8 - Ultrasparc
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
The only requirement for Solaris is that you must be running version 2.8 or
|
|
Packit |
577717 |
newer. As long as that requirement is met, no additional steps are required
|
|
Packit |
577717 |
to install PAPI and you can follow the general installation guide.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Solaris 10 - UltraSPARC T2/Niagara 2
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
PAPI supports the Niagara 2 on Solaris 10. The substrate offers support for
|
|
Packit |
577717 |
common basic operations like adding/reading/etc and the advanced features
|
|
Packit |
577717 |
multiplexing (see below), overflow handling and profiling. The implementation
|
|
Packit |
577717 |
for Solaris 10 is based on libcpc 2, which offers access to the underlying
|
|
Packit |
577717 |
performance counters. Performance counters for the UltraSPARC architecture
|
|
Packit |
577717 |
are described in the UltraSPARC architecture manual in general with detailed
|
|
Packit |
577717 |
descriptions in the actual processor manual. In case of this substrate the
|
|
Packit |
577717 |
documentation for performance counters can be found at:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
- http://www.opensparc.net/publications/specifications/
|
|
Packit |
577717 |
|
|
Packit |
577717 |
In order to install PAPI on this platform make sure the packages SUNWcpc and
|
|
Packit |
577717 |
SUNWcpcu are installed. For the compilation Sun Studio 12 was used while the
|
|
Packit |
577717 |
substrate has been developed. GNU GCC has not been tested and would require
|
|
Packit |
577717 |
to modify the makefiles Makefile.solaris-niagara2 (32 bit) and
|
|
Packit |
577717 |
Makefile.solaris-niagara2-64bit (64 bit).
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The steps required for installation are as follows:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
./configure --with-bitmode=[32|64] --prefix=/is/optional
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If no --with-bitmode parameter is present a default of
|
|
Packit |
577717 |
32 bit is assumed.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If no --prefix is used, a default of /usr/local is assumed.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
make
|
|
Packit |
577717 |
make install
|
|
Packit |
577717 |
|
|
Packit |
577717 |
If you want to link your application against your installation you should
|
|
Packit |
577717 |
make sure to include at least the following linker options:
|
|
Packit |
577717 |
|
|
Packit |
577717 |
-lpapi -lcpc
|
|
Packit |
577717 |
|
|
Packit |
577717 |
PLEASE NOTE: This is the first revision of Niagara 2/libcpc 2/Solaris 10
|
|
Packit |
577717 |
support and needs further testing! Contributions, especially for the preset
|
|
Packit |
577717 |
definitions, would be very appreciated.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
MULTIPLEXING: As the Niagara 2 offers no native event to count the cycles
|
|
Packit |
577717 |
elapsed, a "synthetic event" was created offering access to the cycle count.
|
|
Packit |
577717 |
This event is neither as accurate as the native events, nor it should be
|
|
Packit |
577717 |
used for anything else than the multiplexing mode, which needs the cycle
|
|
Packit |
577717 |
count in order to work. Therefore multiplexing and the preset PAPI_TOT_CYC
|
|
Packit |
577717 |
should be only used with caution. BEWARE OF WRONG COUNTER RESULTS!
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Windows XP/2000/Server 2003 - Intel Pentium III or AMD Athlon / Opteron
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
Please use PAPI 3.7 (http://icl.cs.utk.edu/projects/papi/downloads/papi-3.7.2.tar.gz)
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The Windows source tree comes with Microsoft Visual Studio Version 8 projects
|
|
Packit |
577717 |
to build a graphical shell application, the PAPI library as a DLL, a kernel
|
|
Packit |
577717 |
driver to provide access to the counters, and a collection of C test programs.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The WinPMC driver must be installed with administrator privileges. See the
|
|
Packit |
577717 |
winpmc.html file in the papi/win2k/winpmc directory for details on building
|
|
Packit |
577717 |
and installing this driver.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The general installation instructions are irrelevant for Windows.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Other Platforms
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
PAPI can be compiled and installed on most platforms that have GNU compilers
|
|
Packit |
577717 |
regardless of operating system or hardware. This includes, for example,
|
|
Packit |
577717 |
Macintosh systems running recent versions of OSX. However, PAPI can only
|
|
Packit |
577717 |
provide access to the CPU hardware counters on platforms that are directly
|
|
Packit |
577717 |
supported. Unsupported platforms will run, buttony provide basic timing
|
|
Packit |
577717 |
functions, and potential access to some non-cpu components.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
CREATING AND RUNNING COMPONENTS
|
|
Packit |
577717 |
*****************************************************************************
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Basic instructions on how to create a new component can be found in
|
|
Packit |
577717 |
src/components/README. The components directory contains several components
|
|
Packit |
577717 |
developed by the PAPI team along with a simple yet functional "example"
|
|
Packit |
577717 |
component which can be used as a guide to aid third-party developers.
|
|
Packit |
577717 |
Assuming components are developed according to the specified guidelines,
|
|
Packit |
577717 |
they will function within the PAPI framework without requiring any changes
|
|
Packit |
577717 |
to PAPI source code.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Before running any component that requires configuration, the configure
|
|
Packit |
577717 |
script for that component must be executed in order to generate the
|
|
Packit |
577717 |
Makefile which contains the configuration settings. Normally, the script
|
|
Packit |
577717 |
will only need to be executed once. Depending on the component, configure
|
|
Packit |
577717 |
may require that one or more configuration settings be specified by the user.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The components to be added to PAPI are specified during the configuration of
|
|
Packit |
577717 |
PAPI by adding the --with-components=<component list> command line option to
|
|
Packit |
577717 |
configure. For example, to add the acpi, lustre, and net components, the
|
|
Packit |
577717 |
option would be:
|
|
Packit |
577717 |
% ./configure --with-components="acpi lustre net"
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Attempting to add a component to PAPI which requires configuration and has
|
|
Packit |
577717 |
not been configured will result in a compilation error because the PAPI
|
|
Packit |
577717 |
build environment will be unable to find the Makefile for that component.
|