New Components

The first step in creating a new component is to create a new directory inside the components directory. The naming convention is to use lower case letters for the directory name. At a minimum, this directory will contain all header files and source code required to build the component along with a Rules file which contains the build rules and compiler settings specific to that component. The Rules file must be named using the format Rules.x where x is the name of the directory. There are no restrictions on the naming of header or source files.

If the component requires user input for any of the compiler settings, then the component directory will also contain the files required to generate a configure script using autoconf. The configure script can be used to generate a Makefile which will the Rules file will include. The file configure.in is required in order to generate configure. It should specify that the Makefile that gets generated is named Makefile.x where x is the name of the component directory. Finally, configure also needs an input file to create the Makefile. That file must be named Makefile.x.in where x is the name of the component directory.

The following comments apply to components that are under source control. Although configure is generated, it requires the correct version of autoconf. For that reason, configure should be placed under source control. The generated Makefile should not be placed under source control.

In summary, the additional files required for configuration based on user input are: configure.in, configure (generated by autoconf), Makefile.x.in, and Makefile.x (generated by configure) where x is the name of the component directory.

There is one final very important naming convention that applies to components. The array of function pointers that the component defines must use the naming convention papi_vector_t _x_vector where x is the name of the component directory.

Adding tests to the components: -------------------------------

In order to add tests to a component that will be compiled together with PAPI when typing 'make' (as well as cleaned up when 'make clean' or 'make clobber' is typed), the following steps need to be carried out:

1. create a directory with name 'tests' in the specific component directory 2. add your test files and a Makefile to the 'tests' directory (see the example test and Makefile in components/example/tests) 3. The components/< component >/tests/Makefile has to have a rule with the name '< component >_tests'; e.g. for tests added to the example component, the name of the rule would be 'example_tests'. See: TESTS = HelloWorld example_tests: 4. Include components/Makefile_comp_tests to your component test Makefile (see components/example/tests/Makefile for more details)

NOTE: there is no need to modify any PAPI code other than adding your tests and a Makefile to your component and follow step 1 to 4 listed above.

Components

example/

lmsensors/ The PAPI lmsensors component requires lmsensors version >= 3.0.0.

lustre/

mx/

net/

cuda/ The PAPI CUDA component is a hardware performance counter measurement technology for the NVIDIA CUDA platform which provides access to the hardware counters inside the GPU. PAPI CUDA is based on CUPTI support in the NVIDIA driver library. In any environment where the CUPTI-enabled driver is installed, the PAPI CUDA component can provide detailed performance counter information regarding the execution of GPU kernels. NOTE: In order to disable and destroy the CUDA eventGroup properly, the user has to call PAPI_cleanup_eventset( EventSet ) before calling PAPI_shutdown() in the application. This is important since it also frees the performance monitoring hardware on the GPU.

How to install PAPI with the CUDA component? -------------------------------------------- The PAPI CUDA component requires CUDA version >= 4.0 as well as the CUPTI library. CUPTI is released with the CUDA Tools SDK.

Before running the CUDA component, the configure script for the CUDA component must be executed in order to generate the Makefile which contains the configuration settings. This script needs to be executed only once. The CUDA configure script requires the user to specify the following configuration settings: % cd < latest-papi-version >/src/components/cuda % ./configure --with-cuda_incdir=< CUDA INCLUDE PATH > --with-cupti_incdir=< CUPTI INCLUDE PATH > --with-cupti_libdir=< CUPTI LIBRARY PATH >

Furthermore, the CUDA component will be added to PAPI during the configuration of PAPI by adding the '--with-components=cuda' command line option to configure. % ./configure --prefix=< your_choice > --with-components=cuda

Attempting to add the CUDA component to PAPI - without running the configure script for the CUDA component first - will result in a compilation error because the PAPI build environment will be unable to find the Makefile for the CUDA component.

For general information on how to create and run components, the user is referred to the INSTALL.txt section "CREATING AND RUNNING COMPONENTS".

infiniband/ These files have the source code for a component that enables PAPI-C to access hardware monitoring counters for InfiniBand devices through the OFED library. Since a new interface was introduced with OFED version 1.4 (released Dec 2008), the current InfiniBand component does not support OFED versions < 1.4.

coretemp_freebsd/ This component is intended to access CPU On-Die Thermal Sensors in the Intel Core architecture in a FreeBSD machine using the coretemp.ko kernel module. The returned values represent Kelvin dedegrees.

vmware/

To make the generic VMware component do --with-vmware_incdir=< path_to_VMWare_Guest_SDK > from the component directory.

For further information see the VMwareComponentDocument.txt file in the component directory, or the ComponentGuide pdf file.

bgpm/ Five new components have been added to PAPI to support hardware performance monitoring for the BG/Q platform; in particular the BG/Q network, the I/O system, the Compute Node Kernel in addition to the processing core. There are no specific component configure scripts for L2unit, IOunit, NWunit, CNKunit. In order to configure PAPI for BG/Q, use the following configure options at the papi/src level: % ./configure --prefix=< your_choice > \ --with-OS=bgq \ --with-bgpm_installdir=/bgsys/drivers/ppcfloor \ CC=/bgsys/drivers/ppcfloor/gnu-linux/bin/powerpc64-bgq-linux-gcc \ F77=/bgsys/drivers/ppcfloor/gnu-linux/bin/powerpc64-bgq-linux-gfortran \ --with-components="bgpm/L2unit bgpm/CNKunit bgpm/IOunit bgpm/NWunit"