/*
* File: INSTALL.txt
* CVS: $Id: INSTALL.txt,v 1.42 2010/01/12 21:12:17 terpstra Exp $
* Author: Kevin London
* london@cs.utk.edu
* Mods: Dan Terpstra
* terpstra@cs.utk.edu
* Mods: Philip Mucci
* mucci@cs.utk.edu
* Mods: <your name here>
* <your email address>
*/
*****************************************************************************
HOW TO INSTALL PAPI ONTO YOUR SYSTEM
*****************************************************************************
On some of the systems that PAPI supports, you can install PAPI right
out of the box without any additional setup. Others require drivers or
patches to be installed first.
The general installation steps are below, but first find your particular
Operating System's section for any additional steps that may be necessary.
NOTE: the configure and make files are located in the papi/src directory.
General Installation
1. % ./configure
% make
2. Check for errors.
a) Run a simple test case: (This will run ctests/zero)
% make test
If you get good counts, you can optionally run all the test programs
with the included test harness. This will run the tests in quiet mode,
which will print PASSED, FAILED, or SKIPPED. Tests are SKIPPED if the
functionality being tested is not supported by that platform.
% make fulltest (This will run ./run_tests.sh)
To run the tests in verbose mode:
% ./run_tests.sh -v
3. Create a PAPI binary distribution or install PAPI directly.
a) To install PAPI libraries and header files from the build tree:
% make install
b) To install PAPI manual pages from the build tree:
% make install-man
c) To install PAPI test programs from the build tree:
% make install-tests
d) To install all of the above in one step from the build tree:
% make install-all
e) To create a binary kit, papi-<arch>.tgz:
% make dist
*****************************************************************************
MORE ABOUT CONFIGURE OPTIONS
*****************************************************************************
Beginning with PAPI 3.5.0, there is an extensive array of options available
from the configure command-line. These options select default directories,
32- or 64-bit library modes, driver versions, compiler settings and more.
For complete details on the command-line options:
% ./configure --help
*****************************************************************************
Operating System Specific Installation Steps (In Alphabetical Order by OS)
*****************************************************************************
AIX - IBM POWER3, POWER4, POWER5
*****************************************************************************
PAPI is supported on AIX 5.x for POWER3, POWER4 and POWER5.
Use ./configure to select the desired make options for your system,
specifying the --with_bitmode=32 or --with-bitmode=64 to select wordlength.
32 bits is the default.
1. On AIX 5.x, the bos.pmapi is a product level fileset (part of the OS).
However, it is not installed by default. Consult your sysadmin to
make sure it is installed.
2. Follow the general instructions for installing PAPI.
WARNING: PAPI requires XLC version 6 or greater.
Your version can be determined by running 'lslpp -a -l | grep -i xlc'.
BG/L
*****************************************************************************
BG/L is a cross-compiled environment. The machine on which PAPI is compiled
is not the machine on which PAPI runs. To compile PAPI on BG/L, specify the
BG/L environment as shown below:
% ./configure --with-OS=bgl
% make
The testing targets in the make file will not work in the BG/L environment.
Since BG/L supports multiple queueing systems, you must manually execute
programs in the ctests and ftests directories to check for successful
library creation. You can also manually edit the run_tests.sh script to
automate testing for your installation.
WARNING: ./configure might fail if the cross compiler is not in your path.
If that is the case, just add it to your path
and everything should work.
BG/P
*****************************************************************************
BG/P is a cross-compiled environment. The machine on which PAPI is compiled
is not the machine on which PAPI runs. To compile PAPI on BG/P, specify the
BG/P environment as shown below:
% ./configure --with-OS=bgp
% make
NOTE: ./configure might fail if the cross compiler is not in your path.
If that is the case, just add it to your path and everything should work:
% export PATH=$PATH:/bgsys/drivers/ppcfloor/gnu-linux/bin
By default this will make a subset of tests in the ctests directory and all
tests in the ftests directory.
There is an additional C test program provided for the BG/P environment
that exercises the specific BG/P events and demonstrates how to
intermix the PAPI and BG/P UPC native calls. This test program is built with
the normal make sequence and can be found in the ctests/bgp directory.
The testing targets in the make file will not work in the BG/P environment.
Since BG/P supports multiple queueing systems, you must manually execute
individual programs in the ctests and ftests directories to check for successful
library creation. You can also manually edit the run_tests.sh script to
automate testing for your installation.
Most papi utilities work for BGP, including papi_avail, papi_native_avail, and
papi_command_line. Many ctests pass for BGP, but many others produce errors due
to the non-traditional architecture of BGP. In particular, PAPI_TOT_CYC always
seems to produce 0 counts, although papi_get_virt_usec and papi_get_real_usec
appear to work.
The IBM RedPaper: http://www.redbooks.ibm.com/abstracts/redp4256.html provides
further discussion about PAPI on BGP along with other performance issues.
CLE - Cray XT4/XT5 Opteron
*****************************************************************************
The Cray XT4/5 is a cross-compiled environment. You must specify the
perfmon version to configure as shown below.
Before running configure to create the makefile that supports a Cray XT CLE
build of PAPI, execute the following module commands:
% module purge
% module load Base-opts
% module load pgi
Note: do not load the programming environment module (e.g. PrgEnv-pgi)
but the compiler module (e.g. pgi) as shown above.
Check CLE compute nodes for the version of perfmon2 that it supports:
% aprun -b -a xt cat /sys/kernel/perfmon/version
and use this version when configuring PAPI:
% configure --with-perfmon=2.3 --prefix=<install-dir>
Example ORNL's Jaguar system:
To build PAPI for the compute nodes on ORNL's Jaguar system, you should use
the Cray wrapper 'cc'. The wrappers will call the appropriate compiler which
will use the appropriate header files and link against the appropriate
libraries.
% configure --with-perfmon=2.3 --prefix=<install-dir> CC=cc
The testing targets in the makefile will not work in the XT CLE environment.
It is necessary to log into an interactive session and run the tests
manually through the job submission system. For example, instead of:
% make test
use:
% aprun -n1 ctests/zero
and instead of:
% make fulltest
use:
% ./run_cat_tests.sh
after substituting "aprun -n1" for "yod -sz 1" in run_cat_tests.sh.
Linux - Itanium I & II
*****************************************************************************
PAPI on Itanium Linux links to the perfmon library. The library version and
the Itanium version are automatically determined by configure.
If you wish to override the defaults, a number of pfm options are available
to configure. Use:
% ./configure --help
to learn more about these options.
Follow the general installation instructions to complete your installation.
PLATFORM NOTES:
The earprofile test fails under perfmon for Itanium I and II. It has been
reconfigured to work on the upcoming perfmon2 interface.
Linux - Itanium Montecito
*****************************************************************************
A preliminary implementation of PAPI for Montecito is available in this
release. It can be configured using either libpfm or the beta perfmon2
implementation. Your operating system will require a kernel patch to use
perfmon2. Contact the PAPI team if you are interested in experimenting
with this implementation. CAVEAT EMPTOR.
Linux - PPC64 (POWER5, POWER4, and PowerPC970)
****************************************************************************
Linux/PPC64 requires that the kernel be patched and recompiled with the
PerfCtr patch. The required patches and complete installation instructions
are provided in the papi/src/perfctr-2.7.x directory. PPC64 is the ONLY
platform that REQUIRES use of PerfCtr 2.7.x.
*- IF YOU HAVE ALREADY PATCHED YOUR KERNEL AND/OR INSTALLED PERFCTR -*
WARNING: You should always use a PerfCtr distribution that has been distributed
with a version of PAPI or your build will fail. The reason for this is that
PAPI builds a shared library of the Perfctr runtime, on which libpapi.so
depends. PAPI also depends on the .a file, which it decomposes into component
objects files and includes in the libpapi.a file for convenience. If you
install a new perfctr, even a shared library, YOU MUST REBUILD PAPI to get
a proper, working libpapi.a.
There are several options in configure to allow you to specify your perfctr
version and location. Use:
% ./configure --help
to learn more about these options.
Follow the general installation instructions to complete your installation.
Linux/x86 - Intel Pentium, Core and AMD Athlon, Opteron
*****************************************************************************
Linux/x86 requires that the kernel be patched and recompiled with the PerfCtr
patch. The required patches and complete installation instructions are
provided in the papi/src/perfctr-x.y directory. Please see the INSTALL file
in that directory.
Do not forget, you also need to build your kernel with APIC support in order
for hardware overflow to work. This is very important for accurate statistical
profiling ala gprof via the hardware counters.
So, when you configure your kernel to build with PERFCTR as above, make
sure you turn on APIC support in the "Processor type and features" section.
This should be enabled by default if you are on an SMP, but it is disabled
by default on a UP.
In our 2.4.x kernels:
> grep PIC /usr/src/linux/.config
/usr/src/linux/.config:CONFIG_X86_GOOD_APIC=y
/usr/src/linux/.config:CONFIG_X86_UP_APIC=y
/usr/src/linux/.config:CONFIG_X86_UP_IOAPIC=y
/usr/src/linux/.config:CONFIG_X86_LOCAL_APIC=y
/usr/src/linux/.config:CONFIG_X86_IO_APIC=y
You can verify the APIC is working after rebooting with the new kernel
by running the 'perfex -i' command found in the perfctr/examples/perfex
directory.
PAPI on x86 assumes PerfCtr 2.6.x. You can change this with the
'--with-perfctr=<5,6,7> option to ./configure. THIS IS NOT ADVISED.
PerfCtr 2.7.x is supported only for PPC64.
NOTE: THE VERSIONS OF PERFCTR DO NOT CORRESPOND TO LINUX KERNEL VERSIONS.
*- IF YOU HAVE ALREADY PATCHED YOUR KERNEL AND/OR INSTALLED PERFCTR -*
WARNING: You should always use a PerfCtr distribution that has been distributed
with a version of PAPI or your build may fail. Newer versions with backward
compatibility may also work. PAPI builds a shared library of the Perfctr
runtime, on which libpapi.so depends. PAPI also depends on the .a file,
which it decomposes into component objects files and includes in the libpapi.a
file for convenience. If you install a new PerfCtr, even a shared library,
YOU MUST REBUILD PAPI to get a proper, working libpapi.a.
There are several options in configure to allow you to specify your perfctr
version and location. Use:
% ./configure --help
to learn more about these options.
Follow the general installation instructions to complete your installation.PERFCT
*- IF PERFCTR IS INSTALLED BUT PAPI FAILS TO INITIALIZE -*
You may be running udev, which is not smart enough to know the permissions of
dynamically created devices. To fix this, find your udev/devices directory,
often /lib/udev/devices or /etc/udev/devices and perform the following actions:
mknod perfctr c 10 182
chmod 644 perfctr
On Ubuntu 6.06 (and probably other debian distros), add a line to
/etc/udev/rules.d/40-permissions.rules like this:
KERNEL=="perfctr", MODE="0666"
On SuSE, you may need to add something like the following to
/etc/udev/rules.d/50-udev-default.rules:
(SuSE does not have the 40-permissions.rules file in it.]
# cpu devices
KERNEL=="cpu[0-9]*", NAME="cpu/%n/cpuid"
KERNEL=="msr[0-9]*", NAME="cpu/%n/msr"
KERNEL=="microcode", NAME="cpu/microcode", MODE="0600"
KERNEL=="perfctr", NAME="perfctr", MODE="0644"
These lines tell udev to always create the device file with the appropriate permissions.
Use 'perfex -i' from the perfctr distribution to test this fix.
PLATFORM NOTES:
Opteron fails the matrix-hl test because the default definition of PAPI_FP_OPS
overcounts speculative floating point operations.
MIPS - IRIX 6.5
*****************************************************************************
No additional steps are required to install PAPI on IRIX. Follow the
general installation guide, and everything should work.
Solaris 8 - Ultrasparc
*****************************************************************************
The only requirement for Solaris is that you must be running version 2.8 or
newer. As long as that requirement is met, no additional steps are required
to install PAPI and you can follow the general installation guide.
Solaris 10 - UltraSPARC T2/Niagara 2
*****************************************************************************
PAPI supports the Niagara 2 on Solaris 10 as of PAPI 3.7.0. The substrate
offers support for common basic operations like adding/reading/etc and the
advanced features multiplexing (see below), overflow handling and profiling.
The implementation for Solaris 10 is based on libcpc 2, which offers access
to the underlying performance counters. Performance counters for the
UltraSPARC architecture are described in the UltraSPARC architecture manual
in general with detailed descriptions in the actual processor manual. In
case of this substrate the documentation for performance counters can be
found at:
- http://www.opensparc.net/publications/specifications/
In order to install PAPI on this platform make sure the packages SUNWcpc and
SUNWcpcu are installed. For the compilation Sun Studio 12 was used while the
substrate has been developed. GNU GCC has not been tested and would require
to modify the makefiles Makefile.solaris-niagara2 (32 bit) and
Makefile.solaris-niagara2-64bit (64 bit).
The steps required for installation are as follows:
./configure --with-bitmode=[32|64] --prefix=/is/optional
If no --with-bitmode parameter is present a default of
32 bit is assumed.
If no --prefix is used, a default of /usr/local is assumed.
make
make install
If you want to link your application against your installation you should
make sure to include at least the following linker options:
-lpapi -lcpc
PLEASE NOTE: This is the first revision of Niagara 2/libcpc 2/Solaris 10
support and needs further testing! Contributions, especially for the preset
definitions, would be very appreciated.
MULTIPLEXING: As the Niagara 2 offers no native event to count the cycles
elapsed, a "synthetic event" was created offering access to the cycle count.
This event is neither as accurate as the native events, nor it should be
used for anything else than the multiplexing mode, which needs the cycle
count in order to work. Therefore multiplexing and the preset PAPI_TOT_CYC
should be only used with caution. BEWARE OF WRONG COUNTER RESULTS!
Windows XP/2000/Server 2003 - Intel Pentium III or AMD Athlon / Opteron
*****************************************************************************
PAPI 3.5 for Windows runs on Pentium III, Athlon and Opteron, for
Windows 2000, Windows XP and Windows Server 2003.
Earlier versions of PAPI for Windows provided a self-installing executable.
That is not the case with the current release.
The Windows source tree comes with Microsoft Visual Studio Version 8 projects
to build a graphical shell application, the PAPI library as a DLL, a kernel
driver to provide access to the counters, and a collection of C test programs.
The WinPMC driver must be installed with administrator privileges. See the
winpmc.html file in the papi/win2k/winpmc directory for details on building
and installing this driver.
The general installation instructions are irrelevant for Windows.
