README

Go to the documentation of this file.

/** 
* @file:   README
* @author: Brian Sheely
*          bsheely@eecs.utk.edu
* @defgroup papi_components Components
* @brief Component Readme file
*/
 
/** @page component_readme Component Readme 
@section Creating 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 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 and installed when 'make install-all' or 'make install-tests' is called), 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: $(TESTS)
    4. Include components/Makefile_comp_tests to your component test Makefile
    (see components/example/tests/Makefile for more details)
    5. You may also define 'clean' and/or 'install' targets (as shown in the example) which will be called during those parts of the build.  If these targets are missing it will just print a message reporting the missing target and continue.
 
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.
 
 
 
@section Component Specific Information
 
Some components under source control have additional information specific to their build process or operation. That information can be found in a README file inside the component directory. If the README doesn't exist, no special information is necessary.
 
*/
 
/*-----------------------------------------------------------------------------
  Notes on components as of February 2019 release 5.7.0.0.
appio
bgpm                          IBM Blue Gene Q specific. 
coretemp                      Linux HW Monitor, temperature and other info.
coretemp_freebsd              FREEBSD version of HW Monitor, temperature and other info.
cuda                          CUDA events and metrics via NVIDIA CUpti interfaces.
emon                          IBM Blue Gene Q specific.
example                       Simple example component. 
host_micpower                 Requires its own configure and Knights Corner (KNC) architecture.
infiniband                    Linux Infiniband stats using the sysfs interface. For OFED version < 1.4.
infiniband_umad               Requires its own configure. Infiniband stats for OFED version >= 1.4.
libmsr                        Requires its own configure and libmsr from LLNL, for power (RAPL) read/write.
lmsensors                     Requires its own configure.
lustre                        lustre filesystem stats
micpower                      For reading power on Intel XEON PHI. (MIC) 
mx                            Myricom MX (Myrinet Express) statistics.
net                           Linux network driver statistics
nvml                          Requires its own configure; monitors NVIDIA hardware (power, temp, fan speed, etc).
pcp                           Performance Co-Pilot interface.
perfctr                       OLD, only used for Linux before 2.6.31.
perfctr_ppc                   OLD, only used for Linux before 2.6.31.
perf_event                    Linux perf_event CPU counters
perf_event_uncore             Linux perf-event CPU uncore and Northbridge
perfmon2                      OLD, only used for Linux before 2.6.31.
perfmon_ia64                  OLD, only used for Linux before 2.6.31.
powercap                      Linux Powercap energy measurements.
rapl                          Linux RAPL energy measurments.
stealtime                     Stealtime Filesystem statistics. 
vmware                        Requires its own configure. Only runs in the VMWARE virtual environment.
 
*/