3 * @author: Brian Sheely
5 * @defgroup papi_components Components
6 * @brief Component Readme file
9 /** @page component_readme Component Readme
10 @section Creating New Components
12 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.
14 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.
16 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.
18 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.
20 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.
23 Adding tests to the components:
24 -------------------------------
26 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:
28 1. create a directory with name 'tests' in the specific component directory
29 2. add your test files and a Makefile to the 'tests' directory (see the example test and Makefile in components/example/tests)
30 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:
32 example_tests: $(TESTS)
33 4. Include components/Makefile_comp_tests to your component test Makefile
34 (see components/example/tests/Makefile for more details)
35 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.
37 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.
41 @section Component Specific Information
43 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.
47 /*-----------------------------------------------------------------------------
48 Notes on components as of February 2019 release 5.7.0.0.
50 bgpm IBM Blue Gene Q specific.
51 coretemp Linux HW Monitor, temperature and other info.
52 coretemp_freebsd FREEBSD version of HW Monitor, temperature and other info.
53 cuda CUDA events and metrics via NVIDIA CUpti interfaces.
54 emon IBM Blue Gene Q specific.
55 example Simple example component.
56 host_micpower Requires its own configure and Knights Corner (KNC) architecture.
57 infiniband Linux Infiniband stats using the sysfs interface. For OFED version < 1.4.
58 infiniband_umad Requires its own configure. Infiniband stats for OFED version >= 1.4.
59 libmsr Requires its own configure and libmsr from LLNL, for power (RAPL) read/write.
60 lmsensors Requires its own configure.
61 lustre lustre filesystem stats
62 micpower For reading power on Intel XEON PHI. (MIC)
63 mx Myricom MX (Myrinet Express) statistics.
64 net Linux network driver statistics
65 nvml Requires its own configure; monitors NVIDIA hardware (power, temp, fan speed, etc).
66 pcp Performance Co-Pilot interface.
67 perfctr OLD, only used for Linux before 2.6.31.
68 perfctr_ppc OLD, only used for Linux before 2.6.31.
69 perf_event Linux perf_event CPU counters
70 perf_event_uncore Linux perf-event CPU uncore and Northbridge
71 perfmon2 OLD, only used for Linux before 2.6.31.
72 perfmon_ia64 OLD, only used for Linux before 2.6.31.
73 powercap Linux Powercap energy measurements.
74 rapl Linux RAPL energy measurments.
75 stealtime Stealtime Filesystem statistics.
76 vmware Requires its own configure. Only runs in the VMWARE virtual environment.
1.8.15